Configuration¶

class mappyng.config.ConfigManager[source]¶

Bases: object

Manager for style configurations and colormaps.

static add_style(name, config)[source]¶

Parameters:

name (str) – Style name (used as style= in Map).
config (StyleConfig or dict) – A StyleConfig instance, or a flat dict of overrides (same format as STYLES presets). When a dict is passed it is merged on top of the "classic" preset before building the StyleConfig.

Return type:

None

static get_colormap(name, num_classes)[source]¶

Return a list of hex color strings for a built-in colormap.

Parameters:

name (str) – Colormap name. Available: "YlOrRd", "Blues", "Greens", "Reds", "RdYlGn".
num_classes (int) – Number of classes (4-7).

Return type:

List[str]

Returns:

list of str – Hex color strings, length == num_classes.

Raises:

ValueError – If name or num_classes is not available.

static get_style(style_input='classic')[source]¶

Build a Style from a preset name or a dict.

Parameters:

style_input (str or dict) –

str, a registered preset name (e.g. "classic", "modern").
dict, custom overrides. If the dict contains a "base" key its value selects the starting preset (default "classic"); all other keys override the corresponding STYLES values before building.

Return type:

Style

Returns:

Style

class mappyng.config.Style(config)[source]¶

Bases: object

Wrapper providing dict-like access to StyleConfig.

__init__(config)¶

config: StyleConfig¶

get(key, default=None)[source]¶

Return type:: Any

class mappyng.config.StyleConfig(name, title=<factory>, legend=<factory>, edge=<factory>, basemap=<factory>, scale=<factory>, source=<factory>, z_order=<factory>, layout_edge_color='#A3A5C3')[source]¶

Bases: object

Complete style configuration.

__init__(name, title=<factory>, legend=<factory>, edge=<factory>, basemap=<factory>, scale=<factory>, source=<factory>, z_order=<factory>, layout_edge_color='#A3A5C3')¶

basemap: BasemapConfig¶

edge: EdgeConfig¶

layout_edge_color: str = '#A3A5C3'¶

legend: LegendConfig¶

name: str¶

scale: ScaleConfig¶

source: SourceConfig¶

title: FontConfig¶

z_order: ZOrderConfig¶

class mappyng.config.ZOrderConfig(OCEAN=-50, RASTER=-5, GRATICULES=-2, SHADOW=1, BASEMAP=0, LAYER_BACKGROUND=5, CHOROPLETH=10, SITUATION=20, PROPORTIONAL=30, TOPONYME=40, LAYER_TOP=50, LAYOUT=200)[source]¶

Bases: object

Z-order for SVG layer stacking (higher = on top).

BASEMAP: int = 0¶

CHOROPLETH: int = 10¶

GRATICULES: int = -2¶

LAYER_BACKGROUND: int = 5¶

LAYER_TOP: int = 50¶

LAYOUT: int = 200¶

OCEAN: int = -50¶

PROPORTIONAL: int = 30¶

RASTER: int = -5¶

SHADOW: int = 1¶

SITUATION: int = 20¶

TOPONYME: int = 40¶

__init__(OCEAN=-50, RASTER=-5, GRATICULES=-2, SHADOW=1, BASEMAP=0, LAYER_BACKGROUND=5, CHOROPLETH=10, SITUATION=20, PROPORTIONAL=30, TOPONYME=40, LAYER_TOP=50, LAYOUT=200)¶

class mappyng.config.FontConfig(family='sans-serif', size=10, weight='normal', color='#6c757d', opacity=1.0)[source]¶

Bases: object

Font settings.

__init__(family='sans-serif', size=10, weight='normal', color='#6c757d', opacity=1.0)¶

color: str = '#6c757d'¶

family: str = 'sans-serif'¶

opacity: float = 1.0¶

size: int = 10¶

weight: str = 'normal'¶

class mappyng.config.LegendConfig(title=<factory>, text=<factory>, hatch_style='///', hatch_color='#bcb8b1', spacing=0.01, location='lower left', x=0.15, y=-0.12, circle_stroke='black', circle_stroke_width=0.8, circle_spacing=0.02, title_max_chars=35)[source]¶

Bases: object

Legend settings.

