lib-layered-config 4.1.0__py3-none-any.whl

lib_layered_config/adapters/path_resolvers/_linux.py

@@ -0,0 +1,89 @@
+"""Linux-specific path resolution strategy.
+
+Implement path resolution following XDG Base Directory specification
+and traditional ``/etc`` conventions.
+
+Contents:
+    - ``LinuxStrategy``: yields paths for app, host, user, and dotenv layers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+
+from ._base import PlatformStrategy, collect_layer
+
+
+class LinuxStrategy(PlatformStrategy):
+    """Resolve paths following Linux/XDG conventions.
+
+    Mirror the XDG specification and ``/etc`` conventions documented in the
+    system design.
+
+    Path Layouts:
+        - App: ``/etc/xdg/<slug>`` then ``/etc/<slug>``
+        - Host: ``<etc>/<slug>/hosts/<hostname>.toml``
+        - User: ``$XDG_CONFIG_HOME/<slug>`` or ``~/.config/<slug>``
+        - Dotenv: ``$XDG_CONFIG_HOME/<slug>/.env``
+    """
+
+    def app_paths(self) -> Iterable[str]:
+        """Yield Linux application-default configuration paths.
+
+        Provide deterministic discovery following XDG Base Directory specification.
+        Checks ``/etc/xdg/<slug>`` first (XDG system-wide default), then falls back
+        to ``/etc/<slug>`` for backwards compatibility.
+
+        Returns:
+            Paths under ``/etc/xdg`` and ``/etc`` (or overridden root).
+        """
+        etc_root = Path(self.ctx.env.get("LIB_LAYERED_CONFIG_ETC", "/etc"))
+        profile_seg = self._profile_segment()
+        # Check XDG-compliant location first
+        yield from collect_layer(etc_root / "xdg" / self.ctx.slug / profile_seg)
+        # Fall back to traditional /etc location for backwards compatibility
+        yield from collect_layer(etc_root / self.ctx.slug / profile_seg)
+
+    def host_paths(self) -> Iterable[str]:
+        """Yield Linux host-specific configuration paths.
+
+        Allow installations to override defaults per hostname following XDG specification.
+        Checks ``/etc/xdg/<slug>/hosts`` first, then falls back to ``/etc/<slug>/hosts``.
+
+        Returns:
+            Host-level configuration paths (empty when missing).
+        """
+        etc_root = Path(self.ctx.env.get("LIB_LAYERED_CONFIG_ETC", "/etc"))
+        profile_seg = self._profile_segment()
+        # Check XDG-compliant location first
+        xdg_candidate = etc_root / "xdg" / self.ctx.slug / profile_seg / "hosts" / f"{self.ctx.hostname}.toml"
+        if xdg_candidate.is_file():
+            yield str(xdg_candidate)
+        # Fall back to traditional /etc location for backwards compatibility
+        candidate = etc_root / self.ctx.slug / profile_seg / "hosts" / f"{self.ctx.hostname}.toml"
+        if candidate.is_file():
+            yield str(candidate)
+
+    def user_paths(self) -> Iterable[str]:
+        """Yield Linux user-specific configuration paths.
+
+        Honour XDG directories while falling back to ``~/.config``.
+
+        Returns:
+            User-level configuration paths.
+        """
+        xdg = self.ctx.env.get("XDG_CONFIG_HOME")
+        base = Path(xdg) if xdg else Path.home() / ".config"
+        profile_seg = self._profile_segment()
+        yield from collect_layer(base / self.ctx.slug / profile_seg)
+
+    def dotenv_path(self) -> Path | None:
+        """Return Linux-specific ``.env`` fallback path.
+
+        Returns:
+            Path to ``$XDG_CONFIG_HOME/<slug>/.env``.
+        """
+        base = Path(self.ctx.env.get("XDG_CONFIG_HOME", Path.home() / ".config"))
+        profile_seg = self._profile_segment()
+        return base / self.ctx.slug / profile_seg / ".env"

lib_layered_config/adapters/path_resolvers/_macos.py

@@ -0,0 +1,93 @@
+"""macOS-specific path resolution strategy.
+
+Implement path resolution following macOS Application Support conventions.
+
+Contents:
+    - ``MacOSStrategy``: yields paths for app, host, user, and dotenv layers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+
+from ._base import PlatformStrategy, collect_layer
+
+
+class MacOSStrategy(PlatformStrategy):
+    """Resolve paths following macOS Application Support conventions.
+
+    Follow macOS conventions for vendor/app directories under
+    ``/Library/Application Support`` and ``~/Library/Application Support``.
+
+    Path Layouts:
+        - App: ``/Library/Application Support/<Vendor>/<App>``
+        - Host: ``<app>/hosts/<hostname>.toml``
+        - User: ``~/Library/Application Support/<Vendor>/<App>``
+        - Dotenv: ``~/Library/Application Support/<Vendor>/<App>/.env``
+    """
+
+    def _app_root(self) -> Path:
+        """Return the base directory for system-wide Application Support.
+
+        Returns:
+            ``/Library/Application Support`` or overridden root.
+        """
+        default_root = Path("/Library/Application Support")
+        return Path(self.ctx.env.get("LIB_LAYERED_CONFIG_MAC_APP_ROOT", default_root))
+
+    def _home_root(self) -> Path:
+        """Return the base directory for user-level Application Support.
+
+        Returns:
+            ``~/Library/Application Support`` or overridden root.
+        """
+        home_default = Path.home() / "Library/Application Support"
+        return Path(self.ctx.env.get("LIB_LAYERED_CONFIG_MAC_HOME_ROOT", home_default))
+
+    def app_paths(self) -> Iterable[str]:
+        """Yield macOS application-default configuration paths.
+
+        Follow macOS Application Support directory conventions.
+
+        Returns:
+            Application-level configuration paths.
+        """
+        profile_seg = self._profile_segment()
+        yield from collect_layer(self._app_root() / self.ctx.vendor / self.ctx.app / profile_seg)
+
+    def host_paths(self) -> Iterable[str]:
+        """Yield macOS host-specific configuration paths.
+
+        Support host overrides stored under ``hosts/<hostname>.toml`` within
+        Application Support.
+
+        Returns:
+            Host-level macOS configuration paths (empty when missing).
+        """
+        profile_seg = self._profile_segment()
+        candidate = (
+            self._app_root() / self.ctx.vendor / self.ctx.app / profile_seg / "hosts" / f"{self.ctx.hostname}.toml"
+        )
+        if candidate.is_file():
+            yield str(candidate)
+
+    def user_paths(self) -> Iterable[str]:
+        """Yield macOS user-specific configuration paths.
+
+        Honour per-user Application Support directories with optional overrides.
+
+        Returns:
+            User-level macOS configuration paths.
+        """
+        profile_seg = self._profile_segment()
+        yield from collect_layer(self._home_root() / self.ctx.vendor / self.ctx.app / profile_seg)
+
+    def dotenv_path(self) -> Path | None:
+        """Return macOS-specific ``.env`` fallback path.
+
+        Returns:
+            Path to ``~/Library/Application Support/<Vendor>/<App>/.env``.
+        """
+        profile_seg = self._profile_segment()
+        return self._home_root() / self.ctx.vendor / self.ctx.app / profile_seg / ".env"

