whence

Typed configuration that remembers where it came from.

Every configuration library can tell you a value. whence can tell you why it has that value — which file, which line, which profile, and what it overrode.

$ whence myapp explain db.host --profile prod
db.host = 'db.internal'
  <- config/app.prod.yaml:4:9 [profile=prod]
  shadowed:
      overrides                      - not set
      env                            - not set
      dotenv:.env                    - not found
      secrets-dir                    - not found
      config/app.yaml:2:9            = 'localhost'
      defaults                       = 'localhost'

Spring has this (Origin, /actuator/env), HOCON has it (ConfigOrigin), Rust's figment has it (Metadata). Python has not — so that is what whence is for. It is a complement to pydantic, not a replacement: point it at a pydantic model or a frozen dataclass and it handles the layering, the provenance and the diagnostics.

Install

pip install whence          # env, .env, TOML, JSON, .properties, XML
pip install whence[yaml]    # + YAML

The core has no runtime dependencies. Every format but YAML is parsed on the standard library.

Quick start

from dataclasses import dataclass
from whence import Config, Secret, load_settings, settings


@settings(prefix="db")
@dataclass(frozen=True, slots=True)
class Db:
    host: str = "localhost"
    port: int = 5432
    password: Secret | None = None


cfg = Config.load(app="myapp", profiles=["prod"])
db = load_settings(Db, cfg)

Loading is synchronous. Configuration is read once, before the application runs, so there is no event loop for an await to yield to; a Source that reaches the network blocks the startup it is already part of.

Receiving configuration

The code above fetches: it holds a Config and binds. @from_config is the other direction, for the edges where a framework calls your function and there is no call site to thread a Config through:

from typing import Annotated
from whence import Injected, Value, current_config, from_config


@from_config
def connect(
    *,
    db: Annotated[Db, Injected],
    retries: Annotated[int, Value("http.retries")] = 3,
) -> Conn: ...


with current_config(cfg):
    connect()  # db bound from the `db` subtree, retries from the key
    connect(retries=1)  # an explicit argument always wins

Both markers live in Annotated, so the annotation stays exact and the default stays a real default — retries is 3 when nothing sets the key, and a call that supplies every marked argument needs no ambient configuration at all. The ambient value is a ContextVar, so it is per-task rather than per-process: one tenant's configuration per request, concurrently, and nothing leaking into a worker thread that should have been passed a Config explicitly.

A marked parameter must be keyword-only, which is checked at decoration — filling happens through kwargs, so an argument passed positionally would be filled twice.

Precedence

Seven named layers, highest first. whence <app> explain <key> prints them.

Layer	Source
overrides	values passed to Config.load(overrides=...)
cli	--set a.b=c in sys.argv
env	MYAPP_DB__HOST, plus _FILE indirection
dotenv	.env.{profile}, then .env
secrets-dir	/run/secrets, one file per key
files	app.{profile}.{ext}, then app.{ext}
defaults	schema defaults

The secrets directory sits above configuration files, unlike pydantic-settings: a secret an operator deliberately mounted is deployment truth, not a fallback.

Discovery

Nothing about where configuration lives is hard-coded. Five steps, each reported by whence <app> discovery even when it finds nothing:

1. an explicit file= — missing is an error
2. $MYAPP_CONFIG
3. each root in path
4. the per-user configuration directory
5. pyproject.toml → [tool.myapp]

Discovery(
    app="myapp",
    path=(Path("config"), Path("/etc/myapp")),
    formats=("toml", "yaml"),
    prefix="MYAPP_",
    search_parents=True,
    mode="layer",
)

Two files matching in the same root raise AmbiguousConfigError rather than resolving by preference — the case Spring left unspecified for years. Across different roots there is no ambiguity: the earlier root wins, and both appear in explain.

Profiles

Profile files overlay the base file, profile groups expand, and the invariant is that profiles gate documents; they never reorder sources. A profiled key in a low-precedence source can never outrank an unprofiled key in a higher one — the rule that eliminates the "why did dev configuration win in production?" class of incident.

Interpolation

