apprc-core 0.25.0__py3-none-any.whl

apprc/__init__.py

@@ -0,0 +1,21 @@
+"""Clean public facade for AppRC."""
+
+# ruff: noqa: F401
+
+# > Explicit aliases mark public imports for downstream type checkers.
+from apprc.public.app_rc import AppRC as AppRC
+from apprc.definition.resolution import ResolveOptions as ResolveOptions
+from apprc.runtime.resolution import ResolvedConfig as ResolvedConfig
+from apprc.public.config import Config as Config, ConfigBase as ConfigBase
+from apprc.public.field import field as field
+from apprc.definition.app_config.storage import Storage as Storage
+from apprc.definition.app_config.user_dotenv import UserDotenv as UserDotenv
+
+from . import cli
+from . import tui
+from . import files
+from . import provenance
+from . import schema
+from . import storage
+
+from ._exports import PUBLIC_NAMES as __all__

apprc/__main__.py

@@ -0,0 +1,7 @@
+"""Run AppRC's command-line application with ``python -m apprc``."""
+
+from apprc._cli_app import main
+
+
+if __name__ == "__main__":
+    main()

apprc/_cli_app.py

@@ -0,0 +1,116 @@
+"""Command-line entrypoint for AppRC development helpers."""
+
+# == Standard Library ========================
+from pathlib import Path
+from typing import Annotated
+
+# == 3rd Party ===============================
+import typer
+
+# == Internal ================================
+from apprc.scaffold import (
+    ConfigScaffoldRequest,
+    scaffold_config_package,
+)
+
+app = typer.Typer(
+    help="Developer tools for AppRC-enabled applications.",
+    no_args_is_help=True,
+    pretty_exceptions_show_locals=False,
+)
+scaffold_app = typer.Typer(
+    help="Generate AppRC integration files.",
+    no_args_is_help=True,
+)
+app.add_typer(scaffold_app, name="scaffold")
+
+
+@scaffold_app.command("config")
+def scaffold_config_cmd(
+    package: Annotated[
+        str,
+        typer.Option(
+            "--package",
+            help="Import package that receives config/, for example myapp.",
+        ),
+    ],
+    app_id: Annotated[
+        str,
+        typer.Option("--app-id", help="Stable AppRC application identity."),
+    ],
+    user_dotenv: Annotated[
+        bool,
+        typer.Option(
+            "--user-dotenv",
+            help="Generate a declaration with a managed user dotenv.",
+        ),
+    ] = False,
+    storage: Annotated[
+        bool,
+        typer.Option(
+            "--storage",
+            help="Generate an app declaration with AppRC storage.",
+        ),
+    ] = False,
+    display_name: Annotated[
+        str | None,
+        typer.Option(
+            "--display-name",
+            help="Human-readable application name.",
+        ),
+    ] = None,
+    storage_selector_env_key: Annotated[
+        str | None,
+        typer.Option(
+            "--storage-selector-env-key",
+            help="Optional storage selector env key override.",
+        ),
+    ] = None,
+    env_prefix: Annotated[
+        str | None,
+        typer.Option(
+            "--env-prefix",
+            help="Full env prefix for the generated AppSection.",
+        ),
+    ] = None,
+    target: Annotated[
+        Path,
+        typer.Option(
+            "--target",
+            help="Source root that contains the package.",
+        ),
+    ] = Path("src"),
+    force: Annotated[
+        bool,
+        typer.Option(
+            "--force",
+            help="Replace existing generated config files.",
+        ),
+    ] = False,
+) -> None:
+    """Generate AppRC's standard ``X.config`` package layout."""
+    try:
+        result = scaffold_config_package(
+            ConfigScaffoldRequest(
+                package=package,
+                app_id=app_id,
+                display_name=display_name,
+                target=target,
+                user_dotenv=user_dotenv,
+                storage=storage,
+                storage_selector_env_key=storage_selector_env_key,
+                env_prefix=env_prefix,
+                force=force,
+            )
+        )
+    except (FileExistsError, ValueError) as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+    typer.echo(f"Created AppRC config package: {result.config_package_dir}")
+    for path in result.written_files:
+        typer.echo(f"- {path}")
+
+
+def main() -> None:
+    """Run the AppRC command-line application."""
+    app()

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/_exports.py

@@ -0,0 +1,18 @@
+"""Supported names exported by the public facade."""
+
+PUBLIC_NAMES = [
+    "AppRC",
+    "ResolveOptions",
+    "ResolvedConfig",
+    "Storage",
+    "UserDotenv",
+    "Config",
+    "ConfigBase",
+    "field",
+    "cli",
+    "tui",
+    "files",
+    "provenance",
+    "schema",
+    "storage",
+]

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,7 @@
+"""Advanced AppRC CLI integration namespace."""
+
+# ruff: noqa: F401
+
+from apprc.cli._facade import __all__ as __all__
+from apprc.cli._facade import __dir__ as __dir__
+from apprc.cli._facade import __getattr__ as __getattr__