lib_layered_config/adapters/path_resolvers/_windows.py

@@ -0,0 +1,126 @@
+"""Windows-specific path resolution strategy.
+
+Implement path resolution following Windows ProgramData/AppData conventions.
+
+Contents:
+    - ``WindowsStrategy``: yields paths for app, host, user, and dotenv layers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from pathlib import Path
+
+from ._base import PlatformStrategy, collect_layer
+
+
+class WindowsStrategy(PlatformStrategy):
+    """Resolve paths following Windows directory conventions.
+
+    Respect ``%ProgramData%`` and ``%APPDATA%/%LOCALAPPDATA%`` layouts with
+    override support for portable deployments.
+
+    Path Layouts:
+        - App: ``%ProgramData%/<Vendor>/<App>``
+        - Host: ``<app>/hosts/<hostname>.toml``
+        - User: ``%APPDATA%/<Vendor>/<App>`` (fallback to ``%LOCALAPPDATA%``)
+        - Dotenv: ``%APPDATA%/<Vendor>/<App>/.env``
+    """
+
+    def _program_data_root(self) -> Path:
+        """Return the base directory for ProgramData lookups.
+
+        Centralise overrides for ``%ProgramData%`` so tests can supply temporary roots.
+
+        Returns:
+            Resolved ProgramData root directory.
+        """
+        return Path(
+            self.ctx.env.get(
+                "LIB_LAYERED_CONFIG_PROGRAMDATA",
+                self.ctx.env.get("ProgramData", r"C:\ProgramData"),
+            )
+        )
+
+    def _appdata_root(self) -> Path:
+        """Return the user AppData root used for ``%APPDATA%`` lookups.
+
+        Support overrides in tests or portable deployments.
+
+        Returns:
+            Resolved AppData root directory.
+        """
+        return Path(
+            self.ctx.env.get(
+                "LIB_LAYERED_CONFIG_APPDATA",
+                self.ctx.env.get("APPDATA", Path.home() / "AppData" / "Roaming"),
+            )
+        )
+
+    def _localappdata_root(self) -> Path:
+        """Return the fallback LocalAppData root.
+
+        Provide a deterministic fallback when ``%APPDATA%`` does not exist.
+
+        Returns:
+            Resolved LocalAppData root directory.
+        """
+        return Path(
+            self.ctx.env.get(
+                "LIB_LAYERED_CONFIG_LOCALAPPDATA",
+                self.ctx.env.get("LOCALAPPDATA", Path.home() / "AppData" / "Local"),
+            )
+        )
+
+    def app_paths(self) -> Iterable[str]:
+        """Yield Windows application-default configuration paths.
+
+        Mirror ``%ProgramData%/<Vendor>/<App>`` layouts with override support.
+
+        Returns:
+            Application-level Windows configuration paths.
+        """
+        profile_seg = self._profile_segment()
+        base = self._program_data_root() / self.ctx.vendor / self.ctx.app / profile_seg
+        yield from collect_layer(base)
+
+    def host_paths(self) -> Iterable[str]:
+        """Yield Windows host-specific configuration paths.
+
+        Enable host overrides within ``%ProgramData%/<Vendor>/<App>/hosts``.
+
+        Returns:
+            Host-level Windows configuration paths.
+        """
+        profile_seg = self._profile_segment()
+        base = self._program_data_root() / self.ctx.vendor / self.ctx.app / profile_seg
+        candidate = base / "hosts" / f"{self.ctx.hostname}.toml"
+        if candidate.is_file():
+            yield str(candidate)
+
+    def user_paths(self) -> Iterable[str]:
+        """Yield Windows user-specific configuration paths.
+
+        Honour ``%APPDATA%`` with a fallback to ``%LOCALAPPDATA%`` for portable setups.
+
+        Returns:
+            User-level Windows configuration paths.
+        """
+        profile_seg = self._profile_segment()
+        roaming_base = self._appdata_root() / self.ctx.vendor / self.ctx.app / profile_seg
+        roaming_paths = list(collect_layer(roaming_base))
+        if roaming_paths:
+            yield from roaming_paths
+            return
+
+        local_base = self._localappdata_root() / self.ctx.vendor / self.ctx.app / profile_seg
+        yield from collect_layer(local_base)
+
+    def dotenv_path(self) -> Path | None:
+        """Return Windows-specific ``.env`` fallback path.
+
+        Returns:
+            Path to ``%APPDATA%/<Vendor>/<App>/.env``.
+        """
+        profile_seg = self._profile_segment()
+        return self._appdata_root() / self.ctx.vendor / self.ctx.app / profile_seg / ".env"

lib_layered_config/adapters/path_resolvers/default.py

@@ -0,0 +1,194 @@
+"""Filesystem path resolution using platform-specific strategies.
+
+Implement the :class:`lib_layered_config.application.ports.PathResolver`
+port using the Strategy pattern for clean platform-specific handling.
+
+Contents:
+    - ``DefaultPathResolver``: public adapter consumed by the composition root.
+    - Platform strategies in ``_linux.py``, ``_macos.py``, ``_windows.py``.
+
+System Integration:
+    Produces ordered path lists for the core merge pipeline. All filesystem
+    knowledge stays here so inner layers remain filesystem-agnostic.
+"""
+
+from __future__ import annotations
+
+import os
+import socket
+import sys
+from collections.abc import Iterable
+from pathlib import Path
+
+from ...domain.identifiers import (
+    validate_hostname,
+    validate_identifier,
+    validate_profile,
+    validate_vendor_app,
+)
+from ...observability import log_debug
+from ._base import PlatformContext, PlatformStrategy
+from ._dotenv import DotenvPathFinder
+from ._linux import LinuxStrategy
+from ._macos import MacOSStrategy
+from ._windows import WindowsStrategy
+
+
+class DefaultPathResolver:
+    """Resolve candidate paths for each configuration layer.
+
+    Centralise path discovery so the composition root stays platform-agnostic
+    and easy to test.
+
+    Architecture:
+        Uses the Strategy pattern to delegate platform-specific logic to dedicated
+        classes (``LinuxStrategy``, ``MacOSStrategy``, ``WindowsStrategy``),
+        keeping the main resolver focused on orchestration.
+    """
+
+    def __init__(
+        self,
+        *,
+        vendor: str,
+        app: str,
+        slug: str,
+        profile: str | None = None,
+        cwd: Path | None = None,
+        env: dict[str, str] | None = None,
+        platform: str | None = None,
+        hostname: str | None = None,
+    ) -> None:
+        """Store context required to resolve filesystem locations.
+
+        Args:
+            vendor / app / slug: Naming context injected into platform-specific directory structures.
+            profile: Optional profile name for environment-specific configurations
+                (e.g., "test", "production"). When set, paths include a
+                ``profile/<name>/`` subdirectory.
+            cwd: Working directory to use when searching for ``.env`` files.
+            env: Optional environment mapping that overrides ``os.environ`` values
+                (useful for deterministic tests).
+            platform: Platform identifier (``sys.platform`` clone). Defaults to the
+                current interpreter platform.
+            hostname: Hostname used for host-specific configuration lookups.
+
+        Raises:
+            ValueError: When vendor, app, slug, profile, or hostname contain invalid path characters.
+        """
+        self.vendor = validate_vendor_app(vendor, "vendor")
+        self.application = validate_vendor_app(app, "app")
+        self.slug = validate_identifier(slug, "slug")
+        self.profile = validate_profile(profile)
+        self.cwd = cwd or Path.cwd()
+        self.env = {**os.environ, **(env or {})}
+        self.platform = platform or sys.platform
+        self.hostname = validate_hostname(hostname or socket.gethostname())
+
+        # Build the platform context and select the appropriate strategy
+        self._ctx = PlatformContext(
+            vendor=self.vendor,
+            app=self.application,
+            slug=self.slug,
+            cwd=self.cwd,
+            env=self.env,
+            hostname=self.hostname,
+            profile=self.profile,
+        )
+        self._strategy = self._select_strategy()
+        self._dotenv_finder = DotenvPathFinder(self.cwd, self._strategy)
+
+    @property
+    def strategy(self) -> PlatformStrategy | None:
+        """Return the current platform strategy for direct access in tests."""
+        return self._strategy
+
+    @property
+    def context(self) -> PlatformContext:
+        """Return the platform context for direct access in tests."""
+        return self._ctx
+
+    def _select_strategy(self) -> PlatformStrategy | None:
+        """Select the appropriate platform strategy based on the current platform."""
+        if self.platform.startswith("linux"):
+            return LinuxStrategy(self._ctx)
+        if self.platform == "darwin":
+            return MacOSStrategy(self._ctx)
+        if self.platform.startswith("win"):
+            return WindowsStrategy(self._ctx)
+        return None
+
+    def app(self) -> Iterable[str]:
+        """Return candidate system-wide configuration paths.
+
+        Provide the lowest-precedence defaults shared across machines.
+
+        Returns:
+            Ordered path strings for the application defaults layer.
+
+        Examples:
+            >>> import os
+            >>> from pathlib import Path
+            >>> from tempfile import TemporaryDirectory
+            >>> tmp = TemporaryDirectory()
+            >>> root = Path(tmp.name)
+            >>> (root / 'demo').mkdir(parents=True, exist_ok=True)
+            >>> body = os.linesep.join(['[settings]', 'value=1'])
+            >>> _ = (root / 'demo' / 'config.toml').write_text(body, encoding='utf-8')
+            >>> resolver = DefaultPathResolver(vendor='Acme', app='Demo', slug='demo', env={'LIB_LAYERED_CONFIG_ETC': str(root)}, platform='linux')
+            >>> [Path(p).name for p in resolver.app()]
+            ['config.toml']
+            >>> tmp.cleanup()
+        """
+        return self._iter_layer("app")
+
+    def host(self) -> Iterable[str]:
+        """Return host-specific overrides.
+
+        Allow operators to tailor configuration to individual hosts (e.g.
+        ``demo-host.toml``).
+
+        Returns:
+            Ordered host-level configuration paths.
+        """
+        return self._iter_layer("host")
+
+    def user(self) -> Iterable[str]:
+        """Return user-level configuration locations.
+
+        Capture per-user preferences stored in XDG/macOS/Windows user config
+        directories.
+
+        Returns:
+            Ordered user-level configuration paths.
+        """
+        return self._iter_layer("user")
+
+    def dotenv(self) -> Iterable[str]:
+        """Return candidate ``.env`` locations discovered during path resolution.
+
+        `.env` files often live near the project root; this helper provides the
+        ordered search list for the dotenv adapter.
+
+        Returns:
+            Ordered `.env` path strings.
+        """
+        return list(self._dotenv_finder.find_paths())
+
+    def _iter_layer(self, layer: str) -> list[str]:
+        """Dispatch to the strategy for *layer* with logging."""
+        if self._strategy is None:
+            return []
+
+        method_map = {
+            "app": self._strategy.app_paths,
+            "host": self._strategy.host_paths,
+            "user": self._strategy.user_paths,
+        }
+        method = method_map.get(layer)
+        if method is None:
+            return []
+
+        paths = list(method())
+        if paths:
+            log_debug("path_candidates", layer=layer, path=None, count=len(paths))
+        return paths

lib_layered_config/application/__init__.py

@@ -0,0 +1,12 @@
+"""Application layer orchestrators (ports + merge policy).
+
+Purpose
+-------
+Define pure coordination code that glues domain value objects to adapter
+interfaces.
+
+Contents
+--------
+* :mod:`lib_layered_config.application.ports`
+* :mod:`lib_layered_config.application.merge`
+"""