ferrum.themes¶

Theme class, built-in named themes, and default-theme controls.

Theme ¶

Immutable theme value class for chart styling.

Pass to Chart.theme(t) per-chart or activate process-wide via set_default_theme(t). Per-chart .theme() always wins at render time.

All keys listed in ferrum-spec.md §3.13 are plumbed end-to-end to the Rust renderer. Unknown keys raise ValueError at construction.

Parameters:

Name	Type	Description	Default
`background`	`str`	Chart background color as a CSS hex string (e.g. `"#ffffff"`). `background_color` accepted as an alias.	required
`mark_color`	`str`	Default mark fill/stroke color for marks that have no explicit color encoding.	required
`font_family`	`optional`	Default text styling for body text (axis titles, etc.).	required
`font_weight`	`optional`	Default text styling for body text (axis titles, etc.).	required
`font_color`	`optional`	Default text styling for body text (axis titles, etc.).	required
`font_size`	`optional`	Default text styling for body text (axis titles, etc.).	required
`title_font_family`	`optional`	Chart title styling. `title_anchor` ∈ {"start", "middle", "end"}. Unset values fall back to the corresponding body-text key (`title_color` → `font_color`, etc.).	required
`title_font_size`	`optional`	Chart title styling. `title_anchor` ∈ {"start", "middle", "end"}. Unset values fall back to the corresponding body-text key (`title_color` → `font_color`, etc.).	required
`title_font_weight`	`optional`	Chart title styling. `title_anchor` ∈ {"start", "middle", "end"}. Unset values fall back to the corresponding body-text key (`title_color` → `font_color`, etc.).	required
`title_color`	`optional`	Chart title styling. `title_anchor` ∈ {"start", "middle", "end"}. Unset values fall back to the corresponding body-text key (`title_color` → `font_color`, etc.).	required
`title_anchor`	`optional`	Chart title styling. `title_anchor` ∈ {"start", "middle", "end"}. Unset values fall back to the corresponding body-text key (`title_color` → `font_color`, etc.).	required
`title_offset`	`optional`	Chart title styling. `title_anchor` ∈ {"start", "middle", "end"}. Unset values fall back to the corresponding body-text key (`title_color` → `font_color`, etc.).	required
`label_font_family`	`optional`	Tick label styling. Fall back to `font_family` / `font_color`.	required
`label_color`	`optional`	Tick label styling. Fall back to `font_family` / `font_color`.	required
`grid`	`bool`	Whether to draw grid lines (default True).	required
`grid_color`	`optional`	Grid line styling. `grid_dash` is a list of dash lengths.	required
`grid_width`	`optional`	Grid line styling. `grid_dash` is a list of dash lengths.	required
`grid_dash`	`optional`	Grid line styling. `grid_dash` is a list of dash lengths.	required
`grid_opacity`	`optional`	Grid line styling. `grid_dash` is a list of dash lengths.	required
`axis_line`	`bool`	Whether to draw axis strokes (default True).	required
`axis_line_color`	`optional`	Axis and tick styling.	required
`axis_line_width`	`optional`	Axis and tick styling.	required
`tick_color`	`optional`	Axis and tick styling.	required
`tick_size`	`optional`	Axis and tick styling.	required
`tick_width`	`optional`	Axis and tick styling.	required
`point_size`	`optional`	Mark styling.	required
`point_opacity`	`optional`	Mark styling.	required
`line_stroke_width`	`optional`	Mark styling.	required
`bar_corner_radius`	`optional`	Mark styling.	required
`area_opacity`	`optional`	Mark styling.	required
`opacity`	`optional`	Mark styling.	required
`color_scheme`	`str`	Named categorical palette: one of `paper_ink` (default), `slate_citrus`, `arctic_signal`, `okabe_ito`, `tableau10`, `set1`, `set2`, `paired`, `pastel`, `dark2`. Sequential names (`viridis`, `plasma`, `magma`, `inferno`, `cividis`, `cool_blue`, `warm_ochre`, `night_blue`, `electric_lime`, `signal_blue`, `ember_orange`) and diverging names (`rdbu`, `blue_to_red`, `cyan_to_amber`, `blue_to_violet`) also accepted.	required
`sequential_scheme`	`str`	Default sequential color ramp used by heatmaps, density plots, and other continuous-color charts when no explicit `cmap` is given. Must be one of the recognized sequential/diverging names. Defaults to `"cool_blue"` (Paper Ink).	required
`diverging_scheme`	`str`	Default diverging color ramp used by correlation matrices and other diverging-color charts when no explicit `cmap` is given. Must be one of the recognized sequential/diverging names. Defaults to `"blue_to_red"` (Paper Ink).	required
`legend_orient`	`optional`	Legend layout.	required
`legend_direction`	`optional`	Legend layout.	required
`legend_title_font_size`	`optional`	Legend layout.	required
`padding`	`optional`	Spacing in pixels.	required
`axis_title_padding`	`optional`	Spacing in pixels.	required
`column_padding`	`optional`	Spacing in pixels.	required
`row_padding`	`optional`	Spacing in pixels.	required
`strip_background_color`	`optional`	Facet strip-title background color.	required