__init__(title=<factory>, text=<factory>, hatch_style='///', hatch_color='#bcb8b1', spacing=0.01, location='lower left', x=0.15, y=-0.12, circle_stroke='black', circle_stroke_width=0.8, circle_spacing=0.02, title_max_chars=35)¶

circle_spacing: float = 0.02¶

circle_stroke: str = 'black'¶

circle_stroke_width: float = 0.8¶

hatch_color: str = '#bcb8b1'¶

hatch_style: str = '///'¶

location: str = 'lower left'¶

spacing: float = 0.01¶

text: FontConfig¶

title: FontConfig¶

title_max_chars: int = 35¶

x: float = 0.15¶

y: float = -0.12¶

class mappyng.config.BasemapConfig(fill_color='#ebeced', edge=<factory>)[source]¶

Bases: object

Basemap polygon styling.

__init__(fill_color='#ebeced', edge=<factory>)¶

edge: EdgeConfig¶

fill_color: str = '#ebeced'¶

class mappyng.config.ScaleConfig(color='#6c757d', location='lower right', pad=1.0)[source]¶

Bases: object

Scale bar settings.

__init__(color='#6c757d', location='lower right', pad=1.0)¶

color: str = '#6c757d'¶

location: str = 'lower right'¶

pad: float = 1.0¶

class mappyng.config.SourceConfig(font=<factory>, x=1.01, y=0.01, rotation=90)[source]¶

Bases: object

Source text settings.

__init__(font=<factory>, x=1.01, y=0.01, rotation=90)¶

font: FontConfig¶

rotation: float = 90¶

x: float = 1.01¶

y: float = 0.01¶

mappyng.config.COLORMAP_DEFS = dict, built-in colormap definitions (YlOrRd, Blues, Greens, Reds, RdYlGn × 4-7 classes)¶

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object’s

(key, value) pairs

dict(iterable) -> new dictionary initialized as if via:: d = {} for k, v in iterable:

d[k] = v
dict(**kwargs) -> new dictionary initialized with the name=value pairs: in the keyword argument list. For example: dict(one=1, two=2)

Legend configuration classes¶

class mappyng.legend.BaseLegendConfig(title=None, title_fontsize=None, title_fontcolor=None, title_fontweight=None, title_fontfamily=None, title_max_chars=35, title_offset_x=0.0, title_offset_y=0.0, subtitle=None, subtitle_fontsize=None, subtitle_fontcolor=None, subtitle_fontweight=None, subtitle_fontfamily=None, fontsize=None, fontcolor=None, fontweight=None, fontfamily=None, hatch_color=None, hatch_style=None, spacing=0.01, position=None, frame=None)[source]

Bases: object

Shared configuration fields for all legend types.

All fields can be passed as keys in the legend dict of ChoroplethLayer, ProportionalLayer, and SituationLayer. None values are filled from the active style at render time.

title

Legend title text.

Type:: str or None

title_fontsize

Title font size. Defaults to style value.

Type:: int or None

title_fontcolor

Title font color.

Type:: str or None

title_fontweight

Title font weight (e.g. "bold").

Type:: str or None

title_fontfamily

Title font family.

Type:: str or None

title_max_chars

Maximum characters per line before title wraps (default 35).

Type:: int

title_offset_x

Additional horizontal offset for the title in SVG px (default 0).

Type:: float

title_offset_y

Additional vertical offset for the title in SVG px (default 0).

Type:: float

subtitle

Optional subtitle rendered below the title.

Type:: str or None

subtitle_fontsize

Subtitle font size.

Type:: int or None

subtitle_fontcolor

Subtitle font color.

Type:: str or None

subtitle_fontweight

Subtitle font weight.

Type:: str or None

subtitle_fontfamily

Subtitle font family.

Type:: str or None

fontsize

Legend item label font size.

Type:: int or None

fontcolor

Legend item label color.

Type:: str or None

fontweight

Legend item label weight.

Type:: str or None

fontfamily

Legend item label font family.

Type:: str or None

hatch_color

Hatch pattern color (used for choropleth swatch hatching).

Type:: str or None

hatch_style

Hatch pattern style. Available: "///" , "\\", "xxx", "..." , "|||", "---".

Type:: str or None

spacing

