whence 1.0.0__py3-none-any.whl

whence/__init__.py

@@ -0,0 +1,121 @@
+"""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.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .binding import Binder, Problem, bind, render_problems
+from .chain import SourceChain
+from .config import Config
+from .decorators import (
+    Injected,
+    Value,
+    configure,
+    current_config,
+    from_config,
+    load_settings,
+    settings,
+)
+from .discovery import Discovery, DiscoveryPlan, PyProjectSource, Step
+from .errors import (
+    AmbiguousConfigError,
+    BindError,
+    ConfigError,
+    FormatError,
+    InterpolationError,
+    MissingConfigError,
+    MissingKeyError,
+    SecretError,
+    UnboundKeyError,
+    WhenceError,
+)
+from .keys import KeyPath, canonical, env_name, key_from_env
+from .origin import Origin, RelativePath, Tracked, origin_of, unwrap
+from .profiles import active_profiles, expand_groups
+from .secret import MASK, Secret, is_sensitive, sanitize, unlock_secrets
+from .sources import (
+    ArgvSource,
+    DotEnvSource,
+    EnvSource,
+    FileSource,
+    MappingSource,
+    SecretsDirSource,
+    Source,
+)
+from .tree import Layer, Resolved
+
+__all__ = [
+    "MASK",
+    "AmbiguousConfigError",
+    "ArgvSource",
+    "BindError",
+    "Binder",
+    "Config",
+    "ConfigError",
+    "Discovery",
+    "DiscoveryPlan",
+    "DotEnvSource",
+    "EnvSource",
+    "FileSource",
+    "FormatError",
+    "Injected",
+    "InterpolationError",
+    "KeyPath",
+    "Layer",
+    "MappingSource",
+    "MissingConfigError",
+    "MissingKeyError",
+    "Origin",
+    "Problem",
+    "PyProjectSource",
+    "RelativePath",
+    "Resolved",
+    "Secret",
+    "SecretError",
+    "SecretsDirSource",
+    "Source",
+    "SourceChain",
+    "Step",
+    "Tracked",
+    "UnboundKeyError",
+    "Value",
+    "WhenceError",
+    "__version__",
+    "active_profiles",
+    "bind",
+    "canonical",
+    "configure",
+    "current_config",
+    "env_name",
+    "expand_groups",
+    "from_config",
+    "is_sensitive",
+    "key_from_env",
+    "load_settings",
+    "origin_of",
+    "render_problems",
+    "sanitize",
+    "settings",
+    "unlock_secrets",
+    "unwrap",
+]
+
+try:
+    __version__ = version("whence")
+except PackageNotFoundError:  # pragma: no cover - source tree without an install
+    __version__ = "0.0.0.dev0"

whence/_platform.py

@@ -0,0 +1,196 @@
+"""Platform conventions, behind a seam so tests do not need three machines.
+
+Every function takes the platform and the environment as arguments rather than
+reading ``sys.platform`` and ``os.environ`` directly. That is what lets one test
+run assert the Windows, macOS and Linux answers on whichever machine CI happens
+to schedule, and it is the same seam figment's ``Jail`` and viper's ``afero``
+exist to provide.
+"""
+
+import os
+import sys
+from collections.abc import Mapping
+from pathlib import Path, PurePath, PurePosixPath, PureWindowsPath
+
+__all__ = ["Platform", "current_platform", "flavour", "same_file_key", "user_config_dirs"]
+
+type Platform = str
+"""A ``sys.platform`` value: ``"linux"``, ``"darwin"``, ``"win32"``, ..."""
+
+
+def current_platform() -> Platform:
+    """Return the running platform.
+
+    Returns:
+        The value of ``sys.platform``.
+    """
+    return sys.platform
+
+
+def flavour(platform: Platform) -> type[PurePath]:
+    r"""Return the path flavour a platform uses.
+
+    ``PureWindowsPath`` and ``PurePosixPath`` are fully functional on every
+    platform, which is what makes the whole platform matrix testable in one
+    process. Overriding ``sys.platform`` alone is not enough and is actively
+    misleading: ``PurePath(r"C:\\Users\\u").is_absolute()`` is ``False`` on POSIX,
+    so a Windows test would silently exercise POSIX semantics and pass against
+    the wrong expectation.
+
+    Args:
+        platform: A ``sys.platform`` value.
+
+    Returns:
+        ``PureWindowsPath`` on Windows, ``PurePosixPath`` elsewhere.
+    """
+    return PureWindowsPath if platform == "win32" else PurePosixPath
+
+
+def _is_abs(value: str | None, platform: Platform) -> bool:
+    """Report whether a value is a non-empty absolute path for this platform."""
+    if not value:
+        return False
+    return flavour(platform)(value).is_absolute()
+
+
+def _home(environ: Mapping[str, str], platform: Platform) -> PurePath | None:
+    """Resolve the user's home directory, or ``None`` if it is unusable.
+
+    Deliberately not ``os.path.expanduser("~")`` or ``Path.home()``: with
+    ``HOME=""`` the former returns ``"/"`` and with ``HOME="rel/dir"`` it returns
+    that string verbatim. Neither raises, so both turn a broken environment into
+    a plausible-looking wrong answer -- a config directory of ``/.config/myapp``,
+    or a directory literally named ``~`` in the working directory.
+    """
+    if platform == "win32":
+        value = environ.get("USERPROFILE")
+        if not value:
+            drive, tail = environ.get("HOMEDRIVE", ""), environ.get("HOMEPATH")
+            value = (drive + tail) if tail else None
+    else:
+        value = environ.get("HOME")
+        if not value:
+            try:
+                import pwd
+
+                value = pwd.getpwuid(os.getuid()).pw_dir
+            except (ImportError, KeyError, AttributeError):  # pragma: no cover - POSIX only
+                value = None
+    if value is None or not _is_abs(value, platform):
+        return None
+    return flavour(platform)(value)
+
+
+def _xdg_dir(
+    environ: Mapping[str, str], var: str, fallback: PurePath | None, platform: Platform
+) -> PurePath | None:
+    """Read an XDG single-directory variable.
+
+    The specification is explicit that a value which is unset, empty, or not an
+    absolute path must be treated as unset, which is the part most
+    implementations skip.
+    """
+    value = environ.get(var, "")
+    if _is_abs(value, platform):
+        return flavour(platform)(value)
+    return fallback
+
+
+def user_config_dirs(
+    app: str,
+    *,
+    platform: Platform | None = None,
+    environ: Mapping[str, str] | None = None,
+) -> tuple[PurePath, ...]:
+    """Return the per-user configuration directories for an application.
+
+    Ordered most specific first. The directories are not required to exist; the
+    caller decides what to do about that.
+
+    The conventions differ per platform and there is genuine disagreement in the
+    ecosystem about macOS, where the Apple answer is ``Application Support`` but
+    a large share of command-line tools follow XDG. whence returns both, Apple's
+    first, and additionally honours ``XDG_CONFIG_HOME`` there when the user has
+    set it explicitly -- which is the only signal that they meant it.
+
+    Args:
+        app: The application name.
+        platform: Override the platform; defaults to the running one.
+        environ: Override the environment; defaults to ``os.environ``.
+
+    Returns:
+        Directories to search, most specific first, deduplicated.
+    """
+    system = current_platform() if platform is None else platform
+    env = os.environ if environ is None else environ
+    home = _home(env, system)
+    pure = flavour(system)
+    out: list[PurePath] = []
+
+    if system == "win32":
+        # Local before Roaming. Roaming is copied over the network and merged
+        # last-writer-wins across machines, Microsoft has been retreating from
+        # it since 1909, and Package State Roaming is gone in Windows 11.
+        # platformdirs defaults to Local for the same reasons.
+        for var in ("LOCALAPPDATA", "APPDATA"):
+            value = env.get(var)
+            if value and _is_abs(value, system):
+                out.append(pure(value) / app)
+        if not out and home is not None:
+            out.append(home / "AppData" / "Local" / app)
+    elif system == "darwin":
+        # Apple says Application Support; a large share of command-line tools
+        # follow XDG. Both are served, Apple's first, and an explicitly set
+        # XDG_CONFIG_HOME is honoured because setting it is the only signal a
+        # user can give. platformdirs reached the same position in 4.6.0.
+        if home is not None:
+            out.append(home / "Library" / "Application Support" / app)
+        explicit = _xdg_dir(env, "XDG_CONFIG_HOME", None, system)
+        if explicit is not None:
+            out.append(explicit / app)
+        if home is not None:
+            out.append(home / ".config" / app)
+    else:
+        base = _xdg_dir(env, "XDG_CONFIG_HOME", None if home is None else home / ".config", system)
+        if base is not None:
+            out.append(base / app)
+        # A value of ":" or "::" leaves nothing after filtering, which must mean
+        # the default rather than nothing at all.
+        site = [
+            pure(part)
+            for part in env.get("XDG_CONFIG_DIRS", "").split(":")
+            if _is_abs(part, system)
+        ] or [pure("/etc/xdg")]
+        out.extend(path / app for path in site)
+
+    # setdefault keeps the first path per normalised key, matching the order
+    # these directories are searched in.
+    unique: dict[str, PurePath] = {}
+    for path in out:
+        unique.setdefault(os.path.normcase(str(path)), path)
+    return tuple(unique.values())
+
+
+def same_file_key(path: Path) -> object:
+    """Return a key that is equal for two paths naming the same file.
+
+    macOS (APFS, HFS+) and Windows (NTFS) are case-insensitive but
+    case-preserving, so ``app.toml`` and ``App.TOML`` are one file there and two
+    on Linux. Discovery deduplicates candidates through this so a
+    case-insensitive filesystem does not look like an ambiguity.
+
+    Args:
+        path: The path to key.
+
+    Returns:
+        The file's ``(device, inode)`` identity when it exists, which is exact on
+        every platform, and a normalised path string when it does not.
+
+    ``os.path.normcase`` alone is not enough: it is the identity function on
+    macOS, which is precisely a platform where the filesystem folds case.
+    """
+    try:
+        stat = path.stat()
+    except OSError:
+        return os.path.normcase(str(path))
+    return (stat.st_dev, stat.st_ino)

whence/binding/__init__.py

@@ -0,0 +1,223 @@
+"""Binding resolved configuration onto a typed schema.
+
+Three behaviours here are not negotiable, and each one is a lesson from a
+framework that got it wrong.
+
+**Every error at once.** A configuration file with four mistakes should take one
+run to fix, not four. environs added ``seal()`` for this; .NET's binder was
+still silently swallowing enum failures as late as its own 8.0 breaking-change
+note, which is headed "previously, the following code silently swallowed the
+exceptions".
+
+**Unknown keys are errors, by default.** A typo in a key name is the single most
+common configuration bug, and the usual behaviour -- bind what matches, ignore
+the rest -- makes it invisible. Spring ships a handler for this but does not
+turn it on. whence turns it on and adds a suggestion.
+
+**Nothing configured means ``None``.** An all-defaults object is
+indistinguishable from a section that was never written, which is how a typo in
+a section name goes unnoticed. Spring's ``BindResult`` makes the distinction and
+so does this.
+"""
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, replace
+from typing import Any, Protocol
+
+from ..errors import BindError
+from ..keys import KeyPath, canonical, join, suggest
+from ..origin import Origin, Tracked
+from ..secret import sanitize
+from ._dataclasses import DataclassBinder
+from ._pydantic import PydanticBinder, pydantic_available
+
+__all__ = [
+    "Binder",
+    "DataclassBinder",
+    "Problem",
+    "PydanticBinder",
+    "bind",
+    "choose_binder",
+    "pydantic_available",
+    "render_problems",
+]
+
+
+_BINDERS: "tuple[Binder, ...]" = (PydanticBinder(), DataclassBinder())
+
+
+@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, ...] = ()
+
+
+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)
+
+
+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.
+        """
+        ...
+
+
+def choose_binder(target: type) -> Binder:
+    """Pick the binder for a schema class.
+
+    pydantic is preferred when the target is one of its models and the package
+    is installed; otherwise the standard-library dataclass binder is used.
+
+    Args:
+        target: The schema class.
+
+    Returns:
+        A binder.
+
+    Raises:
+        BindError: If nothing can bind the target.
+    """
+    for binder in _BINDERS:
+        if binder.supports(target):
+            return binder
+    name = getattr(target, "__name__", str(target))
+    msg = (
+        f"cannot bind to {name}: whence binds dataclasses, and pydantic models "
+        "when pydantic is installed"
+    )
+    raise BindError(msg)
+
+
+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
+
+
+def _shadow_text(
+    key: str,
+    shadowed: Mapping[KeyPath, tuple[tuple[str, Tracked], ...]] | None,
+) -> tuple[str, ...]:
+    """Render the shadow chain for one key."""
+    if not shadowed:
+        return ()
+    entries = shadowed.get(canonical(key), ())
+    return tuple(f"{tracked.origin} = {sanitize(key, tracked.value)!r}" for _, tracked in entries)