Raises:

Type	Description
`ValueError`	If any keyword argument is not in the supported key list (see `Theme._KNOWN_KEYS`).

Examples:

>>> import ferrum as fm
>>> t = fm.Theme(background="#f9f9f9", grid=False, padding=16)
>>> t2 = t.update(mark_color="#e74c3c")
>>> t2
Theme(background='#f9f9f9', grid=False, mark_color='#e74c3c', padding=16)

update ¶

update(**kwargs: Any) -> 'Theme'

Return a new Theme with the given properties overridden.

Passing None for a key removes that property from the derived theme. The source theme is unchanged (immutable).

Parameters:

Name	Type	Description	Default
`**kwargs`	`any`	Property overrides. Pass `None` to clear a property.	`{}`

Returns:

Type	Description
`Theme`	A new `Theme` with the merged properties.

Examples:

>>> import ferrum as fm
>>> base = fm.Theme(grid=False, padding=12)
>>> with_bg = base.update(background_color="#222")

to_spec_dict ¶

to_spec_dict() -> dict

Return a dict suitable for ferrum._core.render_svg(theme=...).

Resolves spec-defined fallbacks (e.g. title_color falls back to font_color if unset) and normalises the public Python alias background to the Rust binding's canonical background_color key. Rust sees a fully-resolved dict; no Option fallback chains in the binding.

set_default_theme ¶

set_default_theme(theme: Theme) -> AbstractContextManager

Set the process-default theme for all subsequent charts.

The returned object is a context manager. Use it with with to scope the default to a block (previous default is restored on __exit__). Fire-and-forget usage (without with) is also supported.

Per-chart Chart.theme(t) always overrides this process default.

Parameters:

Name	Type	Description	Default
`theme`	`Theme`	Theme to install as the process default.	required

Returns:

Type	Description
`AbstractContextManager`	Context manager that restores the prior default on `__exit__`.

Raises:

Type	Description
`TypeError`	If `theme` is not a `Theme` instance.

Examples:

Fire-and-forget:

>>> import ferrum as fm
>>> fm.set_default_theme(fm.themes.dark)

Scoped to a block:

>>> with fm.set_default_theme(fm.themes.dark):
...     chart = fm.Chart(df).mark_point().encode(x="hp", y="mpg")

get_default_theme ¶

get_default_theme() -> Theme

Return the current process-default theme.

Returns:

Type	Description
`Theme`	The currently active process-default theme. Starts as `ferrum.themes.default` (Rust renderer defaults); changes after each `set_default_theme()` call.

Examples:

>>> import ferrum as fm
>>> fm.get_default_theme()
Theme()

theme_context ¶

theme_context(theme: Theme) -> AbstractContextManager

Scope a theme to a with block — alias for set_default_theme().

Prefer this spelling over set_default_theme() when the intent is always context-manager usage (e.g. in tests or notebook cells).

Parameters:

Name	Type	Description	Default
`theme`	`Theme`	Theme to activate for the duration of the `with` block.	required

Returns:

Type	Description
`AbstractContextManager`	Context manager; restores the prior default on `__exit__`.

Examples:

>>> import ferrum as fm
>>> with fm.theme_context(fm.themes.dark):
...     chart = fm.Chart(df).mark_point().encode(x="hp", y="mpg")