apprc 0.1.0__py3-none-any.whl

apprc/__init__.py

@@ -0,0 +1,19 @@
+"""Reusable application runtime configuration and logging helpers."""
+
+# ruff: noqa: F401
+
+from apprc.config import (
+    AppConfigKit,
+    AppConfigSpec,
+    BaseConfig,
+    BaseEnv,
+    ConfigField,
+    ConfigOwner,
+    EnvBootstrapSpec,
+)
+from apprc.logging import (
+    AppLogger,
+    LoggingConfig,
+    get_logger,
+    setup_logging,
+)

apprc/_dotenv_guard.py

@@ -0,0 +1,29 @@
+"""Stdlib-only helpers for guarding dotenv autoload side effects."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+
+@contextmanager
+def _disable_dotenv_autoload() -> Iterator[None]:
+    """Temporarily disable libraries that auto-load ``.env`` files.
+
+    Some libraries import ``python-dotenv`` through their dependency graph.
+    Setting ``PYTHON_DOTENV_DISABLED`` around those imports preserves the
+    application's explicit environment loading policy while restoring the
+    user's original process environment afterward.
+
+    :return: Context manager that restores ``PYTHON_DOTENV_DISABLED``.
+    """
+    prev = os.environ.get("PYTHON_DOTENV_DISABLED")
+    os.environ["PYTHON_DOTENV_DISABLED"] = "1"
+    try:
+        yield
+    finally:
+        if prev is None:
+            os.environ.pop("PYTHON_DOTENV_DISABLED", None)
+        else:
+            os.environ["PYTHON_DOTENV_DISABLED"] = prev

apprc/_lazy.py

@@ -0,0 +1,62 @@
+"""Small helpers for PEP 562 package facades. This speeds up import time a lot
+
+Once Python 3.15 hits, replace all this logic with `lazy import`
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Callable, Mapping, Sequence
+from importlib import import_module
+
+
+type LazyGetattr = Callable[[str], object]
+type LazyDir = Callable[[], list[str]]
+
+
+def build_lazy_facade(
+    *,
+    public_module: str,
+    all_exports: Sequence[str],
+    module_exports: Mapping[str, str],
+    symbol_exports: Mapping[str, str],
+) -> tuple[list[str], LazyGetattr, LazyDir]:
+    """Build module-level hooks for one lazy public facade.
+
+    The returned ``__getattr__`` resolves modules and symbols only when a caller
+    first touches them. Resolved values are stored on the public module, not on
+    the private ``_facade`` module, so repeated access is the same cheap global
+    lookup that an eager facade would provide.
+
+    :param public_module: Public module name that owns the lazy attributes.
+    :param all_exports: Stable ``__all__`` values for the facade.
+    :param module_exports: Exported submodule names to import paths.
+    :param symbol_exports: Exported symbol names to the module that defines them.
+    :return: ``(__all__, __getattr__, __dir__)`` for re-export by ``__init__``.
+    """
+    all_names = list(all_exports)
+    module_map = dict(module_exports)
+    symbol_map = dict(symbol_exports)
+    known_names = frozenset((*module_map, *symbol_map))
+
+    def __getattr__(name: str) -> object:
+        namespace = sys.modules[public_module].__dict__
+        if name in module_map:
+            value = import_module(module_map[name])
+        else:
+            try:
+                module_name = symbol_map[name]
+            except KeyError as exc:
+                raise AttributeError(
+                    f"module {public_module!r} has no attribute {name!r}"
+                ) from exc
+            module = import_module(module_name)
+            value = getattr(module, name)
+        namespace[name] = value
+        return value
+
+    def __dir__() -> list[str]:
+        namespace = sys.modules[public_module].__dict__
+        return sorted(set(namespace) | known_names | set(all_names))
+
+    return all_names, __getattr__, __dir__

apprc/cli/__init__.py

@@ -0,0 +1,31 @@
+"""Reusable CLI helpers for application config commands."""
+
+# ruff: noqa: F401
+
+from apprc.cli.bootstrap import bootstrap_cli_env, parse_log_level
+from apprc.cli.config_app import (
+    ConfigCliState,
+    active_storage_root_from_state,
+    build_config_typer_app,
+    config_request_skips_bootstrap,
+    initial_storage_from_state,
+)
+from apprc.cli.doctor import (
+    build_config_doctor_payload,
+    config_command_text,
+    config_setup_message,
+    print_config_doctor,
+)
+from apprc.cli.options import (
+    COMMON_ROOT_FLAG_OPTIONS,
+    COMMON_ROOT_VALUE_OPTIONS,
+)
+from apprc.cli.typer_utils import (
+    MISSING_ACTION_MESSAGE,
+    args_after_command,
+    dump_json,
+    exit_missing_action,
+    run_typer_app,
+    state_from,
+    strip_leading_options,
+)

apprc/cli/bootstrap.py

@@ -0,0 +1,66 @@
+"""Root CLI bootstrap helpers."""
+
+from __future__ import annotations
+
+# == Standard Library ========================
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+# == 3rd Party ===============================
+import typer
+
+# == Internal ================================
+from apprc.config.environment import BootstrapLogger, EnvBootstrapResult
+from apprc.config.kit import AppConfigKit
+
+
+def parse_log_level(log_level: str) -> str | int:
+    """Convert a CLI log-level token into the logging backend value.
+
+    :param log_level: User-provided Typer option value.
+    :return: Integer level for decimal strings, otherwise the original token.
+    """
+    return int(log_level) if log_level.isdecimal() else log_level
+
+
+def bootstrap_cli_env(
+    kit: AppConfigKit,
+    *,
+    env_file: Path | None,
+    env_file_overrides_shell: bool,
+    no_dotenv: bool,
+    storage_name: str | None,
+    log_level: str | None = None,
+    setup_logging: Callable[..., Any] | None = None,
+    logger: BootstrapLogger | None = None,
+) -> EnvBootstrapResult:
+    """Initialize logging and dotenv layers for one CLI process.
+
+    :param kit: Application config facade.
+    :param env_file: Optional explicit dotenv file.
+    :param env_file_overrides_shell: Whether explicit dotenv values beat
+        already exported variables inside this process.
+    :param no_dotenv: Disable dotenv layer loading.
+    :param storage_name: Optional named storage selector.
+    :param log_level: Optional CLI log-level token.
+    :param setup_logging: Optional application logging setup callable.
+    :param logger: Optional application logger for bootstrap status messages.
+    :return: Bootstrap summary for diagnostics and tests.
+    :raises typer.BadParameter: If the explicit env file or storage selector
+        is invalid.
+    """
+    if setup_logging is not None and log_level is not None:
+        setup_logging(level=parse_log_level(log_level))
+    try:
+        return kit.bootstrap(
+            env_file=env_file,
+            env_file_overrides_shell=env_file_overrides_shell,
+            no_dotenv=no_dotenv,
+            storage_name=storage_name,
+            logger=logger,
+        )
+    except FileNotFoundError as exc:
+        raise typer.BadParameter(str(exc), param_hint="--env-file") from exc
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc), param_hint="--storage") from exc