xtr-dotenv 1.2.0__py3-none-any.whl

xtr_dotenv/__init__.py

@@ -0,0 +1,49 @@
+"""Layered dotenv files loaded into the environment, and the same layers behind settings.
+
+Real applications keep several ``.env`` files layered so a developer
+laptop, a CI runner and a production host each end up with the settings
+that suit, without any one file knowing about the other. This library is
+the loader every layer runs through, plus a pydantic-settings source that
+feeds a typed model from the same cascade.
+
+The two entry points a typical application needs are:
+
+* :class:`~xtr_dotenv.dotenv.Dotenv` — call ``Dotenv().boot_env(project_dir / ".env")``
+  at the process' entry point, before anything reads a settings model.
+* :class:`~xtr_dotenv.dotenv_settings.DotenvSettings` — a
+  :class:`~pydantic_settings.BaseSettings` base that gets the layered
+  values *without* mutating :data:`os.environ` itself.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .dotenv import PATH_VAR, TRACKING_VAR, Dotenv
+from .dotenv_settings import DotenvSettings
+from .dotenv_settings_source import DotenvSettingsSource
+from .exception import (
+    DotenvError,
+    FormatError,
+    PathError,
+    VariableCircularReferenceError,
+)
+
+try:
+    __version__ = version("xtr-dotenv")
+except PackageNotFoundError:  # pragma: no cover
+    # Running from a source tree with no installed metadata to read.
+    __version__ = "0+unknown"
+
+__all__ = [
+    "PATH_VAR",
+    "TRACKING_VAR",
+    "Dotenv",
+    "DotenvError",
+    "DotenvSettings",
+    "DotenvSettingsSource",
+    "FormatError",
+    "PathError",
+    "VariableCircularReferenceError",
+    "__version__",
+]

xtr_dotenv/bundle/__init__.py

@@ -0,0 +1,8 @@
+"""The xtr-dependency-injection bundle for xtr-dotenv."""
+
+from __future__ import annotations
+
+from .dotenv_bundle import DotenvBundle
+from .dotenv_config import DotenvConfig
+
+__all__ = ["DotenvBundle", "DotenvConfig"]

xtr_dotenv/bundle/dotenv_bundle.py

@@ -0,0 +1,52 @@
+"""The xtr-dotenv bundle: exposes the dotenv commands when a console is present.
+
+The bundle does **not** load files itself. The application is expected to
+call ``Dotenv().boot_env(project_dir / ".env")`` at its entry point,
+before building the kernel: the kernel and every service it creates rely
+on the environment already being layered by the time they read it.
+
+What the bundle does supply is the two commands — ``dotenv:dump`` and
+``debug:dotenv`` — that need the container's ``KernelInterface`` to know
+the project directory. They are loaded only when the console bundle is
+active, so a headless application still boots to zero config.
+"""
+
+from __future__ import annotations
+
+from typing import final
+
+from typing_extensions import override
+from xtr_dependency_injection import (
+    Bundle,
+    ContainerBuilder,
+    ServiceConfigurator,
+    as_bundle,
+    bundle_active,
+)
+
+from .dotenv_config import DotenvConfig
+
+__all__ = ["DotenvBundle"]
+
+
+@final
+@as_bundle("dotenv", config=DotenvConfig)
+class DotenvBundle(Bundle[DotenvConfig]):
+    """Wire the dotenv commands into the container when a console is around."""
+
+    @override
+    def load_extension(
+        self,
+        config: DotenvConfig,
+        services: ServiceConfigurator,
+        builder: ContainerBuilder,
+    ) -> None:
+        """Load the command module only when a console bundle is active.
+
+        Loading a command module late is the pattern the messenger bundle
+        uses too: it keeps the console dependency out of the runtime graph
+        for applications that do not run one, and does no I/O at build.
+        """
+        del config
+        if bundle_active(builder, "console"):
+            services.load("xtr_dotenv.command")

xtr_dotenv/bundle/dotenv_config.py

@@ -0,0 +1,61 @@
+"""Configuration for :class:`~xtr_dotenv.bundle.dotenv_bundle.DotenvBundle`."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+__all__ = ["DotenvConfig"]
+
+
+@dataclass(frozen=True, slots=True)
+class DotenvConfig:
+    """How the dotenv bundle describes the layered cascade to its commands.
+
+    The bundle itself does no I/O: an application calls
+    ``Dotenv().boot_env(...)`` at its entry point before building the
+    kernel. What lives here is the description the ``dotenv:dump`` and
+    ``debug:dotenv`` commands read to reason about the same cascade.
+
+    Attributes:
+        path: The base ``.env`` path. ``%kernel.project_dir%`` and every other
+            parameter reference is resolved by the kernel; a relative path is
+            taken from the project directory.
+        env_key: The variable naming the active environment.
+        debug_key: The variable naming debug mode.
+        test_envs: Environments where the ``.local`` overlay is skipped.
+        prod_envs: Environments considered production for debug defaulting.
+
+    Raises:
+        ValueError: When any of ``path``, ``env_key``, ``debug_key``,
+            ``test_envs`` or ``prod_envs`` is empty.
+    """
+
+    path: str = "%kernel.project_dir%/.env"
+    env_key: str = "APP_ENV"
+    debug_key: str = "APP_DEBUG"
+    test_envs: tuple[str, ...] = ("test",)
+    prod_envs: tuple[str, ...] = ("prod",)
+
+    def __post_init__(self) -> None:
+        """Refuse combinations the loader would silently accept but not mean."""
+        if not self.path:
+            message = "path must not be empty"
+            raise ValueError(message)
+        if not self.env_key:
+            message = "env_key must not be empty"
+            raise ValueError(message)
+        if not self.debug_key:
+            message = "debug_key must not be empty"
+            raise ValueError(message)
+        if not self.test_envs:
+            message = "test_envs must not be empty"
+            raise ValueError(message)
+        if not self.prod_envs:
+            message = "prod_envs must not be empty"
+            raise ValueError(message)
+
+    def base_path(self, project_dir: Path) -> Path:
+        """Return :attr:`path`, taken from ``project_dir`` when it is relative."""
+        candidate = Path(self.path)
+        return candidate if candidate.is_absolute() else project_dir / candidate