${a.b}, ${a.b:-default} (POSIX :-, so ${url:-redis://h:6379} is unambiguous), ${?a.b} (the key disappears when undefined), ${env:VAR}, ${file:/run/secrets/pw}, and \${literal}. Resolved lazily after the merge, so a base file can reference a key a higher source supplies. There is no global "ignore unresolvable" switch: that is the setting that turns a startup failure into a literal ${db.password} reaching a database driver.

Errors

Every problem in one run, each carrying its origin:

whence.BindError: 2 errors

  Property: db.port
     Value: 'eighty'
    Origin: config/app.prod.yaml:4:9 [profile=prod]
    Reason: could not convert to int
  Shadowed: config/app.yaml:5:9 = 5432

  Property: db.max_retires
     Value: 3
    Origin: config/app.yaml:8:3
    Reason: no such setting - did you mean 'db.max_retries'?

Action: correct the configuration, or run `whence explain <key>`.

No message ever contains the value it rejected — a rejected value may be a secret, and an exception is the most widely logged object in a program.

Reloading

There isn't any. To change configuration, redeploy.

Config is immutable and loaded once. A library that also owns a poll loop owns a thread or an event loop, and the generational swap it needs is where every prior art went wrong: .NET's ChangeToken.OnChange has fired twice per save since 2017 and ships a hash-and-backoff workaround in its own documentation, Go viper's WatchConfig carries a documented data race, and koanf's Watch() is not safe against concurrent reads. Each of those is a property of mutating an object other code is holding — so whence never holds one.

A fresh Config.load(...) does see the current state of the world, including through a Kubernetes ConfigMap's ..data symlink. kubelet republishes by pointing that symlink at a new timestamped directory; an inotify watch on the config file is bound to an inode that has been unlinked and goes permanently deaf, which is the single most common way this is got wrong — Python's watchdog fails it silently because it hardcodes IN_DONT_FOLLOW. Reading resolves the symlink afresh every time. A container test builds kubelet's exact layout with real symlinks and asserts the swap is seen (make test-docker).

If a running process must pick up a change, call Config.load(...) again on a schedule you own and swap your own pointer. That is a handful of lines, it lives where your concurrency model already is, and whence stays out of it.

Cross-platform

Configuration directories follow each platform's own convention: XDG on Linux, ~/Library/Application Support on macOS (plus XDG when explicitly set), %LOCALAPPDATA% then %APPDATA% on Windows. Windows folds environment variable names to upper case before any library code runs, and whence's naming scheme is bijective under that fold, so the same code and the same tests behave identically everywhere. Files are read as UTF-8 with a BOM tolerated, CRLF parses, and case-insensitive filesystems do not produce phantom ambiguities.

API reference

whence

whence -- typed configuration that remembers where it came from.

Every configuration library can tell you a value. whence can tell you why it has that value: which file, which line, which profile, and what it overrode.

>>> from whence import Config
>>> cfg = Config.from_mapping({"db": {"host": "localhost"}})
>>> cfg.get("db.host")
'localhost'

Loading is synchronous and happens once, before the application runs: there is no event loop to protect at that point, so there is nothing for an await to yield to. A source that reaches the network simply blocks the startup it is already part of.

The public API is everything listed in __all__; anything else is internal and may change without a major version bump.

Injected module-attribute

Injected = _Inject()

Annotation metadata: bind this parameter's own type from configuration.

Annotated[Db, Injected] binds Db from the subtree its @settings prefix names. Binding always happens, so a default on such a parameter would be unreachable -- @from_config rejects one at decoration rather than ignoring it.

MASK module-attribute

MASK = '********'

What a redacted value renders as.

Binder

Bases: Protocol

Turns a subtree of resolved configuration into a typed object.

Source code in src/whence/binding/__init__.py

class Binder(Protocol):
    """Turns a subtree of resolved configuration into a typed object."""

    def supports(self, target: type) -> bool:
        """Report whether this binder handles the target.

        Args:
            target: The schema class.

        Returns:
            True when it does.
        """
        ...

    def declared(self, target: type, prefix: KeyPath = ()) -> set[KeyPath]:
        """List the key paths the target declares.

        Args:
            target: The schema class.
            prefix: The path it sits at.

        Returns:
            Every declared key path.
        """
        ...

    def bind(
        self,
        target: type,
        values: Mapping[KeyPath, Tracked],
        prefix: KeyPath = (),
        problems: list[Any] | None = None,
    ) -> Any:
        """Construct the target.

        Args:
            target: The schema class.
            values: Flat resolved values.
            prefix: The subtree to read.
            problems: A list to append problems to.

        Returns:
            The instance, or ``None`` on failure.
        """
        ...

supports

supports(target: type) -> bool

Report whether this binder handles the target.

Parameters:

Name	Type	Description	Default
target	type	The schema class.	required

Returns:

Type	Description
bool	True when it does.

Source code in src/whence/binding/__init__.py

def supports(self, target: type) -> bool:
    """Report whether this binder handles the target.

    Args:
        target: The schema class.

    Returns:
        True when it does.
    """
    ...

declared

declared(
    target: type, prefix: KeyPath = ()
) -> set[KeyPath]

List the key paths the target declares.

Parameters:

Name	Type	Description	Default
target	type	The schema class.	required
prefix	KeyPath	The path it sits at.	()

Returns:

Type	Description
set[KeyPath]	Every declared key path.

Source code in src/whence/binding/__init__.py

def declared(self, target: type, prefix: KeyPath = ()) -> set[KeyPath]:
    """List the key paths the target declares.

    Args:
        target: The schema class.
        prefix: The path it sits at.

    Returns:
        Every declared key path.
    """
    ...

bind

bind(
    target: type,
    values: Mapping[KeyPath, Tracked],
    prefix: KeyPath = (),
    problems: list[Any] | None = None,
) -> Any

Construct the target.

Parameters:

Name	Type	Description	Default
target	type	The schema class.	required
values	Mapping[KeyPath, Tracked]	Flat resolved values.	required
prefix	KeyPath	The subtree to read.	()
problems	list[Any] | None	A list to append problems to.	None

Returns:

Type	Description
Any	The instance, or None on failure.

Source code in src/whence/binding/__init__.py

def bind(
    self,
    target: type,
    values: Mapping[KeyPath, Tracked],
    prefix: KeyPath = (),
    problems: list[Any] | None = None,
) -> Any:
    """Construct the target.

    Args:
        target: The schema class.
        values: Flat resolved values.
        prefix: The subtree to read.
        problems: A list to append problems to.

    Returns:
        The instance, or ``None`` on failure.
    """
    ...

Problem dataclass

One thing wrong with the configuration.

Attributes:

Name	Type	Description
key	str	The dotted key.
value	Any	The offending value, redacted before rendering.
origin	Origin | None	Where the value came from.
reason	str	What is wrong with it.
shadowed	tuple[str, ...]	Entries this value overrode, for context.

Source code in src/whence/binding/__init__.py

@dataclass(frozen=True, slots=True)
class Problem:
    """One thing wrong with the configuration.

    Attributes:
        key: The dotted key.
        value: The offending value, redacted before rendering.
        origin: Where the value came from.
        reason: What is wrong with it.
        shadowed: Entries this value overrode, for context.
    """

    key: str
    value: Any
    origin: Origin | None
    reason: str
    shadowed: tuple[str, ...] = ()

SourceChain

A mutable, ordered collection of named sources, highest precedence first.

Source code in src/whence/chain.py

class SourceChain:
    """A mutable, ordered collection of named sources, highest precedence first."""

    def __init__(self, sources: Sequence[Source] = ()) -> None:
        """Build a chain.

        Args:
            sources: Sources in precedence order, highest first.
        """
        self._sources: list[Source] = list(sources)

    def __iter__(self) -> Iterator[Source]:
        """Iterate sources highest precedence first."""
        return iter(self._sources)

    def __len__(self) -> int:
        """Return the number of sources."""
        return len(self._sources)

    def __contains__(self, name: object) -> bool:
        """Report whether a source with this name is present."""
        return any(self._name(s) == name for s in self._sources)

    @staticmethod
    def _name(source: Source) -> str:
        """Read a source's name."""
        return str(getattr(source, "name", type(source).__name__))

    def names(self) -> tuple[str, ...]:
        """List source names, highest precedence first.

        Returns:
            The names.
        """
        return tuple(self._name(s) for s in self._sources)

    def _index(self, name: str) -> int:
        """Find a source by name.

        Raises:
            ConfigError: If no source carries that name.
        """
        for i, source in enumerate(self._sources):
            if self._name(source) == name:
                return i
        msg = f"no source named {name!r}; the chain holds {', '.join(self.names()) or '<nothing>'}"
        raise ConfigError(msg)

    def add_first(self, source: Source) -> "SourceChain":
        """Insert a source at the highest precedence.

        Args:
            source: The source.

        Returns:
            This chain, for chaining.
        """
        self._sources.insert(0, source)
        return self

    def add_last(self, source: Source) -> "SourceChain":
        """Append a source at the lowest precedence.

        Args:
            source: The source.

        Returns:
            This chain, for chaining.
        """
        self._sources.append(source)
        return self

    def add_before(self, relative: str, source: Source) -> "SourceChain":
        """Insert a source immediately above a named one.

        Args:
            relative: The name to insert above.
            source: The source.

        Returns:
            This chain, for chaining.
        """
        self._sources.insert(self._index(relative), source)
        return self

    def add_after(self, relative: str, source: Source) -> "SourceChain":
        """Insert a source immediately below a named one.

        Args:
            relative: The name to insert below.
            source: The source.

        Returns:
            This chain, for chaining.
        """
        self._sources.insert(self._index(relative) + 1, source)
        return self

    def replace(self, name: str, source: Source) -> Source:
        """Swap a source in place, keeping its precedence.

        This is how a source is decorated rather than displaced -- wrapping the
        environment source to decrypt values, for instance.

        Args:
            name: The source to replace.
            source: The replacement.

        Returns:
            The source that was removed.
        """
        i = self._index(name)
        previous = self._sources[i]
        self._sources[i] = source
        return previous

    def remove(self, name: str) -> Source:
        """Drop a source by name.

        Args:
            name: The source to remove.

        Returns:
            The source that was removed.
        """
        return self._sources.pop(self._index(name))

    def insert_by_ordinal(self, source: Source, ordinal: int) -> "SourceChain":
        """Insert a source by integer rank, higher winning.

        Args:
            source: The source, which must carry an ``ordinal`` attribute for
                comparison against existing entries.
            ordinal: The rank.

        Returns:
            This chain, for chaining.
        """
        for i, existing in enumerate(self._sources):
            if int(getattr(existing, "ordinal", 0)) < ordinal:
                self._sources.insert(i, source)
                return self
        self._sources.append(source)
        return self

    def load(self) -> Resolved:
        """Load every source and merge the layers.

        Returns:
            The winning values, the shadow chain, and every layer consulted.
        """
        layers = [source.load() for source in self._sources]
        return resolve(layers)

__init__

__init__(sources: Sequence[Source] = ()) -> None

Build a chain.

Parameters:

Name	Type	Description	Default
sources	Sequence[Source]	Sources in precedence order, highest first.	()

Source code in src/whence/chain.py

def __init__(self, sources: Sequence[Source] = ()) -> None:
    """Build a chain.

    Args:
        sources: Sources in precedence order, highest first.
    """
    self._sources: list[Source] = list(sources)

__iter__

__iter__() -> Iterator[Source]

Iterate sources highest precedence first.

Source code in src/whence/chain.py

def __iter__(self) -> Iterator[Source]:
    """Iterate sources highest precedence first."""
    return iter(self._sources)

__len__

__len__() -> int

Return the number of sources.

Source code in src/whence/chain.py

def __len__(self) -> int:
    """Return the number of sources."""
    return len(self._sources)

__contains__

__contains__(name: object) -> bool

Report whether a source with this name is present.

Source code in src/whence/chain.py

def __contains__(self, name: object) -> bool:
    """Report whether a source with this name is present."""
    return any(self._name(s) == name for s in self._sources)

names

names() -> tuple[str, ...]

List source names, highest precedence first.

Returns:

Type	Description
tuple[str, ...]	The names.

Source code in src/whence/chain.py

def names(self) -> tuple[str, ...]:
    """List source names, highest precedence first.

    Returns:
        The names.
    """
    return tuple(self._name(s) for s in self._sources)

add_first

add_first(source: Source) -> SourceChain

Insert a source at the highest precedence.

Parameters:

Name	Type	Description	Default
source	Source	The source.	required

Returns:

Type	Description
SourceChain	This chain, for chaining.

Source code in src/whence/chain.py

def add_first(self, source: Source) -> "SourceChain":
    """Insert a source at the highest precedence.

    Args:
        source: The source.

    Returns:
        This chain, for chaining.
    """
    self._sources.insert(0, source)
    return self

add_last

add_last(source: Source) -> SourceChain

Append a source at the lowest precedence.

Parameters:

Name	Type	Description	Default
source	Source	The source.	required

Returns:

Type	Description
SourceChain	This chain, for chaining.

Source code in src/whence/chain.py

def add_last(self, source: Source) -> "SourceChain":
    """Append a source at the lowest precedence.

    Args:
        source: The source.

    Returns:
        This chain, for chaining.
    """
    self._sources.append(source)
    return self

add_before

add_before(relative: str, source: Source) -> SourceChain

Insert a source immediately above a named one.

Parameters:

Name	Type	Description	Default
relative	str	The name to insert above.	required
source	Source	The source.	required

Returns:

Type	Description
SourceChain	This chain, for chaining.

Source code in src/whence/chain.py

def add_before(self, relative: str, source: Source) -> "SourceChain":
    """Insert a source immediately above a named one.

    Args:
        relative: The name to insert above.
        source: The source.

    Returns:
        This chain, for chaining.
    """
    self._sources.insert(self._index(relative), source)
    return self

add_after

add_after(relative: str, source: Source) -> SourceChain

Insert a source immediately below a named one.

Parameters:

Name	Type	Description	Default
relative	str	The name to insert below.	required
source	Source	The source.	required

Returns:

Type	Description
SourceChain	This chain, for chaining.

Source code in src/whence/chain.py

def add_after(self, relative: str, source: Source) -> "SourceChain":
    """Insert a source immediately below a named one.

    Args:
        relative: The name to insert below.
        source: The source.

    Returns:
        This chain, for chaining.
    """
    self._sources.insert(self._index(relative) + 1, source)
    return self

replace

replace(name: str, source: Source) -> Source

Swap a source in place, keeping its precedence.

This is how a source is decorated rather than displaced -- wrapping the environment source to decrypt values, for instance.

Parameters:

Name	Type	Description	Default
name	str	The source to replace.	required
source	Source	The replacement.	required

Returns:

Type	Description
Source	The source that was removed.

Source code in src/whence/chain.py

def replace(self, name: str, source: Source) -> Source:
    """Swap a source in place, keeping its precedence.

    This is how a source is decorated rather than displaced -- wrapping the
    environment source to decrypt values, for instance.

    Args:
        name: The source to replace.
        source: The replacement.

    Returns:
        The source that was removed.
    """
    i = self._index(name)
    previous = self._sources[i]
    self._sources[i] = source
    return previous

remove

remove(name: str) -> Source

Drop a source by name.

Parameters:

Name	Type	Description	Default
name	str	The source to remove.	required

Returns:

Type	Description
Source	The source that was removed.

Source code in src/whence/chain.py

def remove(self, name: str) -> Source:
    """Drop a source by name.

    Args:
        name: The source to remove.

    Returns:
        The source that was removed.
    """
    return self._sources.pop(self._index(name))

insert_by_ordinal

insert_by_ordinal(
    source: Source, ordinal: int
) -> SourceChain

Insert a source by integer rank, higher winning.

Parameters:

Name	Type	Description	Default
source	Source	The source, which must carry an ordinal attribute for comparison against existing entries.	required
ordinal	int	The rank.	required

Returns:

Type	Description
SourceChain	This chain, for chaining.

Source code in src/whence/chain.py

def insert_by_ordinal(self, source: Source, ordinal: int) -> "SourceChain":
    """Insert a source by integer rank, higher winning.

    Args:
        source: The source, which must carry an ``ordinal`` attribute for
            comparison against existing entries.
        ordinal: The rank.

    Returns:
        This chain, for chaining.
    """
    for i, existing in enumerate(self._sources):
        if int(getattr(existing, "ordinal", 0)) < ordinal:
            self._sources.insert(i, source)
            return self
    self._sources.append(source)
    return self

load

load() -> Resolved

Load every source and merge the layers.

Returns:

Type	Description
Resolved	The winning values, the shadow chain, and every layer consulted.

Source code in src/whence/chain.py

def load(self) -> Resolved:
    """Load every source and merge the layers.

    Returns:
        The winning values, the shadow chain, and every layer consulted.
    """
    layers = [source.load() for source in self._sources]
    return resolve(layers)

Config

Resolved configuration, plus the provenance of everything in it.

A Config is immutable. Reloading builds a new one and swaps it, which is the only design that cannot expose a half-updated object: .NET's in-place IOptionsMonitor fires twice per save and Go viper's watcher carries a documented data race, and both problems are properties of mutating in place.

Source code in src/whence/config.py

class Config:
    """Resolved configuration, plus the provenance of everything in it.

    A ``Config`` is immutable. Reloading builds a new one and swaps it, which is
    the only design that cannot expose a half-updated object: .NET's in-place
    ``IOptionsMonitor`` fires twice per save and Go viper's watcher carries a
    documented data race, and both problems are properties of mutating in place.
    """

    def __init__(
        self,
        resolved: Resolved,
        *,
        plan: DiscoveryPlan | None = None,
        profiles: Sequence[str] = (),
        discovery: Discovery | None = None,
    ) -> None:
        """Wrap an already-resolved merge.

        Args:
            resolved: The merged values and shadow records.
            plan: The discovery plan that produced the file sources.
            profiles: The active profiles, in increasing precedence.
            discovery: The discovery settings used.
        """
        self._resolved = resolved
        self.plan = plan
        self.profiles = tuple(profiles)
        self.discovery = discovery

    # ------------------------------------------------------------------ build

    @classmethod
    def load(
        cls,
        app: str | None = None,
        *,
        discovery: Discovery | None = None,
        profiles: Sequence[str] | None = None,
        groups: Mapping[str, Sequence[str]] | None = None,
        overrides: Mapping[str, Any] | None = None,
        argv: Sequence[str] | None = None,
        defaults: Mapping[str, Any] | None = None,
        environ: Mapping[str, str] | None = None,
        aliases: Mapping[str, str] | None = None,
        cwd: Path | None = None,
        platform: Platform | None = None,
        expand: bool = True,
    ) -> "Config":
        """Discover, load and merge every source.

        Args:
            app: The application name; shorthand for ``Discovery(app=...)``.
            discovery: Full discovery settings, if ``app`` is not enough.
            profiles: Active profiles; falls back to the profiles variable.
            groups: Profile group definitions.
            overrides: Values that outrank every source.
            argv: Command-line arguments to scan for ``--set key=value``. Pass
                ``()`` to disable, or leave as ``None`` to read ``sys.argv``.
            defaults: Values every source outranks.
            environ: The environment to read; defaults to ``os.environ``.
            aliases: An explicit map from variable name to dotted key, for the
                cases convention does not cover. An explicit, greppable table
                beats implicit name mangling.
            cwd: The directory discovery starts from.
            platform: Override the platform, for cross-platform tests.
            expand: Whether to expand ``${...}`` placeholders.

        Returns:
            The resolved configuration.

        Raises:
            ConfigError: If discovery or any source fails.
        """
        settings = discovery or Discovery(app=app or "app")
        env = os.environ if environ is None else environ
        active = active_profiles(profiles, environ=env, var=settings.profiles_env, groups=groups)
        plan = settings.plan(profiles=active, environ=env, cwd=cwd, platform=platform)
        base_dir = Path.cwd() if cwd is None else cwd

        chain = SourceChain()
        if overrides:
            chain.add_last(MappingSource(overrides, name="overrides"))
        if argv is None or argv:
            chain.add_last(ArgvSource(argv))
        chain.add_last(
            EnvSource(
                settings.env_prefix,
                environ=env,
                aliases=aliases,
                # These say where to look, not what to load.
                exclude=(settings.config_var, settings.profiles_env),
            )
        )
        for path in settings.dotenv:
            base = path if path.is_absolute() else base_dir / path
            for profile in reversed(active):
                chain.add_last(
                    DotEnvSource(
                        base.with_name(f"{base.name}.{profile}"),
                        settings.env_prefix,
                        name=f"dotenv:{base.name}.{profile}",
                    )
                )
            chain.add_last(DotEnvSource(base, settings.env_prefix, name=f"dotenv:{base.name}"))
        if settings.secrets_dir is not None:
            chain.add_last(SecretsDirSource(settings.secrets_dir))
        for source in settings.file_sources(plan):
            chain.add_last(source)
        if settings.table:
            chain.add_last(PyProjectSource(base_dir / "pyproject.toml", settings.table))
        if defaults:
            chain.add_last(MappingSource(defaults, name="defaults", locator="<defaults>"))

        merged = chain.load()
        if expand:
            merged = replace(merged, values=interpolate(merged.values, environ=env))
        return cls(merged, plan=plan, profiles=active, discovery=settings)

    @classmethod
    def from_mapping(cls, data: Mapping[str, Any], *, name: str = "overrides") -> "Config":
        """Build a configuration from a single mapping, for tests and defaults.

        Args:
            data: Nested or flat configuration values.
            name: The layer name.

        Returns:
            The resolved configuration.
        """
        source = MappingSource(data, name=name)
        return cls(resolve([Layer(name, source._entries, found=bool(data))]))

    # ------------------------------------------------------------------- read

    @property
    def values(self) -> Mapping[KeyPath, Tracked]:
        """The winning tracked value for every key.

        Returns:
            Flat key paths to tracked values.
        """
        return self._resolved.values

    def _tracked(self, key: str) -> Tracked | None:
        """Look a key up by its canonical path."""
        return self._resolved.values.get(canonical(key))

    def __contains__(self, key: str) -> bool:
        """Report whether a key has a value."""
        return canonical(key) in self._resolved.values

    def __getitem__(self, key: str) -> Any:
        """Return a value, raising if it is absent."""
        return self.require(key)

    def get(self, key: str, default: Any = None, *, type_: Any = None) -> Any:
        """Return a value, or a default.

        The second positional argument is the default, as it is on ``dict`` and
        ``os.environ``: ``cfg.get("db.port", 5432)`` means what it looks like.
        Coercion is the named option, because asking for it is the rarer case.

        Args:
            key: A dotted key.
            default: Returned when the key is absent. Never coerced -- it is
                already a Python value.
            type_: Coerce to this type when given.

        Returns:
            The value, coerced if asked.
        """
        tracked = self._tracked(key)
        if tracked is None:
            return default
        if type_ is None:
            return tracked.value
        return coerce(tracked.value, type_)

    def require(self, key: str, *, type_: Any = None) -> Any:
        """Return a value, raising a helpful error if it is absent.

        Args:
            key: A dotted key.
            type_: Coerce to this type when given.

        Returns:
            The value.

        Raises:
            MissingKeyError: If nothing supplies the key.
        """
        value = self.get(key, _MISSING, type_=type_)
        if value is _MISSING:
            consulted = ", ".join(layer.name for layer in self._resolved.layers)
            msg = f"{key!r} is not set. Consulted: {consulted or '<no sources>'}"
            raise MissingKeyError(msg)
        return value

    def origin(self, key: str) -> Origin | None:
        """Return where a value came from.

        Args:
            key: A dotted key.

        Returns:
            Its origin, or ``None`` if the key is absent.
        """
        tracked = self._tracked(key)
        return None if tracked is None else tracked.origin

    # --------------------------------------------------------------- diagnose

    def explain(self, key: str) -> str:
        """Describe where a value came from and what it overrode.

        Every source is listed, including the ones that had nothing to say,
        because absence is information: "the environment variable is not set" is
        usually the answer someone is looking for.

        Args:
            key: A dotted key.

        Returns:
            A multi-line report.
        """
        path = canonical(key)
        dotted = join(path)
        winner = self._resolved.values.get(path)
        if winner is None:
            consulted = [
                f"      {layer.name:<30} - {'no value' if layer.found else 'not found'}"
                for layer in self._resolved.layers
            ]
            return "\n".join([f"{dotted} is not set", "  consulted:", *consulted])

        lines = [
            f"{dotted} = {sanitize(dotted, winner.value)!r}",
            f"  <- {winner.origin}",
        ]
        losers = dict(self._resolved.shadowed.get(path, ()))
        below: list[str] = []
        seen_winner = False
        for layer in self._resolved.layers:
            if not seen_winner and layer.entries.get(path) is winner:
                seen_winner = True
                continue
            tracked = losers.get(layer.name)
            if tracked is not None:
                below.append(f"      {layer.name:<30} = {sanitize(dotted, tracked.value)!r}")
            else:
                below.append(
                    f"      {layer.name:<30} - {'not set' if layer.found else 'not found'}"
                )
        # A single-source configuration has nothing under the winner, and a bare
        # "shadowed:" with no list under it reads as a truncated report.
        if below:
            lines.append("  shadowed:")
            lines.extend(below)
        return "\n".join(lines)

    def discovery_report(self) -> str:
        """Describe how configuration files were searched for.

        Returns:
            A multi-line report, or a note that discovery was not run.
        """
        if self.plan is None or self.discovery is None:
            return "no discovery was run for this configuration"
        head = (
            f"app={self.discovery.app}  prefix={self.discovery.env_prefix}  "
            f"profiles=[{', '.join(self.profiles)}]  mode={self.discovery.mode}"
        )
        return f"{head}\n{self.plan.render()}"

    def dump(self, *, reveal: bool = False) -> dict[str, Any]:
        """Return every value, redacted unless asked otherwise.

        Args:
            reveal: Skip redaction. Only ever pass this deliberately.

        Returns:
            Dotted keys to values.
        """
        out: dict[str, Any] = {}
        for path, tracked in sorted(self._resolved.values.items()):
            dotted = join(path)
            out[dotted] = tracked.value if reveal else sanitize(dotted, tracked.value)
        return out

    def as_dict(self) -> dict[str, Any]:
        """Return the resolved values as a plain nested dictionary.

        Provenance is dropped, which is the point: this is the shape to hand to
        something that only wants the data, such as a validator whence has no
        binder for.

        Returns:
            Nested plain Python values.
        """
        return unflatten({path: tracked.value for path, tracked in self._resolved.values.items()})

    def origins(self) -> dict[str, Origin]:
        """Return the origin of every value.

        Returns:
            Dotted keys to origins.
        """
        return {join(path): tracked.origin for path, tracked in self._resolved.values.items()}

    # ------------------------------------------------------------------ shape

    def bind(self, target: type, *, prefix: str | KeyPath = (), strict: bool | None = None) -> Any:
        """Bind a subtree onto a typed schema.

        Args:
            target: A dataclass, or a pydantic model when pydantic is installed.
            prefix: The subtree to read; defaults to the schema's own
                ``@settings`` prefix when it has one.
            strict: Whether a key nothing declared is an error. Defaults to
                whatever ``@settings`` recorded on the class.

        Returns:
            An instance of ``target``.

        Raises:
            BindError: If anything failed, listing every problem at once.
        """
        declared = getattr(target, "__whence_prefix__", None)
        chosen: str | KeyPath | Sequence[str] = prefix
        if prefix == () and declared is not None:
            chosen = declared
        # An empty prefix means the root, not an empty key segment: `@settings()`
        # with no argument binds the whole tree.
        if not isinstance(chosen, str):
            path: KeyPath = tuple(chosen)
        elif chosen:
            path = canonical(chosen)
        else:
            path = ()
        if strict is None:
            strict = bool(getattr(target, "__whence_strict__", True))
        return _binding.bind(
            target,
            self._resolved.values,
            prefix=path,
            shadowed=self._resolved.shadowed,
            strict=strict,
        )

    def with_fallback(self, other: "Config") -> "Config":
        """Layer another configuration underneath this one.

        This is how a library ships defaults that an application can override.
        HOCON calls it ``withFallback``, and figment separates it from ``merge``
        because "replace" and "fill in the gaps" are genuinely different
        operations. whence has both: the source chain merges, and this fills
        gaps -- a key already set here keeps its value and its origin.

        Args:
            other: The configuration to fall back to.

        Returns:
            A new configuration.
        """
        merged = resolve([*self._resolved.layers, *other._resolved.layers])
        return Config(merged, plan=self.plan, profiles=self.profiles, discovery=self.discovery)

    def __repr__(self) -> str:
        """Summarise without printing any values."""
        return (
            f"Config({len(self._resolved.values)} keys from "
            f"{len(self._resolved.layers)} sources, profiles={list(self.profiles)})"
        )

values property

values: Mapping[KeyPath, Tracked]

The winning tracked value for every key.

Returns:

Type	Description
Mapping[KeyPath, Tracked]	Flat key paths to tracked values.

__init__

__init__(
    resolved: Resolved,
    *,
    plan: DiscoveryPlan | None = None,
    profiles: Sequence[str] = (),
    discovery: Discovery | None = None,
) -> None

Wrap an already-resolved merge.

Parameters:

Name	Type	Description	Default
resolved	Resolved	The merged values and shadow records.	required
plan	DiscoveryPlan | None	The discovery plan that produced the file sources.	None
profiles	Sequence[str]	The active profiles, in increasing precedence.	()
discovery	Discovery | None	The discovery settings used.	None

Source code in src/whence/config.py

def __init__(
    self,
    resolved: Resolved,
    *,
    plan: DiscoveryPlan | None = None,
    profiles: Sequence[str] = (),
    discovery: Discovery | None = None,
) -> None:
    """Wrap an already-resolved merge.

    Args:
        resolved: The merged values and shadow records.
        plan: The discovery plan that produced the file sources.
        profiles: The active profiles, in increasing precedence.
        discovery: The discovery settings used.
    """
    self._resolved = resolved
    self.plan = plan
    self.profiles = tuple(profiles)
    self.discovery = discovery

load classmethod

load(
    app: str | None = None,
    *,
    discovery: Discovery | None = None,
    profiles: Sequence[str] | None = None,
    groups: Mapping[str, Sequence[str]] | None = None,
    overrides: Mapping[str, Any] | None = None,
    argv: Sequence[str] | None = None,
    defaults: Mapping[str, Any] | None = None,
    environ: Mapping[str, str] | None = None,
    aliases: Mapping[str, str] | None = None,
    cwd: Path | None = None,
    platform: Platform | None = None,
    expand: bool = True,
) -> Config

Discover, load and merge every source.

Parameters:

Name	Type	Description	Default
app	str | None	The application name; shorthand for Discovery(app=...).	None
discovery	Discovery | None	Full discovery settings, if app is not enough.	None
profiles	Sequence[str] | None	Active profiles; falls back to the profiles variable.	None
groups	Mapping[str, Sequence[str]] | None	Profile group definitions.	None
overrides	Mapping[str, Any] | None	Values that outrank every source.	None
argv	Sequence[str] | None	Command-line arguments to scan for --set key=value. Pass () to disable, or leave as None to read sys.argv.	None
defaults	Mapping[str, Any] | None	Values every source outranks.	None
environ	Mapping[str, str] | None	The environment to read; defaults to os.environ.	None
aliases	Mapping[str, str] | None	An explicit map from variable name to dotted key, for the cases convention does not cover. An explicit, greppable table beats implicit name mangling.	None
cwd	Path | None	The directory discovery starts from.	None
platform	Platform | None	Override the platform, for cross-platform tests.	None
expand	bool	Whether to expand ${...} placeholders.	True

Returns:

Type	Description
Config	The resolved configuration.

Raises:

Type	Description
ConfigError	If discovery or any source fails.

Source code in src/whence/config.py

@classmethod
def load(
    cls,
    app: str | None = None,
    *,
    discovery: Discovery | None = None,
    profiles: Sequence[str] | None = None,
    groups: Mapping[str, Sequence[str]] | None = None,
    overrides: Mapping[str, Any] | None = None,
    argv: Sequence[str] | None = None,
    defaults: Mapping[str, Any] | None = None,
    environ: Mapping[str, str] | None = None,
    aliases: Mapping[str, str] | None = None,
    cwd: Path | None = None,
    platform: Platform | None = None,
    expand: bool = True,
) -> "Config":
    """Discover, load and merge every source.

    Args:
        app: The application name; shorthand for ``Discovery(app=...)``.
        discovery: Full discovery settings, if ``app`` is not enough.
        profiles: Active profiles; falls back to the profiles variable.
        groups: Profile group definitions.
        overrides: Values that outrank every source.
        argv: Command-line arguments to scan for ``--set key=value``. Pass
            ``()`` to disable, or leave as ``None`` to read ``sys.argv``.
        defaults: Values every source outranks.
        environ: The environment to read; defaults to ``os.environ``.
        aliases: An explicit map from variable name to dotted key, for the
            cases convention does not cover. An explicit, greppable table
            beats implicit name mangling.
        cwd: The directory discovery starts from.
        platform: Override the platform, for cross-platform tests.
        expand: Whether to expand ``${...}`` placeholders.

    Returns:
        The resolved configuration.

    Raises:
        ConfigError: If discovery or any source fails.
    """
    settings = discovery or Discovery(app=app or "app")
    env = os.environ if environ is None else environ
    active = active_profiles(profiles, environ=env, var=settings.profiles_env, groups=groups)
    plan = settings.plan(profiles=active, environ=env, cwd=cwd, platform=platform)
    base_dir = Path.cwd() if cwd is None else cwd

    chain = SourceChain()
    if overrides:
        chain.add_last(MappingSource(overrides, name="overrides"))
    if argv is None or argv:
        chain.add_last(ArgvSource(argv))
    chain.add_last(
        EnvSource(
            settings.env_prefix,
            environ=env,
            aliases=aliases,
            # These say where to look, not what to load.
            exclude=(settings.config_var, settings.profiles_env),
        )
    )
    for path in settings.dotenv:
        base = path if path.is_absolute() else base_dir / path
        for profile in reversed(active):
            chain.add_last(
                DotEnvSource(
                    base.with_name(f"{base.name}.{profile}"),
                    settings.env_prefix,
                    name=f"dotenv:{base.name}.{profile}",
                )
            )
        chain.add_last(DotEnvSource(base, settings.env_prefix, name=f"dotenv:{base.name}"))
    if settings.secrets_dir is not None:
        chain.add_last(SecretsDirSource(settings.secrets_dir))
    for source in settings.file_sources(plan):
        chain.add_last(source)
    if settings.table:
        chain.add_last(PyProjectSource(base_dir / "pyproject.toml", settings.table))
    if defaults:
        chain.add_last(MappingSource(defaults, name="defaults", locator="<defaults>"))

    merged = chain.load()
    if expand:
        merged = replace(merged, values=interpolate(merged.values, environ=env))
    return cls(merged, plan=plan, profiles=active, discovery=settings)

from_mapping classmethod

from_mapping(
    data: Mapping[str, Any], *, name: str = "overrides"
) -> Config

Build a configuration from a single mapping, for tests and defaults.

Parameters:

Name	Type	Description	Default
data	Mapping[str, Any]	Nested or flat configuration values.	required
name	str	The layer name.	'overrides'

Returns:

Type	Description
Config	The resolved configuration.

Source code in src/whence/config.py

@classmethod
def from_mapping(cls, data: Mapping[str, Any], *, name: str = "overrides") -> "Config":
    """Build a configuration from a single mapping, for tests and defaults.

    Args:
        data: Nested or flat configuration values.
        name: The layer name.

    Returns:
        The resolved configuration.
    """
    source = MappingSource(data, name=name)
    return cls(resolve([Layer(name, source._entries, found=bool(data))]))

__contains__

__contains__(key: str) -> bool

Report whether a key has a value.

Source code in src/whence/config.py

def __contains__(self, key: str) -> bool:
    """Report whether a key has a value."""
    return canonical(key) in self._resolved.values

__getitem__

__getitem__(key: str) -> Any

Return a value, raising if it is absent.

Source code in src/whence/config.py

def __getitem__(self, key: str) -> Any:
    """Return a value, raising if it is absent."""
    return self.require(key)

get

get(
    key: str, default: Any = None, *, type_: Any = None
) -> Any

Return a value, or a default.

The second positional argument is the default, as it is on dict and os.environ: cfg.get("db.port", 5432) means what it looks like. Coercion is the named option, because asking for it is the rarer case.

Parameters:

Name	Type	Description	Default
key	str	A dotted key.	required
default	Any	Returned when the key is absent. Never coerced -- it is already a Python value.	None
type_	Any	Coerce to this type when given.	None

Returns:

Type	Description
Any	The value, coerced if asked.

Source code in src/whence/config.py

def get(self, key: str, default: Any = None, *, type_: Any = None) -> Any:
    """Return a value, or a default.

    The second positional argument is the default, as it is on ``dict`` and
    ``os.environ``: ``cfg.get("db.port", 5432)`` means what it looks like.
    Coercion is the named option, because asking for it is the rarer case.

    Args:
        key: A dotted key.
        default: Returned when the key is absent. Never coerced -- it is
            already a Python value.
        type_: Coerce to this type when given.

    Returns:
        The value, coerced if asked.
    """
    tracked = self._tracked(key)
    if tracked is None:
        return default
    if type_ is None:
        return tracked.value
    return coerce(tracked.value, type_)

require

require(key: str, *, type_: Any = None) -> Any

Return a value, raising a helpful error if it is absent.

Parameters:

Name	Type	Description	Default
key	str	A dotted key.	required
type_	Any	Coerce to this type when given.	None

Returns:

Type	Description
Any	The value.

Raises:

Type	Description
MissingKeyError	If nothing supplies the key.

Source code in src/whence/config.py

def require(self, key: str, *, type_: Any = None) -> Any:
    """Return a value, raising a helpful error if it is absent.

    Args:
        key: A dotted key.
        type_: Coerce to this type when given.

    Returns:
        The value.

    Raises:
        MissingKeyError: If nothing supplies the key.
    """
    value = self.get(key, _MISSING, type_=type_)
    if value is _MISSING:
        consulted = ", ".join(layer.name for layer in self._resolved.layers)
        msg = f"{key!r} is not set. Consulted: {consulted or '<no sources>'}"
        raise MissingKeyError(msg)
    return value

origin

origin(key: str) -> Origin | None

Return where a value came from.

Parameters:

Name	Type	Description	Default
key	str	A dotted key.	required

Returns:

Type	Description
Origin | None	Its origin, or None if the key is absent.

Source code in src/whence/config.py

def origin(self, key: str) -> Origin | None:
    """Return where a value came from.

    Args:
        key: A dotted key.

    Returns:
        Its origin, or ``None`` if the key is absent.
    """
    tracked = self._tracked(key)
    return None if tracked is None else tracked.origin

explain

explain(key: str) -> str

Describe where a value came from and what it overrode.

Every source is listed, including the ones that had nothing to say, because absence is information: "the environment variable is not set" is usually the answer someone is looking for.

Parameters:

Name	Type	Description	Default
key	str	A dotted key.	required

Returns:

Type	Description
str	A multi-line report.

Source code in src/whence/config.py

def explain(self, key: str) -> str:
    """Describe where a value came from and what it overrode.

    Every source is listed, including the ones that had nothing to say,
    because absence is information: "the environment variable is not set" is
    usually the answer someone is looking for.

    Args:
        key: A dotted key.

    Returns:
        A multi-line report.
    """
    path = canonical(key)
    dotted = join(path)
    winner = self._resolved.values.get(path)
    if winner is None:
        consulted = [
            f"      {layer.name:<30} - {'no value' if layer.found else 'not found'}"
            for layer in self._resolved.layers
        ]
        return "\n".join([f"{dotted} is not set", "  consulted:", *consulted])

    lines = [
        f"{dotted} = {sanitize(dotted, winner.value)!r}",
        f"  <- {winner.origin}",
    ]
    losers = dict(self._resolved.shadowed.get(path, ()))
    below: list[str] = []
    seen_winner = False
    for layer in self._resolved.layers:
        if not seen_winner and layer.entries.get(path) is winner:
            seen_winner = True
            continue
        tracked = losers.get(layer.name)
        if tracked is not None:
            below.append(f"      {layer.name:<30} = {sanitize(dotted, tracked.value)!r}")
        else:
            below.append(
                f"      {layer.name:<30} - {'not set' if layer.found else 'not found'}"
            )
    # A single-source configuration has nothing under the winner, and a bare
    # "shadowed:" with no list under it reads as a truncated report.
    if below:
        lines.append("  shadowed:")
        lines.extend(below)
    return "\n".join(lines)

discovery_report

discovery_report() -> str

Describe how configuration files were searched for.

Returns:

Type	Description
str	A multi-line report, or a note that discovery was not run.

Source code in src/whence/config.py

def discovery_report(self) -> str:
    """Describe how configuration files were searched for.

    Returns:
        A multi-line report, or a note that discovery was not run.
    """
    if self.plan is None or self.discovery is None:
        return "no discovery was run for this configuration"
    head = (
        f"app={self.discovery.app}  prefix={self.discovery.env_prefix}  "
        f"profiles=[{', '.join(self.profiles)}]  mode={self.discovery.mode}"
    )
    return f"{head}\n{self.plan.render()}"

dump

dump(*, reveal: bool = False) -> dict[str, Any]

Return every value, redacted unless asked otherwise.

Parameters:

Name	Type	Description	Default
reveal	bool	Skip redaction. Only ever pass this deliberately.	False

Returns:

Type	Description
dict[str, Any]	Dotted keys to values.

Source code in src/whence/config.py

def dump(self, *, reveal: bool = False) -> dict[str, Any]:
    """Return every value, redacted unless asked otherwise.

    Args:
        reveal: Skip redaction. Only ever pass this deliberately.

    Returns:
        Dotted keys to values.
    """
    out: dict[str, Any] = {}
    for path, tracked in sorted(self._resolved.values.items()):
        dotted = join(path)
        out[dotted] = tracked.value if reveal else sanitize(dotted, tracked.value)
    return out

as_dict

as_dict() -> dict[str, Any]

Return the resolved values as a plain nested dictionary.

Provenance is dropped, which is the point: this is the shape to hand to something that only wants the data, such as a validator whence has no binder for.

Returns:

Type	Description
dict[str, Any]	Nested plain Python values.

Source code in src/whence/config.py

def as_dict(self) -> dict[str, Any]:
    """Return the resolved values as a plain nested dictionary.

    Provenance is dropped, which is the point: this is the shape to hand to
    something that only wants the data, such as a validator whence has no
    binder for.

    Returns:
        Nested plain Python values.
    """
    return unflatten({path: tracked.value for path, tracked in self._resolved.values.items()})

origins

origins() -> dict[str, Origin]

Return the origin of every value.

Returns:

Type	Description
dict[str, Origin]	Dotted keys to origins.

Source code in src/whence/config.py

def origins(self) -> dict[str, Origin]:
    """Return the origin of every value.

    Returns:
        Dotted keys to origins.
    """
    return {join(path): tracked.origin for path, tracked in self._resolved.values.items()}

bind

bind(
    target: type,
    *,
    prefix: str | KeyPath = (),
    strict: bool | None = None,
) -> Any

Bind a subtree onto a typed schema.

Parameters:

Name	Type	Description	Default
target	type	A dataclass, or a pydantic model when pydantic is installed.	required
prefix	str | KeyPath	The subtree to read; defaults to the schema's own @settings prefix when it has one.	()
strict	bool | None	Whether a key nothing declared is an error. Defaults to whatever @settings recorded on the class.	None

Returns:

Type	Description
Any	An instance of target.

Raises:

Type	Description
BindError	If anything failed, listing every problem at once.

Source code in src/whence/config.py

def bind(self, target: type, *, prefix: str | KeyPath = (), strict: bool | None = None) -> Any:
    """Bind a subtree onto a typed schema.

    Args:
        target: A dataclass, or a pydantic model when pydantic is installed.
        prefix: The subtree to read; defaults to the schema's own
            ``@settings`` prefix when it has one.
        strict: Whether a key nothing declared is an error. Defaults to
            whatever ``@settings`` recorded on the class.

    Returns:
        An instance of ``target``.

    Raises:
        BindError: If anything failed, listing every problem at once.
    """
    declared = getattr(target, "__whence_prefix__", None)
    chosen: str | KeyPath | Sequence[str] = prefix
    if prefix == () and declared is not None:
        chosen = declared
    # An empty prefix means the root, not an empty key segment: `@settings()`
    # with no argument binds the whole tree.
    if not isinstance(chosen, str):
        path: KeyPath = tuple(chosen)
    elif chosen:
        path = canonical(chosen)
    else:
        path = ()
    if strict is None:
        strict = bool(getattr(target, "__whence_strict__", True))
    return _binding.bind(
        target,
        self._resolved.values,
        prefix=path,
        shadowed=self._resolved.shadowed,
        strict=strict,
    )

with_fallback

with_fallback(other: Config) -> Config

Layer another configuration underneath this one.

This is how a library ships defaults that an application can override. HOCON calls it withFallback, and figment separates it from merge because "replace" and "fill in the gaps" are genuinely different operations. whence has both: the source chain merges, and this fills gaps -- a key already set here keeps its value and its origin.

Parameters:

Name	Type	Description	Default
other	Config	The configuration to fall back to.	required

Returns:

Type	Description
Config	A new configuration.

Source code in src/whence/config.py

def with_fallback(self, other: "Config") -> "Config":
    """Layer another configuration underneath this one.

    This is how a library ships defaults that an application can override.
    HOCON calls it ``withFallback``, and figment separates it from ``merge``
    because "replace" and "fill in the gaps" are genuinely different
    operations. whence has both: the source chain merges, and this fills
    gaps -- a key already set here keeps its value and its origin.

    Args:
        other: The configuration to fall back to.

    Returns:
        A new configuration.
    """
    merged = resolve([*self._resolved.layers, *other._resolved.layers])
    return Config(merged, plan=self.plan, profiles=self.profiles, discovery=self.discovery)

__repr__

__repr__() -> str

Summarise without printing any values.

Source code in src/whence/config.py

def __repr__(self) -> str:
    """Summarise without printing any values."""
    return (
        f"Config({len(self._resolved.values)} keys from "
        f"{len(self._resolved.layers)} sources, profiles={list(self.profiles)})"
    )

Value dataclass

Annotation metadata: fill this parameter from one configuration key.

Written inside :data:~typing.Annotated, so the parameter keeps both its real type and its real default::

retries: Annotated[int, Value("http.retries")] = 3

A marked parameter with no default is required: a missing key raises :class:~whence.MissingKeyError rather than passing None on.

Attributes:

Name	Type	Description
key	str	The dotted key to read.

Source code in src/whence/decorators.py

@dataclass(frozen=True, slots=True)
class Value:
    """Annotation metadata: fill this parameter from one configuration key.

    Written inside :data:`~typing.Annotated`, so the parameter keeps both its
    real type and its real default::

        retries: Annotated[int, Value("http.retries")] = 3

    A marked parameter with no default is required: a missing key raises
    :class:`~whence.MissingKeyError` rather than passing ``None`` on.

    Attributes:
        key: The dotted key to read.
    """

    key: str

Discovery dataclass

Declarative configuration discovery.

Attributes:

Name	Type	Description
app	str	The application name. Every other default derives from it.
file	Path | None	An explicit configuration file. Wins outright, and must exist.
path	tuple[Path, ...]	Search roots, highest precedence first.
formats	tuple[str, ...]	Suffixes to look for, in preference order. Restricting this is how a project bans a format: a stray app.yaml is then simply never discovered, and the plan says so.
prefix	str | None	The environment variable prefix. None derives MYAPP_.
env_var	str | None	The variable naming an explicit config file. None derives MYAPP_CONFIG.
profiles_var	str | None	The variable listing active profiles. None derives MYAPP_PROFILES.
pyproject_table	str | None	The dotted table to read from pyproject.toml. None derives tool.myapp. Set to "" to skip step 5.
user_config	bool	Whether to search the per-user configuration directory.
search_parents	bool	Walk search roots upward, for monorepos.
boundary	tuple[str, ...]	Marker names that stop the upward walk.
mode	Literal['layer', 'first']	"layer" keeps every root as its own source; "first" stops at the first root that matches.
on_missing	Literal['ok', 'error']	"error" requires that discovery find at least one file.
dotenv	tuple[Path, ...]	.env files to read, highest precedence first.
secrets_dir	Path | None	A key-per-file secrets directory, or None to skip it.

Source code in src/whence/discovery.py

@dataclass(frozen=True, slots=True)
class Discovery:
    """Declarative configuration discovery.

    Attributes:
        app: The application name. Every other default derives from it.
        file: An explicit configuration file. Wins outright, and must exist.
        path: Search roots, highest precedence first.
        formats: Suffixes to look for, in preference order. Restricting this is
            how a project bans a format: a stray ``app.yaml`` is then simply
            never discovered, and the plan says so.
        prefix: The environment variable prefix. ``None`` derives ``MYAPP_``.
        env_var: The variable naming an explicit config file. ``None`` derives
            ``MYAPP_CONFIG``.
        profiles_var: The variable listing active profiles. ``None`` derives
            ``MYAPP_PROFILES``.
        pyproject_table: The dotted table to read from ``pyproject.toml``.
            ``None`` derives ``tool.myapp``. Set to ``""`` to skip step 5.
        user_config: Whether to search the per-user configuration directory.
        search_parents: Walk search roots upward, for monorepos.
        boundary: Marker names that stop the upward walk.
        mode: ``"layer"`` keeps every root as its own source; ``"first"`` stops
            at the first root that matches.
        on_missing: ``"error"`` requires that discovery find at least one file.
        dotenv: ``.env`` files to read, highest precedence first.
        secrets_dir: A key-per-file secrets directory, or ``None`` to skip it.
    """

    app: str
    file: Path | None = None
    path: tuple[Path, ...] = (Path(),)
    formats: tuple[str, ...] = DEFAULT_FORMATS
    prefix: str | None = None
    env_var: str | None = None
    profiles_var: str | None = None
    pyproject_table: str | None = None
    user_config: bool = True
    search_parents: bool = False
    boundary: tuple[str, ...] = (".git", "pyproject.toml")
    mode: Literal["layer", "first"] = "layer"
    on_missing: Literal["ok", "error"] = "ok"
    dotenv: tuple[Path, ...] = (Path(".env"),)
    secrets_dir: Path | None = field(default=Path("/run/secrets"))

    def __post_init__(self) -> None:
        """Validate the prefix before anything can depend on it."""
        validate_prefix(self.env_prefix)

    @property
    def env_prefix(self) -> str:
        """The environment prefix, derived from ``app`` when unset.

        Returns:
            ``"MYAPP_"``.
        """
        return default_prefix(self.app) if self.prefix is None else self.prefix

    @property
    def config_var(self) -> str:
        """The variable naming an explicit config file.

        Returns:
            ``"MYAPP_CONFIG"``.
        """
        return self.env_var or f"{self.app.upper()}_CONFIG"

    @property
    def profiles_env(self) -> str:
        """The variable listing active profiles.

        Returns:
            ``"MYAPP_PROFILES"``.
        """
        return self.profiles_var or f"{self.app.upper()}_PROFILES"

    @property
    def table(self) -> str:
        """The ``pyproject.toml`` table to read.

        Returns:
            ``"tool.myapp"``, or ``""`` when step 5 is disabled.
        """
        return f"tool.{self.app}" if self.pyproject_table is None else self.pyproject_table

    def with_(self, **changes: object) -> "Discovery":
        """Return a copy with fields replaced.

        Args:
            **changes: Fields to override.

        Returns:
            A new discovery object.
        """
        return replace(self, **changes)  # type: ignore[arg-type]

    def roots(self, cwd: Path | None = None) -> tuple[Path, ...]:
        """Resolve the search roots, expanding the upward walk.

        With ``search_parents``, each relative root is also looked for in every
        parent directory up to and including the first one holding a
        ``boundary`` marker. In a uv workspace, where a test run may start in
        ``libs/<member>/`` while the configuration sits at the repository root,
        this is the difference between working and not.

        Args:
            cwd: The directory to start from; defaults to the process's.

        Returns:
            Roots, nearest first.
        """
        base = Path.cwd() if cwd is None else cwd
        out: list[Path] = []
        for root in self.path:
            if root.is_absolute() or not self.search_parents:
                out.append(root if root.is_absolute() else base / root)
                continue
            for parent in (base, *base.parents):
                out.append(parent / root)
                if any((parent / marker).exists() for marker in self.boundary):
                    break
        return tuple(out)

    def stems(self, profiles: Sequence[str] = ()) -> tuple[tuple[str, str | None], ...]:
        """List the file stems to look for, highest precedence first.

        Args:
            profiles: Active profiles, in increasing precedence.

        Returns:
            ``(stem, profile)`` pairs. Later profiles outrank earlier ones, and
            every profile outranks the base file.
        """
        out: list[tuple[str, str | None]] = [
            (f"{self.app}.{profile}", profile) for profile in reversed(profiles)
        ]
        out.append((self.app, None))
        return tuple(out)

    def _match(self, root: Path, stem: str) -> Path | None:
        """Find the one file in ``root`` matching ``stem``.

        Raises:
            AmbiguousConfigError: If two suffixes both match in this root.
        """
        hits: list[Path] = []
        seen: set[object] = set()
        for suffix in self.formats:
            candidate = root / f"{stem}.{suffix}"
            if not candidate.is_file():
                continue
            key = same_file_key(candidate)
            if key in seen:
                continue
            seen.add(key)
            hits.append(candidate)
        if len(hits) > 1:
            msg = (
                f"{root} holds more than one {stem} configuration file "
                f"({', '.join(p.name for p in hits)}); "
                "remove one, or narrow `formats` to say which wins"
            )
            raise AmbiguousConfigError(msg)
        return hits[0] if hits else None

    def _scan(
        self, index: int, root: Path, label: str, stems: Sequence[tuple[str, str | None]]
    ) -> tuple[Step, list[tuple[Path, str | None]]]:
        """Search one directory for every stem, and record what it found.

        Args:
            index: The step number to record.
            root: The directory to search.
            label: How the step is described in the report.
            stems: ``(stem, profile)`` pairs, highest precedence first.

        Returns:
            The step, and the files it contributed.
        """
        hits: list[tuple[Path, str | None]] = []
        for stem, profile in stems:
            found = self._match(root, stem)
            if found is not None:
                hits.append((found, profile))
        if hits:
            return Step(index, label, tuple(path for path, _ in hits)), hits
        return Step(index, label, note="no match"), []

    def plan(
        self,
        *,
        profiles: Sequence[str] = (),
        environ: Mapping[str, str] | None = None,
        cwd: Path | None = None,
        platform: Platform | None = None,
    ) -> DiscoveryPlan:
        """Run the five-step chain and report exactly what happened.

        Args:
            profiles: Active profiles, in increasing precedence.
            environ: The environment to consult.
            cwd: The directory to start from.
            platform: Override the platform, for cross-platform tests.

        Returns:
            The plan: every step, and every file found.

        Raises:
            MissingConfigError: If an explicitly named file is absent, or
                ``on_missing="error"`` and nothing at all was found.
            AmbiguousConfigError: If one root holds two matching files.
        """
        env = environ if environ is not None else {}
        steps: list[Step] = []
        files: list[tuple[Path, str | None]] = []
        stems = self.stems(profiles)

        # 1 - an explicit file, which must exist.
        if self.file is not None:
            if not self.file.is_file():
                msg = f"configuration file {self.file} was named explicitly but does not exist"
                raise MissingConfigError(msg)
            files.append((self.file, None))
            steps.append(Step(1, "file=", (self.file,)))
        else:
            steps.append(Step(1, "file=", note="not given"))

        # 2 - the operator's environment override, which must also exist.
        named = env.get(self.config_var)
        if named:
            candidate = Path(named)
            if not candidate.is_file():
                msg = f"${self.config_var} points at {named!r}, which does not exist"
                raise MissingConfigError(msg)
            files.append((candidate, None))
            steps.append(Step(2, f"${self.config_var}", (candidate,)))
        else:
            steps.append(Step(2, f"${self.config_var}", note="not set"))

        # 3 - the project's own search roots.
        for root in self.roots(cwd):
            text = str(root)
            step, hits = self._scan(3, root, text if text.endswith("/") else f"{text}/", stems)
            steps.append(step)
            files.extend(hits)
            if hits and self.mode == "first":
                break

        # 4 - the developer's machine.
        if self.user_config:
            for pure in user_config_dirs(self.app, platform=platform, environ=env):
                directory = Path(str(pure))
                step, hits = self._scan(4, directory, str(directory), stems)
                steps.append(step)
                files.extend(hits)
        else:
            steps.append(Step(4, "user config dir", note="disabled"))

        # 5 - the repository's own default, handled by PyProjectSource.
        if self.table:
            steps.append(Step(5, f"pyproject.toml [{self.table}]", note="read separately"))
        else:
            steps.append(Step(5, "pyproject.toml", note="disabled"))

        if not files and self.on_missing == "error":
            msg = f"no configuration file found for {self.app!r}. Searched:\n" + "\n".join(
                f"  {s.label}" for s in steps
            )
            raise MissingConfigError(msg)
        return DiscoveryPlan(tuple(steps), tuple(files))

    def file_sources(self, plan: DiscoveryPlan) -> list[FileSource]:
        """Turn a plan into file sources, highest precedence first.

        Args:
            plan: A plan produced by :meth:`plan`.

        Returns:
            One source per discovered file.
        """
        return [FileSource(path, profile=profile) for path, profile in plan.files]

env_prefix property

env_prefix: str

The environment prefix, derived from app when unset.

Returns:

Type	Description
str	"MYAPP_".

config_var property

config_var: str

The variable naming an explicit config file.

Returns:

Type	Description
str	"MYAPP_CONFIG".

profiles_env property

profiles_env: str

The variable listing active profiles.

Returns:

Type	Description
str	"MYAPP_PROFILES".

table property

table: str

The pyproject.toml table to read.

Returns:

Type	Description
str	"tool.myapp", or "" when step 5 is disabled.

__post_init__

__post_init__() -> None

Validate the prefix before anything can depend on it.

Source code in src/whence/discovery.py

def __post_init__(self) -> None:
    """Validate the prefix before anything can depend on it."""
    validate_prefix(self.env_prefix)

with_

with_(**changes: object) -> Discovery

Return a copy with fields replaced.

Parameters:

Name	Type	Description	Default
**changes	object	Fields to override.	{}

Returns:

Type	Description
Discovery	A new discovery object.

Source code in src/whence/discovery.py

def with_(self, **changes: object) -> "Discovery":
    """Return a copy with fields replaced.

    Args:
        **changes: Fields to override.

    Returns:
        A new discovery object.
    """
    return replace(self, **changes)  # type: ignore[arg-type]

roots

roots(cwd: Path | None = None) -> tuple[Path, ...]

Resolve the search roots, expanding the upward walk.

With search_parents, each relative root is also looked for in every parent directory up to and including the first one holding a boundary marker. In a uv workspace, where a test run may start in libs/<member>/ while the configuration sits at the repository root, this is the difference between working and not.

Parameters:

Name	Type	Description	Default
cwd	Path | None	The directory to start from; defaults to the process's.	None

Returns:

Type	Description
tuple[Path, ...]	Roots, nearest first.

Source code in src/whence/discovery.py

def roots(self, cwd: Path | None = None) -> tuple[Path, ...]:
    """Resolve the search roots, expanding the upward walk.

    With ``search_parents``, each relative root is also looked for in every
    parent directory up to and including the first one holding a
    ``boundary`` marker. In a uv workspace, where a test run may start in
    ``libs/<member>/`` while the configuration sits at the repository root,
    this is the difference between working and not.

    Args:
        cwd: The directory to start from; defaults to the process's.

    Returns:
        Roots, nearest first.
    """
    base = Path.cwd() if cwd is None else cwd
    out: list[Path] = []
    for root in self.path:
        if root.is_absolute() or not self.search_parents:
            out.append(root if root.is_absolute() else base / root)
            continue
        for parent in (base, *base.parents):
            out.append(parent / root)
            if any((parent / marker).exists() for marker in self.boundary):
                break
    return tuple(out)

stems

stems(
    profiles: Sequence[str] = (),
) -> tuple[tuple[str, str | None], ...]

List the file stems to look for, highest precedence first.

Parameters:

Name	Type	Description	Default
profiles	Sequence[str]	Active profiles, in increasing precedence.	()

Returns:

Type	Description
tuple[str, str | None]	(stem, profile) pairs. Later profiles outrank earlier ones, and
...	every profile outranks the base file.

Source code in src/whence/discovery.py

def stems(self, profiles: Sequence[str] = ()) -> tuple[tuple[str, str | None], ...]:
    """List the file stems to look for, highest precedence first.

    Args:
        profiles: Active profiles, in increasing precedence.

    Returns:
        ``(stem, profile)`` pairs. Later profiles outrank earlier ones, and
        every profile outranks the base file.
    """
    out: list[tuple[str, str | None]] = [
        (f"{self.app}.{profile}", profile) for profile in reversed(profiles)
    ]
    out.append((self.app, None))
    return tuple(out)

plan

plan(
    *,
    profiles: Sequence[str] = (),
    environ: Mapping[str, str] | None = None,
    cwd: Path | None = None,
    platform: Platform | None = None,
) -> DiscoveryPlan

Run the five-step chain and report exactly what happened.

Parameters:

Name	Type	Description	Default
profiles	Sequence[str]	Active profiles, in increasing precedence.	()
environ	Mapping[str, str] | None	The environment to consult.	None
cwd	Path | None	The directory to start from.	None
platform	Platform | None	Override the platform, for cross-platform tests.	None

Returns:

Type	Description
DiscoveryPlan	The plan: every step, and every file found.

Raises:

Type	Description
MissingConfigError	If an explicitly named file is absent, or on_missing="error" and nothing at all was found.
AmbiguousConfigError	If one root holds two matching files.

Source code in src/whence/discovery.py

def plan(
    self,
    *,
    profiles: Sequence[str] = (),
    environ: Mapping[str, str] | None = None,
    cwd: Path | None = None,
    platform: Platform | None = None,
) -> DiscoveryPlan:
    """Run the five-step chain and report exactly what happened.

    Args:
        profiles: Active profiles, in increasing precedence.
        environ: The environment to consult.
        cwd: The directory to start from.
        platform: Override the platform, for cross-platform tests.

    Returns:
        The plan: every step, and every file found.

    Raises:
        MissingConfigError: If an explicitly named file is absent, or
            ``on_missing="error"`` and nothing at all was found.
        AmbiguousConfigError: If one root holds two matching files.
    """
    env = environ if environ is not None else {}
    steps: list[Step] = []
    files: list[tuple[Path, str | None]] = []
    stems = self.stems(profiles)

    # 1 - an explicit file, which must exist.
    if self.file is not None:
        if not self.file.is_file():
            msg = f"configuration file {self.file} was named explicitly but does not exist"
            raise MissingConfigError(msg)
        files.append((self.file, None))
        steps.append(Step(1, "file=", (self.file,)))
    else:
        steps.append(Step(1, "file=", note="not given"))

    # 2 - the operator's environment override, which must also exist.
    named = env.get(self.config_var)
    if named:
        candidate = Path(named)
        if not candidate.is_file():
            msg = f"${self.config_var} points at {named!r}, which does not exist"
            raise MissingConfigError(msg)
        files.append((candidate, None))
        steps.append(Step(2, f"${self.config_var}", (candidate,)))
    else:
        steps.append(Step(2, f"${self.config_var}", note="not set"))

    # 3 - the project's own search roots.
    for root in self.roots(cwd):
        text = str(root)
        step, hits = self._scan(3, root, text if text.endswith("/") else f"{text}/", stems)
        steps.append(step)
        files.extend(hits)
        if hits and self.mode == "first":
            break

    # 4 - the developer's machine.
    if self.user_config:
        for pure in user_config_dirs(self.app, platform=platform, environ=env):
            directory = Path(str(pure))
            step, hits = self._scan(4, directory, str(directory), stems)
            steps.append(step)
            files.extend(hits)
    else:
        steps.append(Step(4, "user config dir", note="disabled"))

    # 5 - the repository's own default, handled by PyProjectSource.
    if self.table:
        steps.append(Step(5, f"pyproject.toml [{self.table}]", note="read separately"))
    else:
        steps.append(Step(5, "pyproject.toml", note="disabled"))

    if not files and self.on_missing == "error":
        msg = f"no configuration file found for {self.app!r}. Searched:\n" + "\n".join(
            f"  {s.label}" for s in steps
        )
        raise MissingConfigError(msg)
    return DiscoveryPlan(tuple(steps), tuple(files))

file_sources

file_sources(plan: DiscoveryPlan) -> list[FileSource]

Turn a plan into file sources, highest precedence first.

Parameters:

Name	Type	Description	Default
plan	DiscoveryPlan	A plan produced by :meth:plan.	required

Returns:

Type	Description
list[FileSource]	One source per discovered file.

Source code in src/whence/discovery.py

def file_sources(self, plan: DiscoveryPlan) -> list[FileSource]:
    """Turn a plan into file sources, highest precedence first.

    Args:
        plan: A plan produced by :meth:`plan`.

    Returns:
        One source per discovered file.
    """
    return [FileSource(path, profile=profile) for path, profile in plan.files]

DiscoveryPlan dataclass

The outcome of running discovery: what was searched, and what was found.

Attributes:

Name	Type	Description
steps	tuple[Step, ...]	Every step, in order, including the ones that found nothing.
files	tuple[tuple[Path, str | None], ...]	Every discovered file, highest precedence first.

Source code in src/whence/discovery.py

@dataclass(frozen=True, slots=True)
class DiscoveryPlan:
    """The outcome of running discovery: what was searched, and what was found.

    Attributes:
        steps: Every step, in order, including the ones that found nothing.
        files: Every discovered file, highest precedence first.
    """

    steps: tuple[Step, ...]
    files: tuple[tuple[Path, str | None], ...]

    def render(self) -> str:
        """Format the plan the way ``whence explain --discovery`` prints it.

        Returns:
            A multi-line report.
        """
        lines = []
        for step in self.steps:
            head = f"  {step.index} {step.label:<30}"
            if step.found:
                lines.append(f"{head} {', '.join(p.name for p in step.paths)}")
            else:
                lines.append(f"{head} - {step.note or 'not found'}")
        return "\n".join(lines)

render

render() -> str

Format the plan the way whence explain --discovery prints it.

Returns:

Type	Description
str	A multi-line report.

Source code in src/whence/discovery.py

def render(self) -> str:
    """Format the plan the way ``whence explain --discovery`` prints it.

    Returns:
        A multi-line report.
    """
    lines = []
    for step in self.steps:
        head = f"  {step.index} {step.label:<30}"
        if step.found:
            lines.append(f"{head} {', '.join(p.name for p in step.paths)}")
        else:
            lines.append(f"{head} - {step.note or 'not found'}")
    return "\n".join(lines)

PyProjectSource

Reads a dotted table out of pyproject.toml.

The lowest file layer: a project's own committed defaults, which every other source is entitled to override.

Parameters:

Name	Type	Description	Default
path	Path | str	The pyproject.toml to read.	'pyproject.toml'
table	str	The dotted table name, such as "tool.myapp".	''
name	str	The layer name.	'pyproject'

Source code in src/whence/discovery.py

class PyProjectSource:
    """Reads a dotted table out of ``pyproject.toml``.

    The lowest file layer: a project's own committed defaults, which every other
    source is entitled to override.

    Args:
        path: The ``pyproject.toml`` to read.
        table: The dotted table name, such as ``"tool.myapp"``.
        name: The layer name.
    """

    def __init__(
        self, path: Path | str = "pyproject.toml", table: str = "", *, name: str = "pyproject"
    ) -> None:
        """Build a pyproject source."""
        self.path = Path(path)
        self.table = table
        self.name = name

    def load(self) -> Layer:
        """Read the table, if the file and the table both exist.

        Returns:
            The layer, with ``found=False`` when either is absent.

        Raises:
            FormatError: If ``pyproject.toml`` does not parse.
        """
        if not self.table or not self.path.is_file():
            return Layer(self.name, {}, found=False)
        text = self.path.read_text(encoding="utf-8-sig")
        try:
            data: object = tomllib.loads(text)
        except tomllib.TOMLDecodeError as exc:
            msg = f"{self.path}: invalid TOML: {exc}"
            raise FormatError(msg) from exc
        for segment in self.table.split("."):
            if not isinstance(data, Mapping) or segment not in data:
                return Layer(self.name, {}, found=False)
            data = data[segment]
        if not isinstance(data, Mapping):
            msg = f"{self.path}: [{self.table}] must be a table"
            raise ConfigError(msg)
        origin = Origin("file", f"{self.path} [{self.table}]")
        entries: dict[KeyPath, Tracked] = {
            path: Tracked(value, origin) for path, value in flatten(data).items()
        }
        return Layer(self.name, entries, found=bool(entries))

__init__

__init__(
    path: Path | str = "pyproject.toml",
    table: str = "",
    *,
    name: str = "pyproject",
) -> None

Build a pyproject source.

Source code in src/whence/discovery.py

def __init__(
    self, path: Path | str = "pyproject.toml", table: str = "", *, name: str = "pyproject"
) -> None:
    """Build a pyproject source."""
    self.path = Path(path)
    self.table = table
    self.name = name

load

load() -> Layer

Read the table, if the file and the table both exist.

Returns:

Type	Description
Layer	The layer, with found=False when either is absent.

Raises:

Type	Description
FormatError	If pyproject.toml does not parse.

Source code in src/whence/discovery.py

def load(self) -> Layer:
    """Read the table, if the file and the table both exist.

    Returns:
        The layer, with ``found=False`` when either is absent.

    Raises:
        FormatError: If ``pyproject.toml`` does not parse.
    """
    if not self.table or not self.path.is_file():
        return Layer(self.name, {}, found=False)
    text = self.path.read_text(encoding="utf-8-sig")
    try:
        data: object = tomllib.loads(text)
    except tomllib.TOMLDecodeError as exc:
        msg = f"{self.path}: invalid TOML: {exc}"
        raise FormatError(msg) from exc
    for segment in self.table.split("."):
        if not isinstance(data, Mapping) or segment not in data:
            return Layer(self.name, {}, found=False)
        data = data[segment]
    if not isinstance(data, Mapping):
        msg = f"{self.path}: [{self.table}] must be a table"
        raise ConfigError(msg)
    origin = Origin("file", f"{self.path} [{self.table}]")
    entries: dict[KeyPath, Tracked] = {
        path: Tracked(value, origin) for path, value in flatten(data).items()
    }
    return Layer(self.name, entries, found=bool(entries))

Step dataclass

One step of the discovery chain, and what it found.

Attributes:

Name	Type	Description
index	int	The step number, 1 through 5.
label	str	A human-readable description of where it looked.
paths	tuple[Path, ...]	Files it contributed, highest precedence first.
note	str	Why it contributed nothing, when it did not.

Source code in src/whence/discovery.py

@dataclass(frozen=True, slots=True)
class Step:
    """One step of the discovery chain, and what it found.

    Attributes:
        index: The step number, 1 through 5.
        label: A human-readable description of where it looked.
        paths: Files it contributed, highest precedence first.
        note: Why it contributed nothing, when it did not.
    """

    index: int
    label: str
    paths: tuple[Path, ...] = ()
    note: str = ""

    @property
    def found(self) -> bool:
        """Whether this step contributed anything.

        Returns:
            True when at least one file was found.
        """
        return bool(self.paths)

found property

found: bool

Whether this step contributed anything.

Returns:

Type	Description
bool	True when at least one file was found.

AmbiguousConfigError

Bases: ConfigError

Two files in one search root both satisfy the same logical name.

Raised rather than resolved by preference, because silently picking one is the failure mode that took Spring Boot years to specify.

Source code in src/whence/errors.py

class AmbiguousConfigError(ConfigError):
    """Two files in one search root both satisfy the same logical name.

    Raised rather than resolved by preference, because silently picking one is
    the failure mode that took Spring Boot years to specify.
    """

BindError

Bases: ConfigError

One or more values could not be bound to the target schema.

Source code in src/whence/errors.py

class BindError(ConfigError):
    """One or more values could not be bound to the target schema."""

ConfigError

Bases: WhenceError

The configuration itself is wrong: bad discovery, bad wiring, bad source.

Source code in src/whence/errors.py

class ConfigError(WhenceError):
    """The configuration itself is wrong: bad discovery, bad wiring, bad source."""

FormatError

Bases: ConfigError

A configuration file could not be parsed.

Source code in src/whence/errors.py

class FormatError(ConfigError):
    """A configuration file could not be parsed."""

InterpolationError

Bases: ConfigError

A ${...} placeholder could not be resolved.

Source code in src/whence/errors.py

class InterpolationError(ConfigError):
    """A ``${...}`` placeholder could not be resolved."""

MissingConfigError

Bases: ConfigError

A configuration file that was named explicitly does not exist.

Source code in src/whence/errors.py

class MissingConfigError(ConfigError):
    """A configuration file that was named explicitly does not exist."""

MissingKeyError

Bases: WhenceError, KeyError

A required key is absent from every source.

Source code in src/whence/errors.py

class MissingKeyError(WhenceError, KeyError):
    """A required key is absent from every source."""

    def __str__(self) -> str:
        """Render without ``KeyError``'s surrounding quotes."""
        return str(self.args[0]) if self.args else ""

__str__

__str__() -> str

Render without KeyError's surrounding quotes.

Source code in src/whence/errors.py

def __str__(self) -> str:
    """Render without ``KeyError``'s surrounding quotes."""
    return str(self.args[0]) if self.args else ""

SecretError

Bases: WhenceError

A secret was read outside an explicit unlock_secrets() scope.

Source code in src/whence/errors.py

class SecretError(WhenceError):
    """A secret was read outside an explicit ``unlock_secrets()`` scope."""

UnboundKeyError

Bases: ConfigError

Configuration supplied a key that the target schema does not declare.

Source code in src/whence/errors.py

class UnboundKeyError(ConfigError):
    """Configuration supplied a key that the target schema does not declare."""

WhenceError

Bases: Exception

Base class for every error whence raises.

Source code in src/whence/errors.py

class WhenceError(Exception):
    """Base class for every error whence raises."""

Origin dataclass

Where a single configuration value came from.

Attributes:

Name	Type	Description
source	str	The name of the source that produced it, such as "env" or "file". Matches the name the value's source carries in the chain.
locator	str	The concrete location within that source: a file path, an environment variable name, or "<defaults>".
line	int | None	One-based line number, when the parser reports positions.
column	int | None	One-based column number, when the parser reports positions.
profile	str | None	The profile whose overlay contributed the value, if any.
parent	Origin | None	The origin this one was derived from -- the variable behind a _FILE indirection, or the template behind an interpolated value.

Source code in src/whence/origin.py

@dataclass(frozen=True, slots=True)
class Origin:
    """Where a single configuration value came from.

    Attributes:
        source: The name of the source that produced it, such as ``"env"`` or
            ``"file"``. Matches the name the value's source carries in the chain.
        locator: The concrete location within that source: a file path, an
            environment variable name, or ``"<defaults>"``.
        line: One-based line number, when the parser reports positions.
        column: One-based column number, when the parser reports positions.
        profile: The profile whose overlay contributed the value, if any.
        parent: The origin this one was derived from -- the variable behind a
            ``_FILE`` indirection, or the template behind an interpolated value.
    """

    source: str
    locator: str
    line: int | None = None
    column: int | None = None
    profile: str | None = None
    parent: "Origin | None" = None

    def __str__(self) -> str:
        """Render as ``locator:line:column [profile=...]``."""
        text = self.locator
        if self.line is not None:
            text = f"{text}:{self.line}"
            if self.column is not None:
                text = f"{text}:{self.column}"
        if self.profile is not None:
            text = f"{text} [profile={self.profile}]"
        if self.parent is not None:
            text = f"{text} <- {self.parent}"
        return text

    def derived(self, **changes: Any) -> "Origin":
        """Return a copy that records this origin as its parent.

        Args:
            **changes: Fields to override on the copy.

        Returns:
            A new origin whose ``parent`` is this one.
        """
        return replace(self, parent=self, **changes)

__str__

__str__() -> str

Render as locator:line:column [profile=...].

Source code in src/whence/origin.py

def __str__(self) -> str:
    """Render as ``locator:line:column [profile=...]``."""
    text = self.locator
    if self.line is not None:
        text = f"{text}:{self.line}"
        if self.column is not None:
            text = f"{text}:{self.column}"
    if self.profile is not None:
        text = f"{text} [profile={self.profile}]"
    if self.parent is not None:
        text = f"{text} <- {self.parent}"
    return text

derived

derived(**changes: Any) -> Origin

Return a copy that records this origin as its parent.

Parameters:

Name	Type	Description	Default
**changes	Any	Fields to override on the copy.	{}

Returns:

Type	Description
Origin	A new origin whose parent is this one.

Source code in src/whence/origin.py

def derived(self, **changes: Any) -> "Origin":
    """Return a copy that records this origin as its parent.

    Args:
        **changes: Fields to override on the copy.

    Returns:
        A new origin whose ``parent`` is this one.
    """
    return replace(self, parent=self, **changes)

RelativePath

Bases: Path

A path resolved against the file that declared it, not the process cwd.

cert = "./ca.pem" inside deploy/app.yaml means deploy/ca.pem, wherever the program happens to be run from. That is only expressible because the value remembers where it came from; figment calls the same idea RelativePathBuf and nothing in Python offers it.

An absolute value is left alone, and a value from a source with no file behind it -- an environment variable, say -- is resolved against the cwd, because there is nothing better to resolve it against.

Source code in src/whence/origin.py

class RelativePath(Path):
    """A path resolved against the file that declared it, not the process cwd.

    ``cert = "./ca.pem"`` inside ``deploy/app.yaml`` means ``deploy/ca.pem``,
    wherever the program happens to be run from. That is only expressible
    because the value remembers where it came from; figment calls the same idea
    ``RelativePathBuf`` and nothing in Python offers it.

    An absolute value is left alone, and a value from a source with no file
    behind it -- an environment variable, say -- is resolved against the cwd,
    because there is nothing better to resolve it against.
    """

    __slots__ = ()

    @classmethod
    def resolve_against(cls, value: object, origin: "Origin | None") -> Path:
        """Resolve a path value against its origin's directory.

        Args:
            value: The raw path value.
            origin: Where the value came from.

        Returns:
            An absolute path where the origin names a file, and the value
            unchanged otherwise.
        """
        path = Path(str(value))
        if path.is_absolute() or origin is None or origin.source != "file":
            return path
        base = Path(origin.locator.split(" [")[0]).parent
        return base / path

resolve_against classmethod

resolve_against(
    value: object, origin: Origin | None
) -> Path

Resolve a path value against its origin's directory.

Parameters:

Name	Type	Description	Default
value	object	The raw path value.	required
origin	Origin | None	Where the value came from.	required

Returns:

Type	Description
Path	An absolute path where the origin names a file, and the value
Path	unchanged otherwise.

Source code in src/whence/origin.py

@classmethod
def resolve_against(cls, value: object, origin: "Origin | None") -> Path:
    """Resolve a path value against its origin's directory.

    Args:
        value: The raw path value.
        origin: Where the value came from.

    Returns:
        An absolute path where the origin names a file, and the value
        unchanged otherwise.
    """
    path = Path(str(value))
    if path.is_absolute() or origin is None or origin.source != "file":
        return path
    base = Path(origin.locator.split(" [")[0]).parent
    return base / path

Tracked dataclass

A value paired with its origin.

Equality and hashing delegate to the wrapped value on purpose. That is what makes provenance retrofittable instead of viral: every consumer that compares, hashes or formats a value keeps working unchanged, and only code that explicitly asks for .origin pays any attention to it. A sidecar {key: origin} map loses provenance at every transformation, and a str subclass loses it at the first f-string.

Attributes:

Name	Type	Description
value	Any	The underlying value.
origin	Origin	Where it came from.

Source code in src/whence/origin.py

@dataclass(frozen=True, slots=True)
class Tracked:
    """A value paired with its origin.

    Equality and hashing delegate to the wrapped value on purpose. That is what
    makes provenance retrofittable instead of viral: every consumer that
    compares, hashes or formats a value keeps working unchanged, and only code
    that explicitly asks for ``.origin`` pays any attention to it. A sidecar
    ``{key: origin}`` map loses provenance at every transformation, and a ``str``
    subclass loses it at the first f-string.

    Attributes:
        value: The underlying value.
        origin: Where it came from.
    """

    value: Any
    origin: Origin = field(compare=False, hash=False)

    def __eq__(self, other: object) -> bool:
        """Compare against the wrapped value, tracked or not."""
        return bool(self.value == unwrap(other))

    def __hash__(self) -> int:
        """Hash as the wrapped value does."""
        return hash(self.value)

    def __str__(self) -> str:
        """Render as the wrapped value does."""
        return str(self.value)

    def __repr__(self) -> str:
        """Show the value and its origin."""
        return f"Tracked({self.value!r} <- {self.origin})"

    def __bool__(self) -> bool:
        """Report the truthiness of the wrapped value."""
        return bool(self.value)

__eq__

__eq__(other: object) -> bool

Compare against the wrapped value, tracked or not.

Source code in src/whence/origin.py

def __eq__(self, other: object) -> bool:
    """Compare against the wrapped value, tracked or not."""
    return bool(self.value == unwrap(other))

__hash__

__hash__() -> int

Hash as the wrapped value does.

Source code in src/whence/origin.py

def __hash__(self) -> int:
    """Hash as the wrapped value does."""
    return hash(self.value)

__str__

__str__() -> str

Render as the wrapped value does.

Source code in src/whence/origin.py

def __str__(self) -> str:
    """Render as the wrapped value does."""
    return str(self.value)

__repr__

__repr__() -> str

Show the value and its origin.

Source code in src/whence/origin.py

def __repr__(self) -> str:
    """Show the value and its origin."""
    return f"Tracked({self.value!r} <- {self.origin})"

__bool__

__bool__() -> bool

Report the truthiness of the wrapped value.

Source code in src/whence/origin.py

def __bool__(self) -> bool:
    """Report the truthiness of the wrapped value."""
    return bool(self.value)

Secret

A string that will not reveal itself by accident.

repr and str both render the mask, so a secret cannot reach a log line, a traceback or an f-string through inattention. Reading the real value needs :func:unlock_secrets, which makes the intent explicit and greppable.

Source code in src/whence/secret.py

class Secret:
    """A string that will not reveal itself by accident.

    ``repr`` and ``str`` both render the mask, so a secret cannot reach a log
    line, a traceback or an f-string through inattention. Reading the real value
    needs :func:`unlock_secrets`, which makes the intent explicit and greppable.
    """

    __slots__ = ("_value",)

    def __init__(self, value: str) -> None:
        """Wrap a string.

        Args:
            value: The sensitive value.
        """
        self._value = value

    def reveal(self) -> str:
        """Return the underlying string.

        Returns:
            The real value.

        Raises:
            SecretError: If called outside an ``unlock_secrets()`` scope.
        """
        if not _UNLOCKED.get():
            msg = (
                "reading a Secret requires an explicit scope: "
                "`with unlock_secrets(): ...` around the call"
            )
            raise SecretError(msg)
        return self._value

    def __repr__(self) -> str:
        """Render the mask, never the value."""
        return f"Secret({MASK})"

    def __str__(self) -> str:
        """Render the mask, never the value."""
        return MASK

    def __eq__(self, other: object) -> bool:
        """Compare two secrets without revealing either."""
        if isinstance(other, Secret):
            return self._value == other._value
        return NotImplemented

    def __hash__(self) -> int:
        """Hash the underlying value."""
        return hash(self._value)

    def __bool__(self) -> bool:
        """Report whether the underlying string is non-empty."""
        return bool(self._value)

__init__

__init__(value: str) -> None

Wrap a string.

Parameters:

Name	Type	Description	Default
value	str	The sensitive value.	required

Source code in src/whence/secret.py

def __init__(self, value: str) -> None:
    """Wrap a string.

    Args:
        value: The sensitive value.
    """
    self._value = value

reveal

reveal() -> str

Return the underlying string.

Returns:

Type	Description
str	The real value.

Raises:

Type	Description
SecretError	If called outside an unlock_secrets() scope.

Source code in src/whence/secret.py

def reveal(self) -> str:
    """Return the underlying string.

    Returns:
        The real value.

    Raises:
        SecretError: If called outside an ``unlock_secrets()`` scope.
    """
    if not _UNLOCKED.get():
        msg = (
            "reading a Secret requires an explicit scope: "
            "`with unlock_secrets(): ...` around the call"
        )
        raise SecretError(msg)
    return self._value

__repr__

__repr__() -> str

Render the mask, never the value.

Source code in src/whence/secret.py

def __repr__(self) -> str:
    """Render the mask, never the value."""
    return f"Secret({MASK})"

__str__

__str__() -> str

Render the mask, never the value.

Source code in src/whence/secret.py

def __str__(self) -> str:
    """Render the mask, never the value."""
    return MASK

__eq__

__eq__(other: object) -> bool

Compare two secrets without revealing either.

Source code in src/whence/secret.py

def __eq__(self, other: object) -> bool:
    """Compare two secrets without revealing either."""
    if isinstance(other, Secret):
        return self._value == other._value
    return NotImplemented

__hash__

__hash__() -> int

Hash the underlying value.

Source code in src/whence/secret.py

def __hash__(self) -> int:
    """Hash the underlying value."""
    return hash(self._value)

__bool__

__bool__() -> bool

Report whether the underlying string is non-empty.

Source code in src/whence/secret.py

def __bool__(self) -> bool:
    """Report whether the underlying string is non-empty."""
    return bool(self._value)

ArgvSource

Reads --set key=value pairs out of an argument list.

Parameters:

Name	Type	Description	Default
argv	Sequence[str] | None	The arguments to scan; defaults to sys.argv[1:]. Passing an explicit list is what makes a test hermetic.	None
name	str	The layer name.	'cli'
flag	str	The flag to recognise, if --set collides with an existing one.	FLAG

Source code in src/whence/sources/argv.py

class ArgvSource:
    """Reads ``--set key=value`` pairs out of an argument list.

    Args:
        argv: The arguments to scan; defaults to ``sys.argv[1:]``. Passing an
            explicit list is what makes a test hermetic.
        name: The layer name.
        flag: The flag to recognise, if ``--set`` collides with an existing one.
    """

    def __init__(
        self,
        argv: Sequence[str] | None = None,
        *,
        name: str = "cli",
        flag: str = FLAG,
    ) -> None:
        """Build a command-line source."""
        self.name = name
        self.flag = flag
        self.argv = list(sys.argv[1:] if argv is None else argv)

    def _pairs(self) -> list[tuple[str, str, int]]:
        """Extract ``(key, value, argv index)`` triples, both flag spellings."""
        out: list[tuple[str, str, int]] = []
        i = 0
        while i < len(self.argv):
            arg = self.argv[i]
            if arg == self.flag:
                if i + 1 >= len(self.argv):
                    msg = f"{self.flag} needs an argument, as in `{self.flag} db.host=localhost`"
                    raise ConfigError(msg)
                body, index = self.argv[i + 1], i + 1
                i += 2
            elif arg.startswith(f"{self.flag}="):
                body, index = arg[len(self.flag) + 1 :], i
                i += 1
            else:
                i += 1
                continue
            key, sep, value = body.partition("=")
            if not sep or not key.strip():
                msg = f"{self.flag} expects key=value, as in `{self.flag} db.host=localhost`"
                raise ConfigError(msg)
            out.append((key.strip(), value, index))
        return out

    def load(self) -> Layer:
        """Collect every ``--set`` pair.

        Returns:
            The layer, with ``found=False`` when no pair was given.

        Raises:
            ConfigError: If a pair is malformed.
        """
        entries: dict[KeyPath, Tracked] = {}
        for key, value, index in self._pairs():
            entries[canonical(key)] = Tracked(
                value, Origin(self.name, f"{self.flag} {key}", line=index + 1)
            )
        return Layer(self.name, entries, found=bool(entries))

__init__

__init__(
    argv: Sequence[str] | None = None,
    *,
    name: str = "cli",
    flag: str = FLAG,
) -> None

Build a command-line source.

Source code in src/whence/sources/argv.py

def __init__(
    self,
    argv: Sequence[str] | None = None,
    *,
    name: str = "cli",
    flag: str = FLAG,
) -> None:
    """Build a command-line source."""
    self.name = name
    self.flag = flag
    self.argv = list(sys.argv[1:] if argv is None else argv)

load

load() -> Layer

Collect every --set pair.

Returns:

Type	Description
Layer	The layer, with found=False when no pair was given.

Raises:

Type	Description
ConfigError	If a pair is malformed.

Source code in src/whence/sources/argv.py

def load(self) -> Layer:
    """Collect every ``--set`` pair.

    Returns:
        The layer, with ``found=False`` when no pair was given.

    Raises:
        ConfigError: If a pair is malformed.
    """
    entries: dict[KeyPath, Tracked] = {}
    for key, value, index in self._pairs():
        entries[canonical(key)] = Tracked(
            value, Origin(self.name, f"{self.flag} {key}", line=index + 1)
        )
    return Layer(self.name, entries, found=bool(entries))

DotEnvSource

Reads a .env file and maps its variables like the environment.

Parameters:

Name	Type	Description	Default
path	Path | str	The file to read.	required
prefix	str	The environment prefix, applied exactly as EnvSource does so that .env and the real environment stay interchangeable.	''
name	str	The layer name.	'dotenv'
aliases	Mapping[str, str] | None	Explicit variable-to-key overrides.	None

Source code in src/whence/sources/dotenv.py

class DotEnvSource:
    """Reads a ``.env`` file and maps its variables like the environment.

    Args:
        path: The file to read.
        prefix: The environment prefix, applied exactly as ``EnvSource`` does so
            that ``.env`` and the real environment stay interchangeable.
        name: The layer name.
        aliases: Explicit variable-to-key overrides.
    """

    def __init__(
        self,
        path: Path | str,
        prefix: str = "",
        *,
        name: str = "dotenv",
        aliases: Mapping[str, str] | None = None,
    ) -> None:
        """Build a ``.env`` source."""
        self.name = name
        self.path = Path(path)
        self.prefix = validate_prefix(prefix)
        self._aliases = dict(aliases or {})

    def load(self) -> Layer:
        """Read the file, if it exists.

        Returns:
            The layer, with ``found=False`` when the file is absent.

        Raises:
            FormatError: If the file exists but cannot be parsed.
        """
        if not self.path.is_file():
            return Layer(self.name, {}, found=False)
        text = self.path.read_text(encoding="utf-8-sig")
        entries: dict[KeyPath, Tracked] = {}
        for raw_name, tracked in parse_dotenv(text, str(self.path)).items():
            alias = self._aliases.get(raw_name)
            path = canonical(alias) if alias else key_from_env(raw_name, self.prefix)
            if path is not None:
                entries[path] = tracked
        return Layer(self.name, entries, found=True)

__init__

__init__(
    path: Path | str,
    prefix: str = "",
    *,
    name: str = "dotenv",
    aliases: Mapping[str, str] | None = None,
) -> None

Build a .env source.

Source code in src/whence/sources/dotenv.py

def __init__(
    self,
    path: Path | str,
    prefix: str = "",
    *,
    name: str = "dotenv",
    aliases: Mapping[str, str] | None = None,
) -> None:
    """Build a ``.env`` source."""
    self.name = name
    self.path = Path(path)
    self.prefix = validate_prefix(prefix)
    self._aliases = dict(aliases or {})

load

load() -> Layer

Read the file, if it exists.

Returns:

Type	Description
Layer	The layer, with found=False when the file is absent.

Raises:

Type	Description
FormatError	If the file exists but cannot be parsed.

Source code in src/whence/sources/dotenv.py

def load(self) -> Layer:
    """Read the file, if it exists.

    Returns:
        The layer, with ``found=False`` when the file is absent.

    Raises:
        FormatError: If the file exists but cannot be parsed.
    """
    if not self.path.is_file():
        return Layer(self.name, {}, found=False)
    text = self.path.read_text(encoding="utf-8-sig")
    entries: dict[KeyPath, Tracked] = {}
    for raw_name, tracked in parse_dotenv(text, str(self.path)).items():
        alias = self._aliases.get(raw_name)
        path = canonical(alias) if alias else key_from_env(raw_name, self.prefix)
        if path is not None:
            entries[path] = tracked
    return Layer(self.name, entries, found=True)

EnvSource

Reads configuration from environment variables.

Parameters:

Name	Type	Description	Default
prefix	str	The literal prefix every variable carries. Applied to the environment only -- files are never prefixed, matching Spring's setEnvironmentPrefix.	''
environ	Mapping[str, str] | None	The environment to read; defaults to os.environ. Passing an explicit mapping is what makes a test hermetic.	None
name	str	The layer name.	'env'
aliases	Mapping[str, str] | None	An explicit map from variable name to dotted key, for the cases convention does not cover (DATABASE_URL -> db.url). An explicit, greppable table beats implicit name mangling, which is the lesson from node-config's custom-environment-variables.json.	None
read_files	bool	Whether to honour the _FILE convention.	True
exclude	Collection[str]	Variables that control how configuration is found rather than carrying any of it -- $MYAPP_CONFIG and $MYAPP_PROFILES. Without this they would be read twice: once by discovery, and again as data under a key named config, which a schema that forbids unknown keys then rejects.	()

Source code in src/whence/sources/env.py

class EnvSource:
    """Reads configuration from environment variables.

    Args:
        prefix: The literal prefix every variable carries. Applied to the
            environment only -- files are never prefixed, matching Spring's
            ``setEnvironmentPrefix``.
        environ: The environment to read; defaults to ``os.environ``. Passing an
            explicit mapping is what makes a test hermetic.
        name: The layer name.
        aliases: An explicit map from variable name to dotted key, for the cases
            convention does not cover (``DATABASE_URL`` -> ``db.url``). An
            explicit, greppable table beats implicit name mangling, which is the
            lesson from node-config's ``custom-environment-variables.json``.
        read_files: Whether to honour the ``_FILE`` convention.
        exclude: Variables that control *how* configuration is found rather than
            carrying any of it -- ``$MYAPP_CONFIG`` and ``$MYAPP_PROFILES``.
            Without this they would be read twice: once by discovery, and again
            as data under a key named ``config``, which a schema that forbids
            unknown keys then rejects.
    """

    def __init__(
        self,
        prefix: str = "",
        *,
        environ: Mapping[str, str] | None = None,
        name: str = "env",
        aliases: Mapping[str, str] | None = None,
        read_files: bool = True,
        exclude: Collection[str] = (),
    ) -> None:
        """Build an environment source."""
        self.name = name
        self.exclude = frozenset(exclude)
        self.prefix = validate_prefix(prefix)
        # `environ or os.environ` would quietly reinstate the real environment
        # for a test that deliberately passed an empty one.
        self._environ = os.environ if environ is None else environ
        self._aliases = dict(aliases or {})
        self._read_files = read_files

    def name_for(self, path: KeyPath) -> str:
        """Return the one variable name that maps to a key path.

        Args:
            path: The canonical key path.

        Returns:
            ``"MYAPP_DB__HOST"``.
        """
        return env_name(path, self.prefix)

    def load(self) -> Layer:
        """Read every matching variable, resolving ``_FILE`` indirection.

        Returns:
            The layer.

        Raises:
            ConfigError: If both ``VAR`` and ``VAR_FILE`` are set, or a
                ``_FILE`` target cannot be read.
        """
        entries: dict[KeyPath, Tracked] = {}
        for raw_name, raw_value in sorted(self._environ.items()):
            if raw_name in self.exclude:
                continue
            alias = self._aliases.get(raw_name)
            if alias is not None:
                entries[canonical(alias)] = Tracked(raw_value, Origin(self.name, raw_name))
                continue
            is_file = self._read_files and raw_name.endswith(FILE_SUFFIX)
            lookup = raw_name[: -len(FILE_SUFFIX)] if is_file else raw_name
            path = key_from_env(lookup, self.prefix)
            if path is None:
                continue
            if not is_file:
                entries[path] = Tracked(raw_value, Origin(self.name, raw_name))
                continue
            # Setting both is always a mistake, and silently preferring one is
            # how a rotated secret goes unnoticed. Docker's own helper errors.
            if lookup in self._environ:
                msg = f"both {lookup} and {raw_name} are set; use exactly one to supply this value"
                raise ConfigError(msg)
            entries[path] = Tracked(self._read(raw_value, raw_name), Origin(self.name, raw_name))
        return Layer(self.name, entries, found=bool(entries))

    def _read(self, target: str, var: str) -> str:
        """Read a ``_FILE`` target, stripping the trailing newline."""
        path = Path(target)
        try:
            text = path.read_text(encoding="utf-8")
        except OSError as exc:
            msg = f"{var} points at {target!r}, which could not be read: {exc.strerror}"
            raise ConfigError(msg) from exc
        # `$(< file)` strips trailing newlines, and every editor adds one.
        return text.rstrip("\r\n")

__init__

__init__(
    prefix: str = "",
    *,
    environ: Mapping[str, str] | None = None,
    name: str = "env",
    aliases: Mapping[str, str] | None = None,
    read_files: bool = True,
    exclude: Collection[str] = (),
) -> None

Build an environment source.

Source code in src/whence/sources/env.py

def __init__(
    self,
    prefix: str = "",
    *,
    environ: Mapping[str, str] | None = None,
    name: str = "env",
    aliases: Mapping[str, str] | None = None,
    read_files: bool = True,
    exclude: Collection[str] = (),
) -> None:
    """Build an environment source."""
    self.name = name
    self.exclude = frozenset(exclude)
    self.prefix = validate_prefix(prefix)
    # `environ or os.environ` would quietly reinstate the real environment
    # for a test that deliberately passed an empty one.
    self._environ = os.environ if environ is None else environ
    self._aliases = dict(aliases or {})
    self._read_files = read_files

name_for

name_for(path: KeyPath) -> str

Return the one variable name that maps to a key path.

Parameters:

Name	Type	Description	Default
path	KeyPath	The canonical key path.	required

Returns:

Type	Description
str	"MYAPP_DB__HOST".

Source code in src/whence/sources/env.py

def name_for(self, path: KeyPath) -> str:
    """Return the one variable name that maps to a key path.

    Args:
        path: The canonical key path.

    Returns:
        ``"MYAPP_DB__HOST"``.
    """
    return env_name(path, self.prefix)

load

load() -> Layer

Read every matching variable, resolving _FILE indirection.

Returns:

Type	Description
Layer	The layer.

Raises:

Type	Description
ConfigError	If both VAR and VAR_FILE are set, or a _FILE target cannot be read.

Source code in src/whence/sources/env.py

def load(self) -> Layer:
    """Read every matching variable, resolving ``_FILE`` indirection.

    Returns:
        The layer.

    Raises:
        ConfigError: If both ``VAR`` and ``VAR_FILE`` are set, or a
            ``_FILE`` target cannot be read.
    """
    entries: dict[KeyPath, Tracked] = {}
    for raw_name, raw_value in sorted(self._environ.items()):
        if raw_name in self.exclude:
            continue
        alias = self._aliases.get(raw_name)
        if alias is not None:
            entries[canonical(alias)] = Tracked(raw_value, Origin(self.name, raw_name))
            continue
        is_file = self._read_files and raw_name.endswith(FILE_SUFFIX)
        lookup = raw_name[: -len(FILE_SUFFIX)] if is_file else raw_name
        path = key_from_env(lookup, self.prefix)
        if path is None:
            continue
        if not is_file:
            entries[path] = Tracked(raw_value, Origin(self.name, raw_name))
            continue
        # Setting both is always a mistake, and silently preferring one is
        # how a rotated secret goes unnoticed. Docker's own helper errors.
        if lookup in self._environ:
            msg = f"both {lookup} and {raw_name} are set; use exactly one to supply this value"
            raise ConfigError(msg)
        entries[path] = Tracked(self._read(raw_value, raw_name), Origin(self.name, raw_name))
    return Layer(self.name, entries, found=bool(entries))

FileSource

Loads one configuration file.

Parameters:

Name	Type	Description	Default
path	Path | str	The file to read.	required
name	str | None	The layer name; defaults to the path itself, which is what makes explain readable when several files are layered.	None
optional	bool	When false, a missing file raises. An explicitly named file that does not exist is always a mistake; a discovered one is not.	True
profile	str | None	The profile this file belongs to, recorded in every origin it produces.	None
loaders	Mapping[str, Loader] | None	A suffix-to-loader table; defaults to the built-ins.	None

Source code in src/whence/sources/files.py

class FileSource:
    """Loads one configuration file.

    Args:
        path: The file to read.
        name: The layer name; defaults to the path itself, which is what makes
            ``explain`` readable when several files are layered.
        optional: When false, a missing file raises. An explicitly named file
            that does not exist is always a mistake; a discovered one is not.
        profile: The profile this file belongs to, recorded in every origin it
            produces.
        loaders: A suffix-to-loader table; defaults to the built-ins.
    """

    def __init__(
        self,
        path: Path | str,
        *,
        name: str | None = None,
        optional: bool = True,
        profile: str | None = None,
        loaders: Mapping[str, Loader] | None = None,
    ) -> None:
        """Build a file source."""
        self.path = Path(path)
        self.name = name or str(path)
        self.optional = optional
        self.profile = profile
        self._loaders = loaders

    def load(self) -> Layer:
        """Read and parse the file.

        Returns:
            The layer, with ``found=False`` when an optional file is absent.

        Raises:
            MissingConfigError: If a required file does not exist.
            FormatError: If the file cannot be parsed.
        """
        if not self.path.is_file():
            if self.optional:
                return Layer(self.name, {}, found=False)
            msg = f"configuration file {self.path} does not exist"
            raise MissingConfigError(msg)
        text = self.path.read_text(encoding="utf-8-sig")
        parse = loader_for(self.path.suffix, self._loaders)
        entries = parse(text, str(self.path))
        if self.profile is not None:
            entries = {
                path: Tracked(value.value, replace(value.origin, profile=self.profile))
                for path, value in entries.items()
            }
        return Layer(self.name, entries, found=True)

__init__

__init__(
    path: Path | str,
    *,
    name: str | None = None,
    optional: bool = True,
    profile: str | None = None,
    loaders: Mapping[str, Loader] | None = None,
) -> None

Build a file source.

Source code in src/whence/sources/files.py

def __init__(
    self,
    path: Path | str,
    *,
    name: str | None = None,
    optional: bool = True,
    profile: str | None = None,
    loaders: Mapping[str, Loader] | None = None,
) -> None:
    """Build a file source."""
    self.path = Path(path)
    self.name = name or str(path)
    self.optional = optional
    self.profile = profile
    self._loaders = loaders

load

load() -> Layer

Read and parse the file.

Returns:

Type	Description
Layer	The layer, with found=False when an optional file is absent.

Raises:

Type	Description
MissingConfigError	If a required file does not exist.
FormatError	If the file cannot be parsed.

Source code in src/whence/sources/files.py

def load(self) -> Layer:
    """Read and parse the file.

    Returns:
        The layer, with ``found=False`` when an optional file is absent.

    Raises:
        MissingConfigError: If a required file does not exist.
        FormatError: If the file cannot be parsed.
    """
    if not self.path.is_file():
        if self.optional:
            return Layer(self.name, {}, found=False)
        msg = f"configuration file {self.path} does not exist"
        raise MissingConfigError(msg)
    text = self.path.read_text(encoding="utf-8-sig")
    parse = loader_for(self.path.suffix, self._loaders)
    entries = parse(text, str(self.path))
    if self.profile is not None:
        entries = {
            path: Tracked(value.value, replace(value.origin, profile=self.profile))
            for path, value in entries.items()
        }
    return Layer(self.name, entries, found=True)

MappingSource

A layer built from a Python mapping.

Used for the two ends of the chain -- explicit overrides at the top and schema defaults at the bottom. Defaults are a source rather than a property of the target object on purpose: it means get, dump and explain all agree about what the configuration says. Spring's equivalent split, where @Value cannot see a bean's own defaults, is a genuine bug.

Source code in src/whence/sources/mapping.py

class MappingSource:
    """A layer built from a Python mapping.

    Used for the two ends of the chain -- explicit overrides at the top and
    schema defaults at the bottom. Defaults are a source rather than a property
    of the target object on purpose: it means ``get``, ``dump`` and ``explain``
    all agree about what the configuration says. Spring's equivalent split,
    where ``@Value`` cannot see a bean's own defaults, is a genuine bug.
    """

    def __init__(
        self,
        data: Mapping[str, object] | Mapping[KeyPath, object],
        *,
        name: str = "overrides",
        locator: str | None = None,
    ) -> None:
        """Build a source from a flat or nested mapping.

        Args:
            data: Either nested (``{"db": {"host": "h"}}``) or already flat
                (``{("db", "host"): "h"}``).
            name: The layer name, used verbatim by ``explain``.
            locator: What origins should report; defaults to ``<name>``.
        """
        self.name = name
        self._origin = Origin(name, locator or f"<{name}>")
        if all(isinstance(key, tuple) for key in data):
            flat: dict[KeyPath, object] = {canonical(key): value for key, value in data.items()}
        else:
            flat = flatten({str(k): v for k, v in data.items()})
        self._entries = {path: Tracked(value, self._origin) for path, value in flat.items()}

    def load(self) -> Layer:
        """Return the mapping as a layer.

        Returns:
            The layer, marked found when the mapping was non-empty.
        """
        return Layer(self.name, self._entries, found=bool(self._entries))

__init__

__init__(
    data: Mapping[str, object] | Mapping[KeyPath, object],
    *,
    name: str = "overrides",
    locator: str | None = None,
) -> None

Build a source from a flat or nested mapping.

Parameters:

Name	Type	Description	Default
data	Mapping[str, object] | Mapping[KeyPath, object]	Either nested ({"db": {"host": "h"}}) or already flat ({("db", "host"): "h"}).	required
name	str	The layer name, used verbatim by explain.	'overrides'
locator	str | None	What origins should report; defaults to <name>.	None

Source code in src/whence/sources/mapping.py

def __init__(
    self,
    data: Mapping[str, object] | Mapping[KeyPath, object],
    *,
    name: str = "overrides",
    locator: str | None = None,
) -> None:
    """Build a source from a flat or nested mapping.

    Args:
        data: Either nested (``{"db": {"host": "h"}}``) or already flat
            (``{("db", "host"): "h"}``).
        name: The layer name, used verbatim by ``explain``.
        locator: What origins should report; defaults to ``<name>``.
    """
    self.name = name
    self._origin = Origin(name, locator or f"<{name}>")
    if all(isinstance(key, tuple) for key in data):
        flat: dict[KeyPath, object] = {canonical(key): value for key, value in data.items()}
    else:
        flat = flatten({str(k): v for k, v in data.items()})
    self._entries = {path: Tracked(value, self._origin) for path, value in flat.items()}

load

load() -> Layer

Return the mapping as a layer.

Returns:

Type	Description
Layer	The layer, marked found when the mapping was non-empty.

Source code in src/whence/sources/mapping.py

def load(self) -> Layer:
    """Return the mapping as a layer.

    Returns:
        The layer, marked found when the mapping was non-empty.
    """
    return Layer(self.name, self._entries, found=bool(self._entries))

SecretsDirSource

Reads one file per key from a directory.

A file named db.password or db__password becomes the key db.password; both spellings work because Kubernetes secret keys cannot always contain dots.

Parameters:

Name	Type	Description	Default
path	Path | str	The directory to read.	'/run/secrets'
name	str	The layer name.	'secrets-dir'

Source code in src/whence/sources/secrets.py

class SecretsDirSource:
    """Reads one file per key from a directory.

    A file named ``db.password`` or ``db__password`` becomes the key
    ``db.password``; both spellings work because Kubernetes secret keys cannot
    always contain dots.

    Args:
        path: The directory to read.
        name: The layer name.
    """

    def __init__(self, path: Path | str = "/run/secrets", *, name: str = "secrets-dir") -> None:
        """Build a secrets-directory source."""
        self.path = Path(path)
        self.name = name

    def load(self) -> Layer:
        """Read every regular file in the directory.

        Returns:
            The layer, with ``found=False`` when the directory is absent.
        """
        if not self.path.is_dir():
            return Layer(self.name, {}, found=False)
        entries: dict[KeyPath, Tracked] = {}
        for child in sorted(self.path.iterdir()):
            # Kubernetes projects secrets through a `..data` symlink and hides
            # the real files under `..2024_01_01_00_00_00.123456789/`.
            if child.name.startswith(".") or not child.is_file():
                continue
            text = child.read_text(encoding="utf-8")
            key = canonical(child.name.replace("__", "."))
            entries[key] = Tracked(text.rstrip("\r\n"), Origin(self.name, str(child)))
        return Layer(self.name, entries, found=bool(entries))

__init__

__init__(
    path: Path | str = "/run/secrets",
    *,
    name: str = "secrets-dir",
) -> None

Build a secrets-directory source.

Source code in src/whence/sources/secrets.py

def __init__(self, path: Path | str = "/run/secrets", *, name: str = "secrets-dir") -> None:
    """Build a secrets-directory source."""
    self.path = Path(path)
    self.name = name

load

load() -> Layer

Read every regular file in the directory.

Returns:

Type	Description
Layer	The layer, with found=False when the directory is absent.

Source code in src/whence/sources/secrets.py

def load(self) -> Layer:
    """Read every regular file in the directory.

    Returns:
        The layer, with ``found=False`` when the directory is absent.
    """
    if not self.path.is_dir():
        return Layer(self.name, {}, found=False)
    entries: dict[KeyPath, Tracked] = {}
    for child in sorted(self.path.iterdir()):
        # Kubernetes projects secrets through a `..data` symlink and hides
        # the real files under `..2024_01_01_00_00_00.123456789/`.
        if child.name.startswith(".") or not child.is_file():
            continue
        text = child.read_text(encoding="utf-8")
        key = canonical(child.name.replace("__", "."))
        entries[key] = Tracked(text.rstrip("\r\n"), Origin(self.name, str(child)))
    return Layer(self.name, entries, found=bool(entries))

Source

Bases: Protocol

Something that can contribute one layer of configuration.

Source code in src/whence/sources/__init__.py

@runtime_checkable
class Source(Protocol):
    """Something that can contribute one layer of configuration."""

    name: str

    def load(self) -> Layer:
        """Read everything this source has to offer.

        Returns:
            One layer, possibly empty, named after this source.
        """
        ...

load

load() -> Layer

Read everything this source has to offer.

Returns:

Type	Description
Layer	One layer, possibly empty, named after this source.

Source code in src/whence/sources/__init__.py

def load(self) -> Layer:
    """Read everything this source has to offer.

    Returns:
        One layer, possibly empty, named after this source.
    """
    ...

Layer dataclass

Everything one source contributed, under its own name.

Attributes:

Name	Type	Description
name	str	The source's name in the chain, used verbatim by explain.
entries	Mapping[KeyPath, Tracked]	Flat canonical key paths to tracked values.
found	bool	Whether the source produced anything. A source that was consulted and found nothing still appears in explain, because absence is information.

Source code in src/whence/tree.py

@dataclass(frozen=True, slots=True)
class Layer:
    """Everything one source contributed, under its own name.

    Attributes:
        name: The source's name in the chain, used verbatim by ``explain``.
        entries: Flat canonical key paths to tracked values.
        found: Whether the source produced anything. A source that was consulted
            and found nothing still appears in ``explain``, because absence is
            information.
    """

    name: str
    entries: Mapping[KeyPath, Tracked] = field(default_factory=dict)
    found: bool = True

Resolved dataclass

The outcome of merging layers, with the losers kept.

Attributes:

Name	Type	Description
values	Mapping[KeyPath, Tracked]	The winning value for every key.
shadowed	Mapping[KeyPath, tuple[tuple[str, Tracked], ...]]	Per key, the (layer name, value) pairs that lost, in precedence order.
layers	tuple[Layer, ...]	Every layer consulted, highest precedence first, including the ones that contributed nothing.

Source code in src/whence/tree.py

@dataclass(frozen=True, slots=True)
class Resolved:
    """The outcome of merging layers, with the losers kept.

    Attributes:
        values: The winning value for every key.
        shadowed: Per key, the ``(layer name, value)`` pairs that lost, in
            precedence order.
        layers: Every layer consulted, highest precedence first, including the
            ones that contributed nothing.
    """

    values: Mapping[KeyPath, Tracked]
    shadowed: Mapping[KeyPath, tuple[tuple[str, Tracked], ...]]
    layers: tuple[Layer, ...]

    def keys(self) -> Iterable[KeyPath]:
        """Return every key that has a winning value.

        Returns:
            The resolved key paths.
        """
        return self.values.keys()

    def dotted(self) -> dict[str, Tracked]:
        """Return the resolved values keyed by dotted name.

        Returns:
            A mapping from ``"db.host"`` to its tracked value.
        """
        return {join(path): value for path, value in self.values.items()}

keys

keys() -> Iterable[KeyPath]

Return every key that has a winning value.

Returns:

Type	Description
Iterable[KeyPath]	The resolved key paths.

Source code in src/whence/tree.py

def keys(self) -> Iterable[KeyPath]:
    """Return every key that has a winning value.

    Returns:
        The resolved key paths.
    """
    return self.values.keys()

dotted

dotted() -> dict[str, Tracked]

Return the resolved values keyed by dotted name.

Returns:

Type	Description
dict[str, Tracked]	A mapping from "db.host" to its tracked value.

Source code in src/whence/tree.py

def dotted(self) -> dict[str, Tracked]:
    """Return the resolved values keyed by dotted name.

    Returns:
        A mapping from ``"db.host"`` to its tracked value.
    """
    return {join(path): value for path, value in self.values.items()}

bind

bind(
    target: type,
    values: Mapping[KeyPath, Tracked],
    *,
    prefix: KeyPath = (),
    shadowed: Mapping[
        KeyPath, tuple[tuple[str, Tracked], ...]
    ]
    | None = None,
    strict: bool = True,
) -> Any

Bind resolved configuration onto a schema, reporting every problem.

Parameters:

Name	Type	Description	Default
target	type	The schema class.	required
values	Mapping[KeyPath, Tracked]	Flat resolved values.	required
prefix	KeyPath	The subtree to bind.	()
shadowed	Mapping[KeyPath, tuple[tuple[str, Tracked], ...]] | None	Shadow records, used to enrich error messages.	None
strict	bool	Whether a key nothing declared is an error.	True

Returns:

Type	Description
Any	An instance of target.

Raises:

Type	Description
BindError	If anything failed, with every problem in one message.

Source code in src/whence/binding/__init__.py

def bind(
    target: type,
    values: Mapping[KeyPath, Tracked],
    *,
    prefix: KeyPath = (),
    shadowed: Mapping[KeyPath, tuple[tuple[str, Tracked], ...]] | None = None,
    strict: bool = True,
) -> Any:
    """Bind resolved configuration onto a schema, reporting every problem.

    Args:
        target: The schema class.
        values: Flat resolved values.
        prefix: The subtree to bind.
        shadowed: Shadow records, used to enrich error messages.
        strict: Whether a key nothing declared is an error.

    Returns:
        An instance of ``target``.

    Raises:
        BindError: If anything failed, with every problem in one message.
    """
    binder = choose_binder(target)
    problems: list[Problem] = []
    instance = binder.bind(target, values, prefix, problems)

    if strict:
        declared = binder.declared(target, prefix)
        depth = len(prefix)
        for path, tracked in values.items():
            if path[:depth] != prefix or len(path) <= depth or path in declared:
                continue
            hint = suggest(path, declared)
            reason = "no such setting"
            if hint:
                reason = f"{reason} - did you mean {hint[0]!r}?"
            problems.append(Problem(join(path), tracked.value, tracked.origin, reason))

    if problems:
        if shadowed:
            problems = [replace(p, shadowed=_shadow_text(p.key, shadowed)) for p in problems]
        raise BindError(render_problems(problems))
    return instance

render_problems

render_problems(problems: Sequence[Problem]) -> str

Format problems the way whence reports them.

The four-field Property / Value / Origin / Reason block plus an Action line is Spring Boot's failure-analysis layout, which is the best in the field and costs nothing to adopt.

Parameters:

Name	Type	Description	Default
problems	Sequence[Problem]	The problems to render.	required

Returns:

Type	Description
str	A multi-line message.

Source code in src/whence/binding/__init__.py

def render_problems(problems: Sequence[Problem]) -> str:
    """Format problems the way whence reports them.

    The four-field ``Property / Value / Origin / Reason`` block plus an
    ``Action`` line is Spring Boot's failure-analysis layout, which is the best
    in the field and costs nothing to adopt.

    Args:
        problems: The problems to render.

    Returns:
        A multi-line message.
    """
    count = len(problems)
    lines = [f"{count} error{'s' if count != 1 else ''}", ""]
    for problem in problems:
        lines.append(f"  Property: {problem.key}")
        if problem.value is not None:
            lines.append(f"     Value: {sanitize(problem.key, problem.value)!r}")
        if problem.origin is not None:
            lines.append(f"    Origin: {problem.origin}")
        lines.append(f"    Reason: {problem.reason}")
        lines.extend(f"  Shadowed: {entry}" for entry in problem.shadowed)
        lines.append("")
    lines.append("Action: correct the configuration, or run `whence explain <key>`.")
    return "\n".join(lines)

configure

configure(config: Config | None) -> None

Set the ambient configuration for this context.

Parameters:

Name	Type	Description	Default
config	Config | None	The configuration, or None to clear it.	required

Source code in src/whence/decorators.py

def configure(config: Config | None) -> None:
    """Set the ambient configuration for this context.

    Args:
        config: The configuration, or ``None`` to clear it.
    """
    _CURRENT.set(config)

current_config

current_config(config: Config) -> Generator[Config]

Use a configuration for the duration of a block.

Parameters:

Name	Type	Description	Default
config	Config	The configuration to install.	required

Yields:

Type	Description
Generator[Config]	The same configuration.

Source code in src/whence/decorators.py

@contextmanager
def current_config(config: Config) -> Generator[Config]:
    """Use a configuration for the duration of a block.

    Args:
        config: The configuration to install.

    Yields:
        The same configuration.
    """
    token = _CURRENT.set(config)
    try:
        yield config
    finally:
        _CURRENT.reset(token)

from_config

from_config(fn: Callable[P, R]) -> Callable[..., R]

Fill parameters annotated :data:Injected or :class:Value from configuration.

The wrapper is typed Callable[..., R] rather than Callable[P, R], and that is the one real cost of putting the markers in Annotated. A marked parameter with no default is required in the signature a type checker reads, so connect() would be an error at every call site even though filling it is the entire point. Nothing in the type system can say "these particular keyword parameters are now optional", so the return type says the honest thing instead: after decoration, the arguments are whichever subset the caller chooses to pass. The return type is still checked, and the runtime signature is untouched -- inspect.signature and every framework that reads it see the parameters exactly as written.

Parameters:

Name	Type	Description	Default
fn	Callable[P, R]	The function to wrap; sync or async.	required

Returns:

Type	Description
Callable[..., R]	The wrapped function, accepting any subset of its own arguments.

Raises:

Type	Description
ConfigError	If a marked parameter is not keyword-only, carries two markers, or combines Injected with an unreachable default.

Source code in src/whence/decorators.py

def from_config[**P, R](fn: Callable[P, R]) -> Callable[..., R]:
    """Fill parameters annotated :data:`Injected` or :class:`Value` from configuration.

    The wrapper is typed ``Callable[..., R]`` rather than ``Callable[P, R]``,
    and that is the one real cost of putting the markers in ``Annotated``. A
    marked parameter with no default is *required* in the signature a type
    checker reads, so ``connect()`` would be an error at every call site even
    though filling it is the entire point. Nothing in the type system can say
    "these particular keyword parameters are now optional", so the return type
    says the honest thing instead: after decoration, the arguments are whichever
    subset the caller chooses to pass. The return type is still checked, and the
    runtime signature is untouched -- ``inspect.signature`` and every framework
    that reads it see the parameters exactly as written.

    Args:
        fn: The function to wrap; sync or async.

    Returns:
        The wrapped function, accepting any subset of its own arguments.

    Raises:
        ConfigError: If a marked parameter is not keyword-only, carries two
            markers, or combines ``Injected`` with an unreachable default.
    """
    plan = _plan(fn)

    def fill(kwargs: dict[str, Any]) -> None:
        # Nothing left to fill means nothing to look up: a caller who passes every
        # marked argument -- a test, typically -- needs no ambient configuration at
        # all, and demanding one would make `@from_config` contagious.
        pending = [entry for entry in plan if entry[0] not in kwargs]
        if not pending:
            return
        config = _ambient()
        for name, marker, annotation, default in pending:
            if isinstance(marker, Value):
                kwargs[name] = (
                    config.require(marker.key, type_=annotation)
                    if default is _NO_DEFAULT
                    else config.get(marker.key, default, type_=annotation)
                )
            else:
                kwargs[name] = config.bind(annotation)

    if inspect.iscoroutinefunction(fn):

        @functools.wraps(fn)
        async def async_wrapper(*args: P.args, **kwargs: P.kwargs) -> Any:
            fill(cast("dict[str, Any]", kwargs))
            return await fn(*args, **kwargs)

        return cast("Callable[..., R]", async_wrapper)

    @functools.wraps(fn)
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        fill(cast("dict[str, Any]", kwargs))
        return fn(*args, **kwargs)

    return wrapper

load_settings

load_settings(
    cls: type[T],
    config: Config | None = None,
    *,
    strict: bool | None = None,
) -> T

Bind a @settings class from a configuration.

The typed spelling of config.bind(cls), and the only one: @settings attaches no methods to the class it decorates, because an attribute added by a decorator is invisible to a type checker.

Parameters:

Name	Type	Description	Default
cls	type[T]	A class decorated with :func:settings.	required
config	Config | None	The configuration; defaults to the ambient one.	None
strict	bool | None	Override the strictness @settings recorded on the class.	None

Returns:

Type	Description
T	An instance of cls.

Source code in src/whence/decorators.py

def load_settings[T](
    cls: type[T], config: Config | None = None, *, strict: bool | None = None
) -> T:
    """Bind a ``@settings`` class from a configuration.

    The typed spelling of ``config.bind(cls)``, and the only one: ``@settings``
    attaches no methods to the class it decorates, because an attribute added by
    a decorator is invisible to a type checker.

    Args:
        cls: A class decorated with :func:`settings`.
        config: The configuration; defaults to the ambient one.
        strict: Override the strictness ``@settings`` recorded on the class.

    Returns:
        An instance of ``cls``.
    """
    target = config if config is not None else _ambient()
    return cast("T", target.bind(cls, strict=strict))

settings

settings(prefix: type[T]) -> type[T]

settings(
    prefix: str = "", *, strict: bool = True
) -> Callable[[type[T]], type[T]]

settings(prefix: Any = '', *, strict: bool = True) -> Any

Mark a class as binding to a subtree of configuration.

Usable bare or called, like :func:~dataclasses.dataclass: @settings binds the whole tree, @settings("db") binds one subtree.

Parameters:

Name	Type	Description	Default
prefix	Any	The dotted subtree, such as "db".	''
strict	bool	Whether a key under prefix that this class does not declare is an error. True is the right default -- a typo'd key is the most common configuration bug and is otherwise invisible -- but a class that deliberately covers only part of its subtree sets it False.	True

Returns:

Type	Description
Any	The decorated class when used bare, otherwise a class decorator.

Source code in src/whence/decorators.py

def settings(prefix: Any = "", *, strict: bool = True) -> Any:
    """Mark a class as binding to a subtree of configuration.

    Usable bare or called, like :func:`~dataclasses.dataclass`: ``@settings``
    binds the whole tree, ``@settings("db")`` binds one subtree.

    Args:
        prefix: The dotted subtree, such as ``"db"``.
        strict: Whether a key under ``prefix`` that this class does not declare
            is an error. True is the right default -- a typo'd key is the most
            common configuration bug and is otherwise invisible -- but a class
            that deliberately covers only part of its subtree sets it False.

    Returns:
        The decorated class when used bare, otherwise a class decorator.
    """

    def decorate(cls: type[Any], subtree: str) -> type[Any]:
        # Class-level metadata, read by `Config.bind`. The same shape the
        # standard library uses for `__dataclass_fields__`.
        cls.__whence_prefix__ = subtree
        cls.__whence_strict__ = strict
        return cls

    if isinstance(prefix, type):
        return decorate(prefix, "")
    return lambda cls: decorate(cls, prefix)

canonical

canonical(key: str | Iterable[str]) -> KeyPath

Normalise a dotted key or a sequence of segments into a key path.

Parameters:

Name	Type	Description	Default
key	str | Iterable[str]	"db.max-retries", "DB.MaxRetries" or ("db", "max_retries").	required

Returns:

Type	Description
KeyPath	The canonical path, lowercase with - folded to _.

Raises:

Type	Description
ConfigError	If the key is empty or contains an empty segment.

Source code in src/whence/keys.py

def canonical(key: str | Iterable[str]) -> KeyPath:
    """Normalise a dotted key or a sequence of segments into a key path.

    Args:
        key: ``"db.max-retries"``, ``"DB.MaxRetries"`` or ``("db", "max_retries")``.

    Returns:
        The canonical path, lowercase with ``-`` folded to ``_``.

    Raises:
        ConfigError: If the key is empty or contains an empty segment.
    """
    parts = key.split(".") if isinstance(key, str) else list(key)
    if not parts:
        msg = "empty configuration key"
        raise ConfigError(msg)
    out: list[str] = []
    for part in parts:
        segment = part.strip().replace("-", "_").lower()
        if not segment:
            msg = f"empty segment in configuration key {key!r}"
            raise ConfigError(msg)
        out.append(segment)
    return tuple(out)

env_name

env_name(path: KeyPath, prefix: str = '') -> str

Render the one environment variable name that maps to a key path.

Parameters:

Name	Type	Description	Default
path	KeyPath	The canonical key path.	required
prefix	str	The environment prefix, already validated.	''

Returns:

Type	Description
str	"MYAPP_DB__MAX_RETRIES".

Source code in src/whence/keys.py

def env_name(path: KeyPath, prefix: str = "") -> str:
    """Render the one environment variable name that maps to a key path.

    Args:
        path: The canonical key path.
        prefix: The environment prefix, already validated.

    Returns:
        ``"MYAPP_DB__MAX_RETRIES"``.
    """
    return prefix + NESTING.join(segment.upper() for segment in path)

key_from_env

key_from_env(name: str, prefix: str = '') -> KeyPath | None

Map an environment variable name back to a key path.

Parameters:

Name	Type	Description	Default
name	str	The variable name as it appears in the environment.	required
prefix	str	The environment prefix, already validated.	''

Returns:

Type	Description
KeyPath | None	The key path, or None if the name does not carry the prefix or has
KeyPath | None	an empty segment.

Source code in src/whence/keys.py

def key_from_env(name: str, prefix: str = "") -> KeyPath | None:
    """Map an environment variable name back to a key path.

    Args:
        name: The variable name as it appears in the environment.
        prefix: The environment prefix, already validated.

    Returns:
        The key path, or ``None`` if the name does not carry the prefix or has
        an empty segment.
    """
    if prefix and not name.startswith(prefix):
        return None
    body = name[len(prefix) :]
    if not body:
        return None
    segments = body.split(NESTING)
    if any(not segment for segment in segments):
        return None
    return tuple(segment.lower() for segment in segments)

origin_of

origin_of(obj: object) -> Origin | None

Return the origin of a value, or None if it carries none.

Parameters:

Name	Type	Description	Default
obj	object	Any value.	required

Returns:

Type	Description
Origin | None	The origin, when obj is :class:Tracked.

Source code in src/whence/origin.py

def origin_of(obj: object) -> Origin | None:
    """Return the origin of a value, or ``None`` if it carries none.

    Args:
        obj: Any value.

    Returns:
        The origin, when ``obj`` is :class:`Tracked`.
    """
    return obj.origin if isinstance(obj, Tracked) else None

unwrap

unwrap(obj: object) -> Any

Strip tracking from a value, recursively through containers.

Parameters:

Name	Type	Description	Default
obj	object	A tracked value, a plain value, or a container of either.	required

Returns:

Type	Description
Any	The same shape with every :class:Tracked replaced by its value.

Source code in src/whence/origin.py

def unwrap(obj: object) -> Any:
    """Strip tracking from a value, recursively through containers.

    Args:
        obj: A tracked value, a plain value, or a container of either.

    Returns:
        The same shape with every :class:`Tracked` replaced by its value.
    """
    if isinstance(obj, Tracked):
        return unwrap(obj.value)
    if isinstance(obj, dict):
        return {k: unwrap(v) for k, v in obj.items()}
    if isinstance(obj, list):
        return [unwrap(v) for v in obj]
    if isinstance(obj, tuple):
        return tuple(unwrap(v) for v in obj)
    return obj

active_profiles

active_profiles(
    explicit: Sequence[str] | None = None,
    *,
    environ: Mapping[str, str] | None = None,
    var: str = "",
    groups: Mapping[str, Sequence[str]] | None = None,
    default: Sequence[str] = (),
) -> tuple[str, ...]

Decide which profiles are active.

Parameters:

Name	Type	Description	Default
explicit	Sequence[str] | None	Profiles passed in code; wins over the environment.	None
environ	Mapping[str, str] | None	The environment to consult.	None
var	str	The variable holding a comma-separated list.	''
groups	Mapping[str, Sequence[str]] | None	Group definitions to expand.	None
default	Sequence[str]	Profiles to use when nothing else says.	()

Returns:

Type	Description
tuple[str, ...]	Active profiles in increasing precedence, so the last one wins.

Source code in src/whence/profiles.py

def active_profiles(
    explicit: Sequence[str] | None = None,
    *,
    environ: Mapping[str, str] | None = None,
    var: str = "",
    groups: Mapping[str, Sequence[str]] | None = None,
    default: Sequence[str] = (),
) -> tuple[str, ...]:
    """Decide which profiles are active.

    Args:
        explicit: Profiles passed in code; wins over the environment.
        environ: The environment to consult.
        var: The variable holding a comma-separated list.
        groups: Group definitions to expand.
        default: Profiles to use when nothing else says.

    Returns:
        Active profiles in increasing precedence, so the last one wins.
    """
    if explicit is not None:
        chosen: Sequence[str] = explicit
    elif var and environ and (raw := environ.get(var, "").strip()):
        chosen = raw.split(",")
    else:
        chosen = default
    return expand_groups(chosen, groups)

expand_groups

expand_groups(
    profiles: Sequence[str],
    groups: Mapping[str, Sequence[str]] | None = None,
    _depth: int = 0,
) -> tuple[str, ...]

Expand profile groups into the profiles they stand for.

groups={"staging": ["cloud", "readonly-db"]} turns ["staging"] into ["cloud", "readonly-db", "staging"]. Spring added groups in 2.4 to replace chained include directives, and they are considerably easier to read than the chain they replaced.

Parameters:

Name	Type	Description	Default
profiles	Sequence[str]	The requested profiles, in increasing precedence.	required
groups	Mapping[str, Sequence[str]] | None	Group definitions.	None
_depth	int	Recursion guard.	0

Returns:

Type	Description
tuple[str, ...]	The expanded profiles, deduplicated, in increasing precedence.

Raises:

Type	Description
ConfigError	If groups reference each other in a cycle.

Source code in src/whence/profiles.py

def expand_groups(
    profiles: Sequence[str],
    groups: Mapping[str, Sequence[str]] | None = None,
    _depth: int = 0,
) -> tuple[str, ...]:
    """Expand profile groups into the profiles they stand for.

    ``groups={"staging": ["cloud", "readonly-db"]}`` turns ``["staging"]`` into
    ``["cloud", "readonly-db", "staging"]``. Spring added groups in 2.4 to
    replace chained ``include`` directives, and they are considerably easier to
    read than the chain they replaced.

    Args:
        profiles: The requested profiles, in increasing precedence.
        groups: Group definitions.
        _depth: Recursion guard.

    Returns:
        The expanded profiles, deduplicated, in increasing precedence.

    Raises:
        ConfigError: If groups reference each other in a cycle.
    """
    if _depth > MAX_GROUP_DEPTH:
        msg = f"profile groups nest more than {MAX_GROUP_DEPTH} deep; check for a cycle"
        raise ConfigError(msg)
    table = {k.strip().lower(): v for k, v in (groups or {}).items()}
    out: list[str] = []
    for raw in profiles:
        name = raw.strip().lower()
        if not name:
            continue
        members = table.get(name)
        if members:
            out.extend(expand_groups(list(members), table, _depth + 1))
        out.append(name)
    # dict preserves first-insertion order, which is the dedup this needs.
    return tuple(dict.fromkeys(out))

is_sensitive

is_sensitive(
    key: str, patterns: Sequence[str] = SENSITIVE
) -> bool

Report whether a key name looks like it holds a secret.

Parameters:

Name	Type	Description	Default
key	str	A dotted key name.	required
patterns	Sequence[str]	Glob patterns to match against, case-insensitively.	SENSITIVE

Returns:

Type	Description
bool	True when any pattern matches.

Source code in src/whence/secret.py

def is_sensitive(key: str, patterns: Sequence[str] = SENSITIVE) -> bool:
    """Report whether a key name looks like it holds a secret.

    Args:
        key: A dotted key name.
        patterns: Glob patterns to match against, case-insensitively.

    Returns:
        True when any pattern matches.
    """
    lowered = key.lower()
    return any(fnmatch.fnmatchcase(lowered, pattern) for pattern in patterns)

sanitize

sanitize(
    key: str,
    value: Any,
    patterns: Sequence[str] = SENSITIVE,
) -> Any

Redact a value if its key or its type says it is sensitive.

A :class:Secret is masked whatever it is called, and a value is masked when its key matches. Both directions matter: convict masks by declared sensitivity, Spring masks by key pattern, and each misses what the other catches.

Parameters:

Name	Type	Description	Default
key	str	The dotted key name.	required
value	Any	The value.	required
patterns	Sequence[str]	Key patterns to treat as sensitive.	SENSITIVE

Returns:

Type	Description
Any	Either the value or :data:MASK.

Source code in src/whence/secret.py

def sanitize(key: str, value: Any, patterns: Sequence[str] = SENSITIVE) -> Any:
    """Redact a value if its key or its type says it is sensitive.

    A :class:`Secret` is masked whatever it is called, and a value is masked
    when its key matches. Both directions matter: convict masks by declared
    sensitivity, Spring masks by key pattern, and each misses what the other
    catches.

    Args:
        key: The dotted key name.
        value: The value.
        patterns: Key patterns to treat as sensitive.

    Returns:
        Either the value or :data:`MASK`.
    """
    if isinstance(value, Secret) or is_sensitive(key, patterns):
        return MASK
    return value

unlock_secrets

unlock_secrets() -> Generator[None]

Permit :meth:Secret.reveal for the duration of the block.

The flag lives in a :class:~contextvars.ContextVar, so it does not leak across tasks and a concurrent request cannot ride on another's unlock.

Yields:

Type	Description
Generator[None]	Nothing.

Source code in src/whence/secret.py

@contextmanager
def unlock_secrets() -> Generator[None]:
    """Permit :meth:`Secret.reveal` for the duration of the block.

    The flag lives in a :class:`~contextvars.ContextVar`, so it does not leak
    across tasks and a concurrent request cannot ride on another's unlock.

    Yields:
        Nothing.
    """
    token = _UNLOCKED.set(True)
    try:
        yield
    finally:
        _UNLOCKED.reset(token)