Skip to content

ferrum.config

Process-level configuration store for ferrum defaults.

Uses contextvars.ContextVar for thread-safe, scope-bounded defaults. The defaults() context manager provides temporary overrides that revert on exit.

Precedence (highest wins):

  1. Explicit per-chart .properties()
  2. ferrum.config overrides
  3. Built-in defaults

Process-level configuration store for ferrum defaults.

Uses contextvars.ContextVar for thread-safe, scope-bounded defaults. The same pattern as set_default_theme() in ferrum.themes._defaults.

Precedence (highest wins): 1. Explicit per-chart .properties() 2. ferrum.config overrides 3. Built-in defaults

set 

set(**kwargs: Any) -> None

Set process-level configuration defaults.

Parameters:

Name Type Description Default
**kwargs Any

Key-value pairs to store. Recognized keys: width, height, renderer, max_rows, raster_threshold.

 {}

Examples:

>>> import ferrum
>>> ferrum.config.set(width=800, height=600)
>>> ferrum.config.get("width")
800

get 

get(key: str) -> Any

Get a configuration value (user-set or built-in default).

Parameters:

Name Type Description Default
key str

Configuration key.

 required

Returns:

Type Description
Any

The configured value, or the built-in default if not overridden.

Raises:

Type Description
KeyError

If key is not a recognized configuration key and has not been set by the user.

Examples:

>>> import ferrum
>>> ferrum.config.get("width")
640

defaults 

defaults(**kwargs: Any) -> AbstractContextManager

Context manager for temporary config overrides.

Restores the prior configuration state on exit.

Parameters:

Name Type Description Default
**kwargs Any

Temporary configuration overrides active within the with block.

 {}

Yields:

Type Description
None

Examples:

>>> import ferrum
>>> with ferrum.config.defaults(width=1000):
...     assert ferrum.config.get("width") == 1000
>>> assert ferrum.config.get("width") == 640

reset 

reset() -> None

Reset all config to built-in defaults.

Removes all user-set overrides so subsequent get() calls return the built-in defaults. This only affects the current context — child async tasks that already inherited a prior ContextVar snapshot retain their own copy and are not affected by this call.

Examples:

>>> import ferrum
>>> ferrum.config.set(width=1200)
>>> ferrum.config.reset()
>>> ferrum.config.get("width")
640