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(ChoroplethLayer(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.

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`	ChoroplethLayer.
`linewidth` (choropleth)	`stroke_width`	ChoroplethLayer.

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`	ProportionalLayer	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`	`to_interactive`	Convenience alias for hover effect opacity.
`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 TileLayer
m.add(TileLayer(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 LabelLayer
m.add(LabelLayer(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