Extra vertical spacing added to the auto-computed legend position as a fraction of the content height (default 0.01).

Type:: float

position

Manual legend position as {"x": frac, "y": frac} where (0, 0) = top-left and (1, 1) = bottom-right of the content area. When None, position is computed automatically.

Type:: dict or None

frame

Background frame behind the legend. False/None = no frame, True = frame with defaults, dict = frame with overrides (see LegendFrameConfig).

Type:: bool or dict or None

__init__(title=None, title_fontsize=None, title_fontcolor=None, title_fontweight=None, title_fontfamily=None, title_max_chars=35, title_offset_x=0.0, title_offset_y=0.0, subtitle=None, subtitle_fontsize=None, subtitle_fontcolor=None, subtitle_fontweight=None, subtitle_fontfamily=None, fontsize=None, fontcolor=None, fontweight=None, fontfamily=None, hatch_color=None, hatch_style=None, spacing=0.01, position=None, frame=None)

fontcolor: str | None = None

fontfamily: str | None = None

fontsize: int | None = None

fontweight: str | None = None

frame: Any = None

hatch_color: str | None = None

hatch_style: str | None = None

position: Any = None

resolve_defaults(style, font_scale=1.0)[source]

Fill None fields from the active style.

Parameters:: font_scale (float) – Multiplier applied to all resolved font sizes (default 1.0 = no change).
Return type:: None

spacing: float = 0.01

subtitle: str | None = None

subtitle_fontcolor: str | None = None

subtitle_fontfamily: str | None = None

subtitle_fontsize: int | None = None

subtitle_fontweight: str | None = None

title: str | None = None

title_fontcolor: str | None = None

title_fontfamily: str | None = None

title_fontsize: int | None = None

title_fontweight: str | None = None

title_max_chars: int = 35

title_offset_x: float = 0.0: Horizontal offset applied to the legend title (pixels). Positive = right.

title_offset_y: float = 0.0: Vertical offset applied to the legend title (pixels). Positive = down.

class mappyng.legend.LegendFrameConfig(enabled=False, fill='#ffffff', fill_opacity=0.85, stroke='#cccccc', stroke_width=0.5, border_radius=4.0, padding=8.0, padding_top=None, padding_right=None, padding_bottom=None, padding_left=None, shadow=False, shadow_dx=1.0, shadow_dy=1.0, shadow_blur=3.0, shadow_opacity=0.15)[source]

Bases: object

Configuration for the optional legend background frame.

Pass as frame=True (defaults) or frame={...} (overrides) in the legend params dict.

enabled

Show the frame (default False).

Type:: bool

fill

Frame background color.

Type:: str

fill_opacity

Frame background opacity 0-1.

Type:: float

stroke

Frame border color.

Type:: str

stroke_width

Frame border width in SVG px.

Type:: float

border_radius

Frame corner radius in SVG px.

Type:: float

padding

Uniform inner padding on all four sides (SVG px). Used as fallback when individual side overrides are not set.

Type:: float

padding_top

Top padding override (SVG px). Falls back to padding when None.

Type:: float or None

padding_right

Right padding override (SVG px). Falls back to padding when None.

Type:: float or None

padding_bottom

Bottom padding override (SVG px). Falls back to padding when None.

Type:: float or None

padding_left

Left padding override (SVG px). Falls back to padding when None.

Type:: float or None

shadow

Add a drop shadow behind the frame.

Type:: bool

shadow_dx

Shadow horizontal offset (SVG px).

Type:: float

shadow_dy

Shadow vertical offset (SVG px).

Type:: float

shadow_blur

Shadow blur radius (SVG px).

Type:: float

shadow_opacity

Shadow opacity 0-1.

Type:: float

__init__(enabled=False, fill='#ffffff', fill_opacity=0.85, stroke='#cccccc', stroke_width=0.5, border_radius=4.0, padding=8.0, padding_top=None, padding_right=None, padding_bottom=None, padding_left=None, shadow=False, shadow_dx=1.0, shadow_dy=1.0, shadow_blur=3.0, shadow_opacity=0.15)

border_radius: float = 4.0

effective_padding()[source]

Return (top, right, bottom, left) padding values.

Return type:: tuple

enabled: bool = False

fill: str = '#ffffff'

fill_opacity: float = 0.85

