yggdrasil.environ.parameters

parameters

Lazy, type-aware process parameter mapping.

:class:SystemParameters is a lazy Mapping[str, Any] over every channel a runtime exposes to a process:

• sys.argv[1:] — --key=value / --key value / --flag pairs. Positional tokens (no -- prefix) land on :attr:SystemParameters.args.
• Databricks notebook bindings — the union of dbutils.widgets values and {{job.parameters.*}} substitutions via dbutils.notebook.entry_point.getCurrentBindings(). Probed lazily: dbutils is not touched until a key actually needs it.
• os.environ — filtered by prefix when the caller asks for it.

Precedence on collision (highest wins): explicit overrides > sys.argv > Databricks bindings > env.

Typed config via subclassing

Annotate fields on a subclass to get value casting through :func:yggdrasil.data.cast.convert and attribute access::

class Config(SystemParameters):
    count: int = 1
    name: str = "default"
    verbose: bool = False

cfg = Config()         # auto-fetches from every channel
cfg.count              # int(42) from --count=42 / widget / env
cfg["name"]            # "alice"
cfg.verbose            # bool, "true"/"false" coerced

Undeclared keys come back as the raw source value (string from argv / env / widgets). Cast results are cached per-key for the lifetime of the instance.

WidgetType

Bases: Enum

Databricks notebook widget kinds used by :meth:SystemParameters.init_widgets.

SystemParameters

SystemParameters(
    mapping: Mapping[str, Any] | None = None,
    *,
    argv: list[str] | None = _UNSET,
    env_prefix: str | tuple[str, ...] = (),
    dbutils: Any = _UNSET,
    **kwargs: Any
)

Bases: Mapping

Lazy Mapping[str, Any] over sys.argv, Databricks bindings, and env.

Build via the from_* constructors — :meth:from_argv, :meth:from_dbutils, :meth:from_environ — or instantiate directly to auto-fetch from every channel. Subclass and annotate fields to get typed attribute access with cast-through-convert.

Capture source configuration; nothing is fetched until first access.

Parameters:

Name	Type	Description	Default
mapping	Mapping[str, Any] | None	Highest-precedence explicit overrides. Merged with kwargs.	None
argv	list[str] | None	... (default) → sys.argv[1:]; None → skip argv; a list[str] → parse those tokens. Argv parsing is eager because reading the list is essentially free.	_UNSET
env_prefix	str | tuple[str, ...]	Empty (default) → ignore env. Pass a prefix string or tuple to expose os.environ keys with those prefixes.	()
dbutils	Any	... (default) → auto-detect via builtins.dbutils / IPython on first access; None → skip Databricks bindings; a live handle → use it directly.	_UNSET
**kwargs	Any	Convenience for ad-hoc explicit overrides.	{}

from_ classmethod

from_(value: Any = _UNSET) -> SystemParameters

Generic dispatch — route by input shape to the right constructor.

• ... / None → fresh instance (auto-fetch from every channel).
• existing SystemParameters → identity.
• Mapping → explicit-only (argv + dbutils + env skipped).
• list / tuple of strings → :meth:from_argv.

from_argv classmethod

from_argv(argv: list[str] | None = None) -> SystemParameters

Build from argv only — skips Databricks and env.

from_dbutils classmethod

from_dbutils(*names: str) -> SystemParameters

Read Databricks notebook widget bindings via dbutils.

With no names: the full union from dbutils.notebook.entry_point.getCurrentBindings(). With names: only those widgets via dbutils.widgets.get(name).

Raises :class:RuntimeError when dbutils is not available so the miss is loud — instantiate :class:SystemParameters directly for the silent-fallback shape.

from_environ classmethod

from_environ(*prefixes: str) -> SystemParameters

Snapshot os.environ, optionally filtered by key prefix.

from_environment classmethod

from_environment() -> SystemParameters

Auto-fetch from every channel — alias for cls().

Kept as the canonical entry point for the historical NotebookConfig.from_environment() shape.

init_widgets classmethod

init_widgets(*, skip_existing: bool = True) -> None

Create a Databricks notebook widget for each declared field.

Resolves the widget shape from the field's annotation: bool → dropdown("true" / "false"), Enum → dropdown over enum values, list / set → multiselect, :class:datetime.datetime / :class:datetime.date → text widget with ISO 8601 default, everything else → text widget.

Silent no-op outside a Databricks notebook (no dbutils). Pass skip_existing=False to recreate widgets already present.

init_job classmethod

init_job(logging: bool | int | None = logging.INFO) -> SystemParameters

Initialize widgets, tweak the active Spark session, return the populated config.

Mirrors the historical NotebookConfig.init_job() entry point. Spark tweaks are silently skipped when PySpark isn't importable or no session is active.

logging controls runtime log activation on the yggdrasil logger:

• int (default logging.INFO) — set the level to that numeric value;
• True — alias for logging.INFO;
• False / None — leave the logger untouched.

A :class:logging.StreamHandler is attached only when nothing upstream is already going to render records (checked via :meth:logging.Logger.hasHandlers, which walks the propagation chain). The Databricks job runtime (and pytest harnesses) usually wire the root logger at startup; in those cases propagation alone carries the messages to the existing handler, so adding our own would double-log.

as_dict

as_dict() -> dict[str, Any]

Materialise every known key into a plain dict, applying casts.

nice_label

nice_label(name: str) -> str

Prettify a snake_case identifier into a Title Case widget label.

Splits on _ / -, title-cases each piece, and keeps tokens in :data:LABEL_ACRONYMS upper-case. Empty / all-separator input round-trips.

Examples::

nice_label("start_date_utc")    # "Start Date UTC"
nice_label("user_id")           # "User ID"
nice_label("api_url")           # "API URL"
nice_label("bidding_zone_eic")  # "Bidding Zone EIC"
nice_label("verbose")           # "Verbose"