Style Management

Helpers for discovering and applying the packaged matplotlib styles. The Style manager reads asset/mplstyle, provides preset combinations (scientific, report, minimal, presentation, poster, web, dark, and Korean variants), resets rcParams, and stacks multiple style files when needed.

Typical usage

import dartwork_mpl as dm

# Apply a preset (recommended)
dm.style.use("scientific")       # papers
dm.style.use("report")           # reports & dashboards
dm.style.use("minimal")          # Tufte-style, data-ink focus
dm.style.use("presentation")     # slides
dm.style.use("poster")           # conference posters
dm.style.use("web")              # web pages & documentation
dm.style.use("dark")             # dark backgrounds
dm.style.use("presentation-kr")  # Korean font variant

# Stack multiple styles for advanced customization
dm.style.stack(["base", "font-report", "theme-dark"])

# Inspect what a style will set
available = dm.list_styles()
style_dict = dm.load_style_dict("font-presentation")

API

Matplotlib style management utilities.

This module provides functions and classes for loading and applying matplotlib styles from the package’s built-in style library.

class dartwork_mpl.style.Style

Bases: object

Class for managing and applying multiple matplotlib styles.

This class provides functionality for loading style presets and stacking multiple styles sequentially.

Examples

>>> import dartwork_mpl as dm
>>> dm.style.use("scientific")  # Apply a single preset
>>> dm.style.stack(["base", "lang-kr"])  # Stack multiple styles

context(preset_name: str, **kwargs: float | str) → Iterator[None]

Temporarily apply a style, restoring rcParams, semantics and ownership.

Body use() calls, exceptions and nested scopes restore the immediate outer tracking at exit. Preset-only normalized values are recorded before kwargs; inherited keys remain tracked. Non-string names raise TypeError before mutation; unknown strings retain KeyError suggestions.

Parameters:

• preset_name (str) – Name of the preset to apply.

• **kwargs (float | str) – Additional rcParams to override.

Examples

>>> with dm.style.context("dark"):
...     plt.plot([1, 2, 3])

Notes

Not thread-safe: the underlying plt.rcParams mutation is process-global, and holding a lock across the yield would deadlock any body code that calls style.use. Apply styles from one thread (matplotlib itself is not thread-safe for concurrent rcParams mutation).

load_presets() → None

Load style presets from the JSON file.

Reads presets.json and stores the configuration in the instance’s presets attribute.

presets_dict() → dict[str, list[str]]

Return all available presets as a dictionary.

Returns:

Dictionary mapping preset names (keys) to their constituent style lists (values).

Return type:

dict[str, list[str]]

static presets_path() → Path

Get the path to the presets configuration file (presets.json).

Returns:

Path to the presets.json file containing combined style presets.

Return type:

Path

static stack(style_names: list[str]) → None

Stack multiple styles in order.

Applies multiple style files sequentially. Later styles override values set by earlier ones for the same keys. Detectable caller edits survive on incoming-silent keys; unchanged prior preset values reset. Preset-produced mutable values are copied before caller overrides.

Parameters:

style_names (list[str]) – List of style names to apply. Styles are applied in order, with later entries taking precedence.

Examples

>>> import dartwork_mpl as dm
>>> dm.style.stack(["base", "font-scientific", "lang-kr"])

use(preset_name: str | list[str], **kwargs: float | str) → None

Apply a preset style configuration or a list of presets.

This is the recommended way to apply styles in this module. Presets are pre-optimized combinations of styles for specific use cases. Resolve the complete request and validate overrides in isolated rcParams before font loading or changes to live style, semantics or bookkeeping. Successful requests retain the usual preset and caller-override order. Detectable native edits survive when the incoming preset is silent; incoming declarations win and current kwargs apply last. A native same-value rewrite is indistinguishable from unchanged preset residue; pass that override with or after the later switch. Explicit kwargs are known caller intent, including when equal to a preset value.

Parameters:

• preset_name (str or list of str) – Name of the preset to apply. Available presets: - “scientific”: Academic papers (default English) - “report”: Documents, reports, and dashboards - “minimal”: Tufte-style with minimal lines and ticks - “presentation”: Slide presentations - “poster”: Conference posters and large displays - “web”: Web pages and documentation - “dark”: Dark background theme - “scientific-kr”: Academic papers (Korean fonts) - “report-kr”: Reports and dashboards (Korean fonts) - “minimal-kr”: Minimal style (Korean fonts) - “presentation-kr”: Presentations (Korean fonts) - “poster-kr”: Conference posters (Korean fonts) - “web-kr”: Web pages (Korean fonts) - “dark-kr”: Dark theme (Korean fonts)

• **kwargs (float | str) – Additional rcParams to override the preset defaults (e.g., font_size=12). Both underscore (font_size) and dot (font.size) notation are supported.

Raises:

• TypeError – If a preset name or list member is not a string.

• KeyError – If the preset name is unknown or an override key is invalid.

• ValueError – If an override value fails Matplotlib’s rcParam validation. Rejected requests leave the active style and semantic tokens unchanged.

Examples

>>> import dartwork_mpl as dm
>>> dm.style.use("scientific")
>>> dm.style.use("presentation-kr", font_size=16)
>>> dm.style.use(["scientific", "dark"])  # Stack multiple presets

dartwork_mpl.style.install_twinx_patch() → None

Make Axes.twinx show the twin’s right spine at the preset line width.

dartwork-mpl presets hide the right spine, so a twin axis would otherwise have no visible axis line for its own scale. Called once by import dartwork_mpl. Idempotent: the wrapper is tagged __dm_patched__, so a repeated call (or importlib.reload) never wraps the patched method again and recurses.

dartwork_mpl.style.list_styles() → list[str]

Return a list of all available styles.

Returns:

List of style names.

Return type:

list[str]

dartwork_mpl.style.load_style_dict(name: str) → dict[str, float | str]

Read key-value pairs from an mplstyle file.

Parameters:

name (str) – Name of the style to load.

Returns:

Dictionary of style parameters. Values are converted to float where possible; otherwise they are kept as strings.

Return type:

dict[str, float | str]

Raises:

• TypeError – If the style name is not a string.

• ValueError – If the named style file does not exist.

dartwork_mpl.style.style_path(name: str) → Path

Get the path to a style file.

Parameters:

name (str) – Name of the style (e.g., ‘report’, ‘scientific’).

Returns:

Absolute path to the style file (.mplstyle).

Return type:

Path

Raises:

• TypeError – If the style name is not a string.

• ValueError – If the specified style name cannot be found.