Skip to content

mplchart.styles

Chart styling — the runtime Styler and its spec forms.

A chart's look is set with Chart(style=...), which accepts a shipped style name (see available_styles), a matplotlib stylesheet name, a provider-prefixed name ("mpf:yahoo" for mplfinance styles, "mt:economist" for morethemes — requires that provider package), a spec mapping (stylesheet/rc/settings/aliases), or a prebuilt Styler. Styles are total — ambient rcParams never affect the chart.

Design notes in notes/styler-sketch.md, notes/styler-settings.md and notes/styler-aliases.md.

Styler

Styler(settings=(), rcparams=(), stylesheet=None, aliases=())

Runtime styling state for one canvas.

Arguments:

  • settings (dict or iterable of pairs): Mapping of flat dotted setting keys <prefix>.<facet> to values (e.g. candle.up.color, volume.alpha). Any value may be a list, which cycles per pane and key. A .color value may also be a "~"-prefixed color (snapped to the closest prop-cycle color), or the "line"/"fill" sentinels (next color from the axes prop cycle).
  • rcparams (dict or iterable of pairs): matplotlib rcParams overrides, applied via context() around artist creation.
  • stylesheet (str or Path): base matplotlib stylesheet — what plt.style.use accepts: a stock style name or an .mplstyle path — loaded via load_stylesheet and collapsed eagerly under rcparams (explicit rcparams win). Every styler is totalized over the factory template (base_template()), so the stored rcparams are always fully specified — ambient rcParams never affect a chart.
  • aliases (dict or iterable of pairs): prefix renames applied during lookup — {"sma": "overlay", "ema": "overlay"} makes every moving average draw from one overlay.color cycle. A rename, not a fallback: the pre-alias prefix is never tried, which is what keys the shared cycle correctly.

Cycle state lives in counters — a per-axes Counter of uses per key, created on first use and persisting for the lifetime of the styler (one chart) — fresh chart, fresh cycles. Axes are held weakly: when a pane is garbage-collected, its counters go with it.

available_styles

available_styles()

Names of the shipped styles — styles/lib/ is the registry.

get_styler

get_styler(style=None, *, overrides=())

Normalize a style spec into a Styler.

Arguments:

  • style: None for the default "mplchart" style, a prebuilt Styler (passed through), a shipped style name, a matplotlib stylesheet name, a provider-prefixed name ("mpf:yahoo", "mt:economist"), or a spec mapping (stylesheet/rc/settings/aliases). Every result is total: fully specified rc, no ambient inheritance.
  • overrides: settings mapping (canonical dotted keys, e.g. candle.up.color) layered on top of the style settings — whatever their source, a prebuilt Styler included.

load_stylesheet

load_stylesheet(spec)

Load an rc mapping from a matplotlib stylesheet.

Accepts what plt.style.use accepts: a stock style name (matplotlib.style.library), a path to an .mplstyle file, or the special name "default" — the factory-default template (minus non-style keys), giving an ambient-independent base. Named sheets and files return only the keys they define, so scoped application doesn't stomp the ambient theme. Values are validated by matplotlib's per-key validators, failing fast on garbage.

resolve_style

resolve_style(name)

Resolve a style name into a Styler.

Names resolve in order: shipped style (styles/lib/<name>.py, which shadows), then matplotlib stylesheet name, with provider: prefixed names ("mpf:yahoo", "mt:economist") dispatching to the matching loader module — requires that provider package.