padding: float = 8.0

padding_bottom: float | None = None

padding_left: float | None = None

padding_right: float | None = None

padding_top: float | None = None

shadow: bool = False

shadow_blur: float = 3.0

shadow_dx: float = 1.0

shadow_dy: float = 1.0

shadow_opacity: float = 0.15

stroke: str = '#cccccc'

stroke_width: float = 0.5

class mappyng.choropleth.ChoroplethLegendConfig(title=None, title_fontsize=None, title_fontcolor=None, title_fontweight=None, title_fontfamily=None, title_max_chars=35, title_offset_x=0.0, title_offset_y=0.0, subtitle=None, subtitle_fontsize=None, subtitle_fontcolor=None, subtitle_fontweight=None, subtitle_fontfamily=None, fontsize=None, fontcolor=None, fontweight=None, fontfamily=None, hatch_color=None, hatch_style=None, spacing=0.01, position=None, frame=None, decimals=1, orientation='vertical', swatch_size=None, swatch_width=30.0, swatch_height=None, swatch_spacing=10.0, label_rotation=-33.0, label_position='border', label_format='value', label_anchor='middle', label_margin=5.0, nodata_gap=25, nodata_label_gap=4, nodata_label=None, vertical_swatch_width=20.0, vertical_swatch_height=None, vertical_label_gap=6.0, labels=None, decimal_sep='.', thousands_sep=' ', histogram=False, histogram_bins=20, histogram_width=80.0, histogram_height=50.0, histogram_gap=16.0)[source]

Bases: BaseLegendConfig

Choropleth-specific legend configuration.

Inherits all shared fields from BaseLegendConfig. Pass as the legend dict in add_choropleth().

decimals

Number of decimal places for class boundary labels (default 1).

Type:: int

orientation

Legend layout: "horizontal" (default) or "vertical".

Type:: str

swatch_width

Width of each color swatch in horizontal mode (SVG px).

Type:: float

swatch_size

Sets the swatch width for both horizontal and vertical modes at once. Height is always derived as swatch_size / phi. When None, swatch_width and vertical_swatch_width are used independently.

Type:: float or None

swatch_height

Height of each color swatch in horizontal mode. Defaults to swatch_width / phi (golden ratio).

Type:: float or None

swatch_spacing

Gap between swatches (SVG px).

Type:: float

label_rotation

Rotation of bin labels in degrees (0 = horizontal, default 0).

Type:: float

label_position

Horizontal legend label placement: "border" (default, n+1 labels at swatch edges) or "center" (n labels centered inside each swatch).

Type:: str

label_format

Label content when label_position="center": "value" (lower bound only) or "range" ([min, max] interval).

Type:: str

label_anchor

SVG text-anchor for rotated labels: "middle" (default) or "end".

Type:: str

label_margin

Gap in SVG px between the bottom of swatches and label baseline.

Type:: float

nodata_gap

Horizontal gap between the last class swatch and the N/A swatch.

Type:: float

nodata_label_gap

Gap between the N/A swatch right edge and its label.

Type:: float

nodata_label

Custom label for missing-value swatch. Defaults to "N/A".

Type:: str or None

vertical_swatch_width

Swatch width in vertical mode (SVG px).

Type:: float

vertical_swatch_height

Swatch height in vertical mode. Defaults to vertical_swatch_width / phi (golden ratio).

Type:: float or None

vertical_label_gap

Gap between swatch right edge and label in vertical mode.

Type:: float

labels

Custom label list that replaces auto-generated range labels. Must have length == num_classes.

Type:: list of str or None

__init__(title=None, title_fontsize=None, title_fontcolor=None, title_fontweight=None, title_fontfamily=None, title_max_chars=35, title_offset_x=0.0, title_offset_y=0.0, subtitle=None, subtitle_fontsize=None, subtitle_fontcolor=None, subtitle_fontweight=None, subtitle_fontfamily=None, fontsize=None, fontcolor=None, fontweight=None, fontfamily=None, hatch_color=None, hatch_style=None, spacing=0.01, position=None, frame=None, decimals=1, orientation='vertical', swatch_size=None, swatch_width=30.0, swatch_height=None, swatch_spacing=10.0, label_rotation=-33.0, label_position='border', label_format='value', label_anchor='middle', label_margin=5.0, nodata_gap=25, nodata_label_gap=4, nodata_label=None, vertical_swatch_width=20.0, vertical_swatch_height=None, vertical_label_gap=6.0, labels=None, decimal_sep='.', thousands_sep=' ', histogram=False, histogram_bins=20, histogram_width=80.0, histogram_height=50.0, histogram_gap=16.0)

