whence 1.0.0__py3-none-any.whl

whence/binding/_pydantic.py

@@ -0,0 +1,120 @@
+"""Binding to pydantic models, when pydantic is installed.
+
+whence never imports pydantic at module scope and never declares it as a
+dependency. The binder is selected only when ``pydantic`` is importable, which
+is what lets the same library serve a zero-dependency project and a
+pydantic-native one.
+
+The interesting work is the last step: pydantic reports errors with a ``loc``
+tuple, and whence holds a map from key path to origin keyed identically. Joining
+them at the key is what produces an error that names the file and line, which no
+Python library does today.
+"""
+
+import functools
+from collections.abc import Mapping
+from importlib.util import find_spec
+from typing import Any
+
+from ..keys import KeyPath, join
+from ..origin import Tracked
+from ..tree import unflatten
+
+__all__ = ["PydanticBinder", "pydantic_available"]
+
+
+@functools.cache
+def pydantic_available() -> bool:
+    """Report whether pydantic can be imported.
+
+    Returns:
+        True when the package is installed.
+    """
+    return find_spec("pydantic") is not None
+
+
+class PydanticBinder:
+    """Binds a subtree of configuration onto a pydantic model."""
+
+    def supports(self, target: type) -> bool:
+        """Report whether this binder handles the target.
+
+        Args:
+            target: The schema class.
+
+        Returns:
+            True for a ``pydantic.BaseModel`` subclass.
+        """
+        if not pydantic_available():
+            return False
+        import pydantic
+
+        return issubclass(target, pydantic.BaseModel)
+
+    def declared(self, target: type, prefix: KeyPath = ()) -> set[KeyPath]:
+        """List the key paths the model declares, recursing into sub-models.
+
+        Args:
+            target: The model.
+            prefix: The path it sits at.
+
+        Returns:
+            Every declared key path.
+        """
+        import pydantic
+
+        out: set[KeyPath] = set()
+        for name, info in target.model_fields.items():  # type: ignore[attr-defined]
+            annotation = info.annotation
+            path = (*prefix, name)
+            if isinstance(annotation, type) and issubclass(annotation, pydantic.BaseModel):
+                out |= self.declared(annotation, path)
+            else:
+                out.add(path)
+        return out
+
+    def bind(
+        self,
+        target: type,
+        values: Mapping[KeyPath, Tracked],
+        prefix: KeyPath = (),
+        problems: list[Any] | None = None,
+    ) -> Any:
+        """Validate the subtree into a model instance.
+
+        Args:
+            target: The model.
+            values: Flat resolved values.
+            prefix: The subtree to read.
+            problems: A list to append problems to.
+
+        Returns:
+            A model instance, or ``None`` when validation failed.
+        """
+        import pydantic
+
+        from . import Problem
+
+        collected = problems if problems is not None else []
+        depth = len(prefix)
+        subtree = {
+            path[depth:]: tracked.value
+            for path, tracked in values.items()
+            if path[:depth] == prefix and len(path) > depth
+        }
+        try:
+            return target.model_validate(unflatten(subtree))  # type: ignore[attr-defined]
+        except pydantic.ValidationError as exc:
+            for error in exc.errors():
+                loc = tuple(str(part) for part in error["loc"])
+                path = (*prefix, *loc)
+                tracked = values.get(path)
+                collected.append(
+                    Problem(
+                        join(path),
+                        None if tracked is None else tracked.value,
+                        None if tracked is None else tracked.origin,
+                        error["msg"],
+                    )
+                )
+            return None

whence/binding/coerce.py