apprc/cli/__init__.pyi

@@ -0,0 +1,65 @@
+"""Typed surface for the lazy AppRC CLI integration namespace."""
+
+# ruff: noqa: F401
+
+from apprc.interfaces.cli import (
+    COMMON_CLI_FLAG_OPTIONS as COMMON_CLI_FLAG_OPTIONS,
+    COMMON_CLI_VALUE_OPTIONS as COMMON_CLI_VALUE_OPTIONS,
+    DEFAULT_CONFIG_RUNTIME_INDEPENDENT_ACTIONS as DEFAULT_CONFIG_RUNTIME_INDEPENDENT_ACTIONS,
+    MISSING_ACTION_MESSAGE as MISSING_ACTION_MESSAGE,
+    RuntimeIndependentCommand as RuntimeIndependentCommand,
+    CliArgvProvider as CliArgvProvider,
+    CliRuntime as CliRuntime,
+    CliRuntimeContext as CliRuntimeContext,
+    CliRuntimeOptions as CliRuntimeOptions,
+    CliRuntimeOptionsProtocol as CliRuntimeOptionsProtocol,
+    CliRuntimePolicy as CliRuntimePolicy,
+    CliRuntimeSession as CliRuntimeSession,
+    CliRuntimeStateFactory as CliRuntimeStateFactory,
+    ConfigCliState as ConfigCliState,
+    ConfigRuntimePolicy as ConfigRuntimePolicy,
+    ConfigSelectorContext as ConfigSelectorContext,
+    DefaultConfigCliState as DefaultConfigCliState,
+    EnvFileOverridesOption as EnvFileOverridesOption,
+    EnvFilesOption as EnvFilesOption,
+    LogLevelOption as LogLevelOption,
+    MountCliRuntimeStateFactory as MountCliRuntimeStateFactory,
+    SkipDotenvLayersOption as SkipDotenvLayersOption,
+    StorageOption as StorageOption,
+    active_storage_root_from_state as active_storage_root_from_state,
+    args_after_command as args_after_command,
+    resolve_cli_config as resolve_cli_config,
+    resolve_cli_options as resolve_cli_options,
+    build_config_doctor_payload as build_config_doctor_payload,
+    build_config_typer_app as build_config_typer_app,
+    cli_options_from as cli_options_from,
+    cli_runtime_context_from as cli_runtime_context_from,
+    cli_runtime_options_to_args as cli_runtime_options_to_args,
+    config_command_text as config_command_text,
+    config_request_skips_runtime as config_request_skips_runtime,
+    config_setup_message as config_setup_message,
+    dump_json as dump_json,
+    ensure_config_group_name_available as ensure_config_group_name_available,
+    exit_missing_action as exit_missing_action,
+    initial_storage_from_state as initial_storage_from_state,
+    mount_config_cli as mount_config_cli,
+    parse_log_level as parse_log_level,
+    prepare_cli_runtime_context as prepare_cli_runtime_context,
+    print_config_doctor as print_config_doctor,
+    print_config_paths as print_config_paths,
+    run_typer_app as run_typer_app,
+    state_from as state_from,
+    strip_leading_options as strip_leading_options,
+)
+from apprc.interfaces.cli.diagnostics import (
+    ConfigDoctorPayload as ConfigDoctorPayload,
+    ConfigDoctorStatus as ConfigDoctorStatus,
+)
+from apprc.runtime.logging import (
+    ResolutionLogger as ResolutionLogger,
+)
+
+__all__: list[str]
+
+def __getattr__(name: str) -> object: ...
+def __dir__() -> list[str]: ...

apprc/cli/_facade.py