decimal_sep: str = '.': Decimal separator. Use ‘,’ for French convention (e.g. ‘12,5’).

decimals: int = 1

histogram: bool = False: Draw a mini distribution histogram to the right of the legend block.

histogram_bins: int = 20: Number of bars in the histogram.

histogram_gap: float = 16.0: Horizontal gap between legend block and histogram (SVG px).

histogram_height: float = 50.0: Height of the histogram area (SVG px).

histogram_width: float = 80.0: Width of the histogram area (SVG px).

label_anchor: str = 'middle'

‘end’ or ‘middle’ (default). With ‘middle’, vertical offset is auto-adjusted to prevent overlap.

Type:: SVG text-anchor for rotated labels

label_format: str = 'value'

‘value’ (min bound) or ‘range’ ([min, max]).

Type:: Label content in center mode

label_margin: float = 5.0: Gap in pixels between the bottom of the swatches and the label baseline.

label_position: str = 'border'

‘border’ (default, n+1 at swatch edges) or ‘center’ (n labels centered inside each swatch).

Type:: Horizontal legend label placement

label_rotation: float = -33.0

labels: List[str] | None = None

nodata_gap: float = 25: Horizontal gap in pixels between the last class swatch and the N/A swatch.

nodata_label: str | None = None: Custom label for the N/A swatch. Defaults to D.LEGEND_NODATA_LABEL (‘N/A’).

nodata_label_gap: float = 4: Horizontal gap in pixels between the N/A swatch right edge and its label.

orientation: str = 'vertical'

resolve_defaults(style, font_scale=1.0)[source]

Fill None fields from the active style.

Parameters:: font_scale (float) – Multiplier applied to all resolved font sizes (default 1.0 = no change).
Return type:: None

swatch_height: float | None = None

swatch_size: float | None = None

swatch_spacing: float = 10.0

swatch_width: float = 30.0

thousands_sep: str = ' ': Thousands separator. Default narrow space (‘1 234’); use ‘’ for none.

vertical_label_gap: float = 6.0

vertical_swatch_height: float | None = None

vertical_swatch_width: float = 20.0

class mappyng.proportional.ProportionalLegendConfig(title=None, title_fontsize=None, title_fontcolor=None, title_fontweight=None, title_fontfamily=None, title_max_chars=35, title_offset_x=0.0, title_offset_y=0.0, subtitle=None, subtitle_fontsize=None, subtitle_fontcolor=None, subtitle_fontweight=None, subtitle_fontfamily=None, fontsize=None, fontcolor=None, fontweight=None, fontfamily=None, hatch_color=None, hatch_style=None, spacing=0.01, position=None, frame=None, orientation='nested', values=None, num_values=3, decimals=0, number_format='space', circle_fill=None, circle_fill_opacity=0.4, circle_stroke='black', circle_stroke_width=0.8, circle_spacing=None, label_gap=5, leader_color='#999999', leader_width=0.5, leader_dash='2,2', leader_opacity=0.6)[source]

Bases: BaseLegendConfig

Proportional-symbol legend configuration.

Inherits all shared fields from BaseLegendConfig. Pass as the legend dict in add_proportional().

orientation

Legend layout: "nested" (default, concentric circles), "vertical" (stacked), or "horizontal" (side by side).

Type:: str

values

Explicit data values to show in the legend. Auto-generated if None.

Type:: list of float or None

num_values

Number of auto-generated legend values (default 4).

Type:: int

decimals

Decimal places for value labels (default 0).

Type:: int

number_format

Thousands separator: "space" (default, narrow no-break space) or "none" (no separator).

Type:: str

circle_fill

Legend circle fill color override. Uses the layer fill if None.

Type:: str or None

circle_fill_opacity

Legend circle fill opacity 0-1.

Type:: float

circle_stroke

Legend circle stroke color.