@@ -0,0 +1,220 @@
+"""Turning strings into the types a schema asks for.
+
+No message in this module 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;
+the standard library's own conversion errors quote the input, so they are caught
+and replaced rather than passed through.
+
+Environment variables and ``.properties`` files carry only strings, so some
+coercion is unavoidable. The rule whence follows is that coercion is **never a
+global guess**: a list is JSON when the string opens with ``[`` and
+comma-separated otherwise, and everything else is driven by the declared field
+type. The three conventions in the wild -- JSON, comma-separated and indexed
+keys -- are irreconcilable, so guessing between them by inspection is how a
+value silently becomes the wrong shape.
+"""
+
+import datetime as dt
+import json
+import uuid
+from collections.abc import Callable, Mapping, Sequence
+from enum import Enum
+from pathlib import Path
+from types import UnionType
+from typing import Annotated, Any, Literal, Union, get_args, get_origin
+
+from ..secret import Secret
+
+__all__ = ["TRUE", "coerce", "is_optional", "strip_annotated"]
+
+TRUE = frozenset({"1", "true", "yes", "on", "y", "t"})
+"""Strings that mean ``True``; everything else that parses means ``False``."""
+
+FALSE = frozenset({"0", "false", "no", "off", "n", "f", ""})
+
+
+class CoercionError(ValueError):
+    """A value could not be converted to the declared type."""
+
+
+def strip_annotated(annotation: Any) -> Any:
+    """Return the type an annotation declares, without its metadata.
+
+    ``Annotated[int, Value("x")]`` declares an ``int``; the metadata is for
+    whoever put it there. Stripping is recursive because nesting is legal.
+
+    Args:
+        annotation: A type annotation, annotated or not.
+
+    Returns:
+        The underlying type.
+    """
+    while get_origin(annotation) is Annotated:
+        annotation = get_args(annotation)[0]
+    return annotation
+
+
+def is_optional(annotation: Any) -> bool:
+    """Report whether an annotation admits ``None``.
+
+    Args:
+        annotation: A type annotation.
+
+    Returns:
+        True for ``X | None`` and ``Optional[X]``.
+    """
+    annotation = strip_annotated(annotation)
+    return get_origin(annotation) in (Union, UnionType) and type(None) in get_args(annotation)
+
+
+def _non_none(annotation: Any) -> Any:
+    """Strip ``None`` from an optional annotation."""
+    args = [a for a in get_args(annotation) if a is not type(None)]
+    return args[0] if len(args) == 1 else annotation
+
+
+def _to_bool(value: Any) -> bool:
+    """Parse a boolean from a string or a number."""
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (int, float)):
+        return bool(value)
+    text = str(value).strip().lower()
+    if text in TRUE:
+        return True
+    if text in FALSE:
+        return False
+    msg = f"expected a boolean; accepted spellings are {sorted(TRUE | FALSE - {''})}"
+    raise CoercionError(msg)
+
+
+def _to_timedelta(value: Any) -> dt.timedelta:
+    """Parse a duration from seconds or a ``1h30m`` style string."""
+    if isinstance(value, dt.timedelta):
+        return value
+    if isinstance(value, (int, float)):
+        return dt.timedelta(seconds=float(value))
+    text = str(value).strip().lower()
+    try:
+        return dt.timedelta(seconds=float(text))
+    except ValueError:
+        pass
+    units = {"d": 86400.0, "h": 3600.0, "m": 60.0, "s": 1.0, "ms": 0.001}
+    total, number = 0.0, ""
+    i = 0
+    while i < len(text):
+        if text[i].isdigit() or text[i] == ".":
+            number += text[i]
+            i += 1
+            continue
+        unit = text[i : i + 2] if text[i : i + 2] in units else text[i]
+        if unit not in units or not number:
+            msg = "expected a duration such as '30s', '1h30m' or a number of seconds"
+            raise CoercionError(msg)
+        total += float(number) * units[unit]
+        number = ""
+        i += len(unit)
+    if number:
+        total += float(number)
+    return dt.timedelta(seconds=total)
+
+
+def _split_list(text: str) -> list[Any]:
+    """Split a list from JSON or from commas."""
+    stripped = text.strip()
+    if stripped.startswith("["):
+        loaded = json.loads(stripped)
+        if isinstance(loaded, list):
+            return loaded
+    return [part.strip() for part in stripped.split(",") if part.strip()]
+
+
+_SCALARS: Mapping[Any, Callable[[Any], Any]] = {
+    bool: _to_bool,
+    int: lambda v: v if isinstance(v, int) and not isinstance(v, bool) else int(str(v).strip()),
+    float: lambda v: float(v) if isinstance(v, (int, float)) else float(str(v).strip()),
+    str: lambda v: v if isinstance(v, str) else str(v),
+    Path: lambda v: v if isinstance(v, Path) else Path(str(v)),
+    uuid.UUID: lambda v: v if isinstance(v, uuid.UUID) else uuid.UUID(str(v)),
+    dt.timedelta: _to_timedelta,
+    dt.datetime: lambda v: v if isinstance(v, dt.datetime) else dt.datetime.fromisoformat(str(v)),
+    dt.date: lambda v: v if isinstance(v, dt.date) else dt.date.fromisoformat(str(v)),
+    Secret: lambda v: v if isinstance(v, Secret) else Secret(str(v)),
+}
+
+
+def coerce(value: Any, annotation: Any) -> Any:
+    """Convert a loaded value to the type a field declares.
+
+    Args:
+        value: The value as a source produced it.
+        annotation: The declared type.
+
+    Returns:
+        The converted value.
+
+    Raises:
+        CoercionError: If the value cannot be converted.
+    """
+    annotation = strip_annotated(annotation)
+    if annotation is Any or annotation is None:
+        return value
+    if is_optional(annotation):
+        if value is None or (isinstance(value, str) and value.strip() == ""):
+            return None
+        return coerce(value, _non_none(annotation))
+
+    origin = get_origin(annotation)
+    if origin is Literal:
+        allowed = get_args(annotation)
+        for option in allowed:
+            if value == option or str(value) == str(option):
+                return option
+        msg = f"expected one of {list(allowed)}"
+        raise CoercionError(msg)
+
+    if isinstance(annotation, type) and issubclass(annotation, Enum):
+        for member in annotation:
+            if value is member or value == member.value or str(value) == str(member.value):
+                return member
+        try:
+            return annotation[str(value)]
+        except KeyError:
+            msg = f"expected one of {[m.value for m in annotation]}"
+            raise CoercionError(msg) from None
+
+    if origin in (list, tuple, set, frozenset):
+        items = _split_list(value) if isinstance(value, str) else list(value)
+        args = get_args(annotation)
+        inner = args[0] if args and args[0] is not Ellipsis else Any
+        converted = [coerce(item, inner) for item in items]
+        return origin(converted) if origin is not list else converted
+
+    if origin is dict:
+        raw = json.loads(value) if isinstance(value, str) else value
+        if not isinstance(raw, Mapping):
+            msg = "expected a mapping"
+            raise CoercionError(msg)
+        args = get_args(annotation)
+        kt, vt = (*args, Any, Any)[:2]
+        return {coerce(k, kt): coerce(v, vt) for k, v in raw.items()}
+
+    convert = _SCALARS.get(annotation)
+    if convert is not None:
+        try:
+            return convert(value)
+        except CoercionError:
+            raise
+        except (TypeError, ValueError) as exc:
+            # Deliberately not `{exc}`: the standard library embeds the rejected
+            # input in its message ("invalid literal for int() ... 'hunter2'"),
+            # and that value may be a secret.
+            name = getattr(annotation, "__name__", str(annotation))
+            msg = f"could not convert to {name}"
+            raise CoercionError(msg) from exc
+
+    if isinstance(annotation, type) and isinstance(value, annotation):
+        return value
+    if isinstance(value, Sequence) and not isinstance(value, str):
+        return value
+    return value