@@ -0,0 +1,81 @@
+"""Lazy facade for advanced AppRC CLI integration APIs."""
+
+from __future__ import annotations
+
+from apprc._lazy import build_lazy_facade
+
+_CLI_EXPORTS = [
+    "COMMON_CLI_FLAG_OPTIONS",
+    "COMMON_CLI_VALUE_OPTIONS",
+    "DEFAULT_CONFIG_RUNTIME_INDEPENDENT_ACTIONS",
+    "MISSING_ACTION_MESSAGE",
+    "RuntimeIndependentCommand",
+    "CliArgvProvider",
+    "CliRuntime",
+    "CliRuntimeContext",
+    "CliRuntimeOptions",
+    "CliRuntimeOptionsProtocol",
+    "CliRuntimePolicy",
+    "CliRuntimeSession",
+    "CliRuntimeStateFactory",
+    "ConfigCliState",
+    "ConfigRuntimePolicy",
+    "ConfigSelectorContext",
+    "DefaultConfigCliState",
+    "EnvFileOverridesOption",
+    "EnvFilesOption",
+    "LogLevelOption",
+    "MountCliRuntimeStateFactory",
+    "SkipDotenvLayersOption",
+    "StorageOption",
+    "active_storage_root_from_state",
+    "args_after_command",
+    "resolve_cli_config",
+    "resolve_cli_options",
+    "build_config_doctor_payload",
+    "build_config_typer_app",
+    "cli_options_from",
+    "cli_runtime_context_from",
+    "cli_runtime_options_to_args",
+    "config_command_text",
+    "config_request_skips_runtime",
+    "config_setup_message",
+    "dump_json",
+    "ensure_config_group_name_available",
+    "exit_missing_action",
+    "initial_storage_from_state",
+    "mount_config_cli",
+    "parse_log_level",
+    "prepare_cli_runtime_context",
+    "print_config_doctor",
+    "print_config_paths",
+    "run_typer_app",
+    "state_from",
+    "strip_leading_options",
+]
+_DIAGNOSTIC_EXPORTS = [
+    "ConfigDoctorPayload",
+    "ConfigDoctorStatus",
+]
+_RESULT_EXPORTS = [
+    "ResolutionLogger",
+]
+
+_SYMBOL_EXPORTS = {
+    **{name: "apprc.interfaces.cli" for name in _CLI_EXPORTS},
+    **{
+        name: "apprc.interfaces.cli.diagnostics" for name in _DIAGNOSTIC_EXPORTS
+    },
+    **{name: "apprc.runtime.logging" for name in _RESULT_EXPORTS},
+}
+
+__all__, __getattr__, __dir__ = build_lazy_facade(
+    public_module="apprc.cli",
+    all_exports=[
+        *_CLI_EXPORTS,
+        *_DIAGNOSTIC_EXPORTS,
+        *_RESULT_EXPORTS,
+    ],
+    module_exports={},
+    symbol_exports=_SYMBOL_EXPORTS,
+)

apprc/definition/__init__.py

@@ -0,0 +1 @@
+"""Internal configuration contract packages."""

apprc/definition/app_config/__init__.py

@@ -0,0 +1,7 @@
+"""Application-level configuration declarations and internal facades."""
+
+# ruff: noqa: F401
+
+from apprc.definition.app_config.spec import AppConfigSpec
+from apprc.definition.app_config.storage import Storage
+from apprc.definition.app_config.user_dotenv import UserDotenv

apprc/definition/app_config/_validation.py

@@ -0,0 +1,57 @@
+"""Validation and derivation helpers for application config specs."""
+
+from __future__ import annotations
+
+# == Standard Library ========================
+import re
+
+
+def _environment_key_prefix(app_id: str) -> str:
+    """Return the normalized environment-key prefix for an application.
+
+    :param app_id: Stable application identity.
+    :return: Uppercase identifier suitable for an environment key.
+    """
+    normalized = re.sub(r"[^A-Za-z0-9]+", "_", app_id).strip("_").upper()
+    return normalized or "APP"
+
+
+def derive_apprc_dir_env_key(app_id: str) -> str:
+    """Return the environment key that relocates the AppRC directory.
+
+    :param app_id: Stable application identity.
+    :return: Uppercase ``<APP>_APPRC_DIR`` key.
+    """
+    return f"{_environment_key_prefix(app_id)}_APPRC_DIR"
+
+
+def derive_legacy_apprc_toml_env_key(app_id: str) -> str:
+    """Return the released 0.19 AppRC TOML relocation key.
+
+    :param app_id: Legacy application identity.
+    :return: Uppercase ``<APP>_APPRC_TOML`` key.
+    """
+    return f"{_environment_key_prefix(app_id)}_APPRC_TOML"
+
+
+def derive_storage_selector_env_key(app_id: str) -> str:
+    """Return the environment variable that selects active storage.
+
+    :param app_id: Application name from the AppRC integration spec.
+    :return: Uppercase env key for the active storage selector.
+    """
+    return f"{_environment_key_prefix(app_id)}_STORAGE"
+
+
+def resolve_storage_selector_env_key(
+    *,
+    app_id: str,
+    selector_env_key: str | None,
+) -> str:
+    """Return the explicit or derived active-storage selector key.
+
+    :param app_id: Application name used for the conventional key.
+    :param selector_env_key: Optional caller-supplied key.
+    :return: Explicit key or the derived ``<APP>_STORAGE`` key.
+    """
+    return selector_env_key or derive_storage_selector_env_key(app_id)