whence/binding/_dataclasses.py

@@ -0,0 +1,144 @@
+"""Binding to frozen dataclasses, on the standard library alone.
+
+This is what keeps whence's zero-dependency claim honest: a project that does
+not want pydantic still gets typed, validated configuration. When pydantic *is*
+installed the other binder takes over automatically and you get its error
+quality for free.
+"""
+
+import dataclasses
+from collections.abc import Mapping
+from typing import Any, get_type_hints
+
+from ..keys import KeyPath, join
+from ..origin import RelativePath, Tracked
+from .coerce import CoercionError, coerce, is_optional
+
+__all__ = ["DataclassBinder", "declared_paths"]
+
+
+def _is_dataclass_type(annotation: Any) -> bool:
+    """Report whether an annotation is a nested dataclass to recurse into."""
+    return isinstance(annotation, type) and dataclasses.is_dataclass(annotation)
+
+
+def declared_paths(target: type, prefix: KeyPath = ()) -> set[KeyPath]:
+    """List every key path a dataclass declares, recursing into nested ones.
+
+    Args:
+        target: The dataclass.
+        prefix: The path it sits at.
+
+    Returns:
+        Every declared key path.
+    """
+    hints = get_type_hints(target)
+    out: set[KeyPath] = set()
+    for field in dataclasses.fields(target):
+        annotation = hints.get(field.name, Any)
+        path = (*prefix, field.name)
+        if _is_dataclass_type(annotation):
+            out |= declared_paths(annotation, path)
+        else:
+            out.add(path)
+    return out
+
+
+class DataclassBinder:
+    """Binds a subtree of configuration onto a dataclass."""
+
+    def supports(self, target: type) -> bool:
+        """Report whether this binder handles the target.
+
+        Args:
+            target: The schema class.
+
+        Returns:
+            True for any dataclass.
+        """
+        return dataclasses.is_dataclass(target)
+
+    def declared(self, target: type, prefix: KeyPath = ()) -> set[KeyPath]:
+        """List the key paths the target declares.
+
+        Args:
+            target: The dataclass.
+            prefix: The path it sits at.
+
+        Returns:
+            Every declared key path.
+        """
+        return declared_paths(target, prefix)
+
+    def bind(
+        self,
+        target: type,
+        values: Mapping[KeyPath, Tracked],
+        prefix: KeyPath = (),
+        problems: list[Any] | None = None,
+    ) -> Any:
+        """Construct the target from the resolved values.
+
+        Args:
+            target: The dataclass.
+            values: Flat resolved values.
+            prefix: The subtree to read.
+            problems: A list to append problems to. Errors are accumulated
+                rather than raised, so one run reports every mistake in the file
+                instead of the first.
+
+        Returns:
+            An instance of ``target``, or ``None`` if construction failed.
+        """
+        from . import Problem
+
+        collected = problems if problems is not None else []
+        # Scoped to this target: a sibling's problem recorded earlier in the
+        # shared list must not suppress an unrelated construction.
+        before = len(collected)
+        hints = get_type_hints(target)
+        kwargs: dict[str, Any] = {}
+        for field in dataclasses.fields(target):
+            if not field.init:
+                continue
+            annotation = hints.get(field.name, Any)
+            path = (*prefix, field.name)
+            if _is_dataclass_type(annotation):
+                nested = self.bind(annotation, values, path, collected)
+                if nested is not None:
+                    kwargs[field.name] = nested
+                continue
+            tracked = values.get(path)
+            if tracked is None:
+                if _has_default(field):
+                    continue
+                if is_optional(annotation):
+                    kwargs[field.name] = None
+                    continue
+                collected.append(
+                    Problem(join(path), None, None, "required, but nothing supplies it")
+                )
+                continue
+            try:
+                if annotation is RelativePath:
+                    kwargs[field.name] = RelativePath.resolve_against(tracked.value, tracked.origin)
+                    continue
+                kwargs[field.name] = coerce(tracked.value, annotation)
+            except (CoercionError, ValueError, TypeError) as exc:
+                collected.append(Problem(join(path), tracked.value, tracked.origin, str(exc)))
+        if len(collected) > before:
+            # Constructing anyway would raise TypeError for the very field
+            # already reported, and append a second `<root>` problem saying so.
+            return None
+        try:
+            return target(**kwargs)
+        except TypeError as exc:  # pragma: no cover - defensive
+            collected.append(Problem(join(prefix) or "<root>", None, None, str(exc)))
+            return None
+
+
+def _has_default(field: "dataclasses.Field[Any]") -> bool:
+    """Report whether a dataclass field can be left unset."""
+    return (
+        field.default is not dataclasses.MISSING or field.default_factory is not dataclasses.MISSING
+    )