Migration from v1 (matplotlib) to v2 (SVG)

The import statement is unchanged:

from mappyng import Map

The constructor signature is preserved. The drawing API, however, is now object-based: instead of m.add_choropleth(gdf, {...}) you build a layer and add it with m.add(Choropleth(gdf, ...)). The dict-based add_* helpers have been removed (see Quickstart). The parameter names below still apply; they are now keyword arguments of the corresponding layer class.

Layer and element names

Layers and chrome are objects added with + or m.add(...) (see Quickstart). The layer classes lost their Layer suffix; the former names were removed in mappyng 2.0 (they had emitted a DeprecationWarning since the layer classes were introduced).

Former	Current
ChoroplethLayer, CategoryLayer, ProportionalLayer, SituationLayer, LabelLayer, VectorLayer	Choropleth, Category, Proportional, Situation, Label, Vector
BasemapLayer, TileLayer, RasterLayer, GraticuleLayer	Basemap, Tile, Raster, Graticule
m.title(...), m.source(...), m.scale_bar(...), m.north_arrow(...)	Title, Source, ScaleBar, NorthArrow (the methods remain as shortcuts)
cartouche_params={0: {...}}	Insets([Inset(...), ...]) (the parameter remains)
m.add_zoom({...})	Zoom(bbox, ...)
m.add_shadow(gdf, {...})	DropShadow(gdf, ...); stdDeviation is now blur
m.add_radial_gradient(...)	RadialGradient(...), referenced with fill=gradient.url
m.to_interactive(columns=..., aliases=...)	Tooltip(columns, aliases=...) and m.render("map.html")

m.add(layer) now returns the map instead of the layer; the layer still receives its id. Vector is drawn in the cartouches by default (on_cartouches=True), like the thematic layers.

Renamed parameters

v1 parameter	v2 parameter	Notes
symbol["alpha"]	fill_opacity	Proportional and situation layers.
symbol["edgecolors"]	stroke	Proportional and situation layers.
symbol["linewidth"]	stroke_width	Proportional and situation layers.
line_color (leader)	leader_color	ProportionalLegendConfig.
line_width (leader)	leader_width	ProportionalLegendConfig.
line_style (leader)	leader_dash	SVG dasharray string instead of matplotlib line style.
line_alpha (leader)	leader_opacity	ProportionalLegendConfig.
circle_color	circle_fill	ProportionalLegendConfig.
rounding	decimals	Legend label decimal places.
edgecolor (choropleth)	stroke	Choropleth.
linewidth (choropleth)	stroke_width	Choropleth.

Removed parameters

These v1 parameters are not available in v2:

v1 parameter	Reason
symbol["marker"] (non-circle shapes in proportional)	v2 proportional symbols are always circles.
symbol["zorder"]	Z-order is managed globally by ZOrderConfig.
adjust_size	v2 uses max_radius for auto-scaling; fixed scale via reference_radius.
units (legend position)	v2 always uses SVG pixel coordinates.
PNG custom markers (situation.py)	v2 is SVG-native only. Use custom SVG files instead.

New parameters in v2

These parameters are not present in v1:

Parameter	Method / class	Description
font_scale	Map	Global font size multiplier.
reference_radius	Proportional	Fixed circle radius in SVG px (replaces reference_size).
num_values	ProportionalLegendConfig	Number of auto-generated legend values.
circle_fill_opacity	ProportionalLegendConfig	Legend circle fill opacity.
columns_n / col_gap	SituationLegendConfig	Multi-column legend layout.
hatch_style	ChoroplethLegendConfig	SVG hatch pattern for legend swatches.
hover_opacity	Tooltip	Hover effect opacity: Tooltip(columns, hover_opacity=0.7), or tooltip={"hover": {"opacity": 0.7}}. The to_interactive argument of the same name was removed in 2.0.
label_position / label_format	ChoroplethLegendConfig (horizontal)	Label centering and range formatting for horizontal legends.

Tile basemaps

v1 used contextily (matplotlib-based). v2 downloads tiles directly:

# v1
import contextily as cx
cx.add_basemap(ax, source=cx.providers.CartoDB.Positron)

# v2
from mappyng import Tile
m.add(Tile(source="cartodb_positron"))

Requires pip install mappyng[tile].

Label placement

v1 used adjustText (matplotlib). v2 uses a pure Python simulated-annealing implementation with geometric obstacle avoidance:

# v1
m.add_toponyms(gdf, column="nom", max_labels=20)

# v2
from mappyng import Label
m.add(Label(gdf, column="nom", max_labels=20, n_sweeps=50))

Exceptions

v2 exposes a typed exception hierarchy not present in v1:

from mappyng.errors import MapError, DataError, RenderError