Type:: str

circle_stroke_width

Legend circle stroke width (SVG px).

Type:: float

circle_spacing

Fixed horizontal gap between circles in horizontal mode (SVG px). Auto-computed from circle sizes if None.

Type:: float or None

label_gap

Gap between circle edge and label text (SVG px).

Type:: float

leader_color

Leader line color in nested mode.

Type:: str

leader_width

Leader line stroke width (SVG px).

Type:: float

leader_dash

Leader line SVG stroke-dasharray (e.g. "4 2").

Type:: str

leader_opacity

Leader line opacity 0-1.

Type:: float

__init__(title=None, title_fontsize=None, title_fontcolor=None, title_fontweight=None, title_fontfamily=None, title_max_chars=35, title_offset_x=0.0, title_offset_y=0.0, subtitle=None, subtitle_fontsize=None, subtitle_fontcolor=None, subtitle_fontweight=None, subtitle_fontfamily=None, fontsize=None, fontcolor=None, fontweight=None, fontfamily=None, hatch_color=None, hatch_style=None, spacing=0.01, position=None, frame=None, orientation='nested', values=None, num_values=3, decimals=0, number_format='space', circle_fill=None, circle_fill_opacity=0.4, circle_stroke='black', circle_stroke_width=0.8, circle_spacing=None, label_gap=5, leader_color='#999999', leader_width=0.5, leader_dash='2,2', leader_opacity=0.6)

circle_fill: str | None = None

circle_fill_opacity: float = 0.4

circle_spacing: float | None = None: Fixed horizontal gap between circles in horizontal mode (SVG px). Overrides default.

circle_stroke: str = 'black'

circle_stroke_width: float = 0.8

decimals: int = 0

label_gap: float = 5

leader_color: str = '#999999'

leader_dash: str = '2,2'

leader_opacity: float = 0.6: Opacity of leader lines in nested legend (0-1).

leader_width: float = 0.5

num_values: int = 3

number_format: str = 'space'

"space" (default) or "none".

Type:: Thousands separator

orientation: str = 'nested'

values: List[float] | None = None

class mappyng.situation.SituationLegendConfig(title=None, title_fontsize=None, title_fontcolor=None, title_fontweight=None, title_fontfamily=None, title_max_chars=35, title_offset_x=0.0, title_offset_y=0.0, subtitle=None, subtitle_fontsize=None, subtitle_fontcolor=None, subtitle_fontweight=None, subtitle_fontfamily=None, fontsize=None, fontcolor=None, fontweight=None, fontfamily=None, hatch_color=None, hatch_style=None, spacing=0.01, position=None, frame=None, marker_size=10.0, label_gap=6.0, row_spacing=4.0, col_gap=20.0, columns_n=1)[source]

Bases: BaseLegendConfig

Legend configuration for situation (categorical marker) layers.

Inherits all shared fields from BaseLegendConfig. Pass as the legend dict in SituationLayer.

marker_size

Size of the marker preview in the legend (SVG px, default 10.0).

Type:: float

label_gap

Gap between marker preview and label text (SVG px, default 6.0).

Type:: float

row_spacing

Vertical gap between legend rows (SVG px, default 4.0).

Type:: float

col_gap

Horizontal gap between columns in multi-column layout (SVG px, default 20.0).

Type:: float

columns_n

Number of columns in the legend (default 1).

Type:: int

__init__(title=None, title_fontsize=None, title_fontcolor=None, title_fontweight=None, title_fontfamily=None, title_max_chars=35, title_offset_x=0.0, title_offset_y=0.0, subtitle=None, subtitle_fontsize=None, subtitle_fontcolor=None, subtitle_fontweight=None, subtitle_fontfamily=None, fontsize=None, fontcolor=None, fontweight=None, fontfamily=None, hatch_color=None, hatch_style=None, spacing=0.01, position=None, frame=None, marker_size=10.0, label_gap=6.0, row_spacing=4.0, col_gap=20.0, columns_n=1)

col_gap: float = 20.0: Horizontal gap between columns in multi-column layout (SVG px).

columns_n: int = 1: Number of columns in the legend (default 1 = single column).

label_gap: float = 6.0

marker_size: float = 10.0

row_spacing: float = 4.0