xtr_dotenv/command/__init__.py

@@ -0,0 +1,8 @@
+"""Console commands the dotenv bundle contributes when a console is active."""
+
+from __future__ import annotations
+
+from .debug_dotenv_command import DebugDotenvCommand
+from .dotenv_dump_command import DotenvDumpCommand
+
+__all__ = ["DebugDotenvCommand", "DotenvDumpCommand"]

xtr_dotenv/command/debug_dotenv_command.py

@@ -0,0 +1,90 @@
+"""``debug:dotenv``: list the cascade files and each variable's value per file."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import final
+
+from xtr_console import ConsoleStyle, ExitCode, as_command
+from xtr_dependency_injection import (  # noqa: TC002 — engine reads annotations at runtime.
+    Injected,
+    KernelInterface,
+)
+
+from xtr_dotenv.bundle.dotenv_config import (  # noqa: TC001 — engine reads annotations at runtime.
+    DotenvConfig,
+)
+from xtr_dotenv.dotenv import Dotenv
+from xtr_dotenv.exception import DotenvError
+
+__all__ = ["DebugDotenvCommand"]
+
+
+@as_command("debug:dotenv")
+@final
+class DebugDotenvCommand:
+    """List every file in the cascade and each variable's value per file.
+
+    Missing files are shown too, in order, so a debugger can see exactly
+    what the loader would have done. ``name`` filters the value listing to
+    a single variable, which is what a "why is this value what it is?"
+    session usually needs.
+    """
+
+    async def __call__(
+        self,
+        io: ConsoleStyle,
+        kernel: Injected[KernelInterface],
+        config: Injected[DotenvConfig],
+        name: str | None = None,
+    ) -> int:
+        """Print the cascade files and (optionally) one variable across them."""
+        base_path = config.base_path(kernel.project_dir)
+        env = kernel.environment
+        cascade_paths = _cascade_paths(base_path, env, config.test_envs)
+        io.section(f"Cascade for env={env!r} at {base_path}")
+        io.table(
+            ("File", "Status"),
+            tuple(
+                (str(candidate), "loaded" if candidate.exists() else "missing")
+                for candidate in cascade_paths
+            ),
+        )
+        per_file: list[tuple[str, dict[str, str]]] = []
+        for candidate in cascade_paths:
+            if not candidate.exists():
+                continue
+            try:
+                loader = Dotenv(env_key=config.env_key, environ={config.env_key: env})
+                # Parse a single file to see what IT contributes; expansion is
+                # done against the env key alone so the output is per-file.
+                parsed = loader.parse(candidate.read_text(encoding="utf-8"), str(candidate))
+            except DotenvError as error:
+                io.error(f"{candidate}: {error}")
+                return ExitCode.FAILURE
+            per_file.append((str(candidate), parsed))
+        rows: list[tuple[str, str, str]] = []
+        for file_label, values in per_file:
+            for var_name, value in sorted(values.items()):
+                if name is not None and var_name != name:
+                    continue
+                rows.append((file_label, var_name, value))
+        if rows:
+            io.table(("File", "Variable", "Value"), tuple(rows))
+        elif name is not None:
+            io.note(f"variable {name!r} not present in any cascade file")
+        return ExitCode.SUCCESS
+
+
+def _cascade_paths(base: Path, env: str, test_envs: tuple[str, ...]) -> list[Path]:
+    """List the cascade files in the order the loader would try them."""
+    paths: list[Path] = [base]
+    dist = Path(f"{base}.dist")
+    if not base.exists() and dist.exists():
+        paths.append(dist)
+    if env not in test_envs:
+        paths.append(Path(f"{base}.local"))
+    if env != "local":
+        paths.append(Path(f"{base}.{env}"))
+        paths.append(Path(f"{base}.{env}.local"))
+    return paths

xtr_dotenv/command/dotenv_dump_command.py

@@ -0,0 +1,70 @@
+"""``dotenv:dump``: compile the cascade for one env into ``<path>.local.json``."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import final
+
+from xtr_console import ConsoleStyle, ExitCode, as_command
+from xtr_dependency_injection import (  # noqa: TC002 — engine reads annotations at runtime.
+    Injected,
+    KernelInterface,
+)
+
+from xtr_dotenv.bundle.dotenv_config import (  # noqa: TC001 — engine reads annotations at runtime.
+    DotenvConfig,
+)
+from xtr_dotenv.dotenv import PATH_VAR, TRACKING_VAR, Dotenv
+from xtr_dotenv.exception import DotenvError
+
+__all__ = ["DotenvDumpCommand"]
+
+
+@as_command("dotenv:dump")
+@final
+class DotenvDumpCommand:
+    """Compile the layered cascade for one env into ``<path>.local.json``.
+
+    The dump is what :meth:`Dotenv.boot_env` reads for a fast start. It is
+    computed on a **fresh environ** carrying only the env key (never real
+    secrets), so the file it writes is safe to commit and travels with the
+    build.
+    """
+
+    async def __call__(
+        self,
+        io: ConsoleStyle,
+        kernel: Injected[KernelInterface],
+        config: Injected[DotenvConfig],
+        env: str | None = None,
+    ) -> int:
+        """Write the compiled cascade for ``env`` (default: the kernel's env)."""
+        target_env = env if env is not None else kernel.environment
+        base_path = config.base_path(kernel.project_dir)
+        sandbox: dict[str, str] = {config.env_key: target_env}
+        loader = Dotenv(env_key=config.env_key, environ=sandbox)
+        try:
+            _ = loader.load_env(
+                str(base_path),
+                default_env=target_env,
+                test_envs=config.test_envs,
+            )
+        except DotenvError as error:
+            io.error(f"cannot compile cascade: {error}")
+            return ExitCode.FAILURE
+        payload = _extract(sandbox)
+        dump_path = Path(f"{base_path}.local.json")
+        _write(dump_path, json.dumps(payload, indent=2, sort_keys=True))
+        io.success(f"wrote {dump_path} ({len(payload)} values)")
+        return ExitCode.SUCCESS
+
+
+def _write(path: Path, content: str) -> None:
+    """Blocking write, isolated so the async ``__call__`` stays lint-clean."""
+    _ = path.write_text(content, encoding="utf-8")
+
+
+def _extract(sandbox: dict[str, str]) -> dict[str, str]:
+    """Drop the internal bookkeeping variables before serialising."""
+    return {name: value for name, value in sandbox.items() if name not in {TRACKING_VAR, PATH_VAR}}