whence/chain.py

@@ -0,0 +1,176 @@
+"""The ordered, named chain of sources.
+
+Precedence is position in a list whose entries have names, not an integer
+ordinal. Both models exist in the wild -- Spring uses a name-addressable list,
+SmallRye uses integer ordinals -- and the list wins for the primary model: a
+third-party source can say "immediately above the ``.env`` file" without knowing
+what everything else chose, and two sources can never tie.
+
+Ordinals remain available as sugar through :meth:`SourceChain.insert_by_ordinal`,
+because letting an operator drop in a file that outranks the environment without
+touching code is genuinely useful. They are converted to a position on insert,
+so the ambiguity stays at the edge.
+"""
+
+from collections.abc import Iterator, Sequence
+
+from .errors import ConfigError
+from .sources import Source
+from .tree import Resolved, resolve
+
+__all__ = ["SourceChain"]
+
+
+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)

whence/cli.py

@@ -0,0 +1,83 @@
+"""The ``whence`` command: explain, dump, discovery.
+
+One discipline, learned from someone else's outage: **data goes to stdout,
+diagnostics go to stderr, and the library itself never prints at all.** Node's
+dotenv added a single ``console.log`` on stdout and broke a JSON-RPC transport
+in the wild, because a library that writes to stdout is a library that corrupts
+whatever pipeline it is embedded in.
+"""
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+
+from .config import Config
+from .errors import WhenceError
+
+__all__ = ["main"]
+
+
+def _parser() -> argparse.ArgumentParser:
+    """Build the argument parser."""
+    parser = argparse.ArgumentParser(
+        prog="whence",
+        description="Inspect layered configuration and where each value came from.",
+    )
+    parser.add_argument("app", help="application name, e.g. myapp")
+    parser.add_argument(
+        "command",
+        choices=("explain", "dump", "discovery"),
+        help="explain one key, dump every value, or show how files were searched for",
+    )
+    parser.add_argument("key", nargs="?", help="dotted key, for `explain`")
+    parser.add_argument(
+        "-p",
+        "--profile",
+        action="append",
+        default=None,
+        dest="profiles",
+        help="activate a profile; repeat for several, last wins",
+    )
+    parser.add_argument("--json", action="store_true", help="emit JSON, for `dump`")
+    parser.add_argument(
+        "--reveal",
+        action="store_true",
+        help="do not redact secrets; pass this only deliberately",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command-line interface.
+
+    Args:
+        argv: Arguments, defaulting to ``sys.argv[1:]``.
+
+    Returns:
+        A process exit code.
+    """
+    args = _parser().parse_args(argv)
+    try:
+        config = Config.load(args.app, profiles=args.profiles)
+        if args.command == "discovery":
+            print(config.discovery_report())
+        elif args.command == "dump":
+            data = config.dump(reveal=args.reveal)
+            if args.json:
+                print(json.dumps(data, indent=2, default=str))
+            else:
+                print("\n".join(f"{key} = {value!r}" for key, value in data.items()))
+        else:
+            if not args.key:
+                print("explain needs a key, e.g. `whence myapp explain db.host`", file=sys.stderr)
+                return 2
+            print(config.explain(args.key))
+    except WhenceError as exc:
+        print(f"whence: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())