apppy-env 0.1.0__tar.gz

apppy_env-0.1.0/.gitignore

@@ -0,0 +1,2 @@
+# Allow a dummy .secrets dir for testing purposes
+!src/apppy/env/.secrets

apppy_env-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: apppy-env
+Version: 0.1.0
+Summary: Python environment configuration helpers for server development
+Project-URL: Homepage, https://github.com/spals/apppy
+Author: Tim Kral
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.11
+Requires-Dist: pydantic-settings==2.10.1
+Requires-Dist: pydantic==2.11.7

apppy_env-0.1.0/env.mk

@@ -0,0 +1,23 @@
+ifndef APPPY_ENV_MK_INCLUDED
+APPPY_ENV_MK_INCLUDED := 1
+ENV_PKG_DIR := $(dir $(abspath $(lastword $(MAKEFILE_LIST))))
+
+.PHONY: env env-dev env/build env/clean env/install env/install-dev
+
+env: env/clean env/install
+
+env-dev: env/clean env/install-dev
+
+env/build:
+	cd $(ENV_PKG_DIR) && uvx --from build pyproject-build
+
+env/clean:
+	cd $(ENV_PKG_DIR) && rm -rf dist/ *.egg-info .venv
+
+env/install: env/build
+	cd $(ENV_PKG_DIR) && uv pip install dist/*.whl
+
+env/install-dev:
+	cd $(ENV_PKG_DIR) && uv pip install -e .
+
+endif # APPPY_ENV_MK_INCLUDED

apppy_env-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "apppy-env"
+version = "0.1.0"
+description = "Python environment configuration helpers for server development"
+readme = "README.md"
+requires-python = ">=3.11"
+license = {text = "MIT"}
+authors = [{ name = "Tim Kral" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+]
+dependencies = [
+    "pydantic==2.11.7",
+    "pydantic-settings==2.10.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/spals/apppy"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/apppy"]

apppy_env-0.1.0/src/apppy/env/.secrets/dummy/APP_TEST_SECRET

@@ -0,0 +1 @@
+my-secret-value

apppy_env-0.1.0/src/apppy/env/__init__.py

@@ -0,0 +1,359 @@
+import abc
+import inspect
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+from pydantic.fields import FieldInfo
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+)
+from pydantic_settings.sources import PydanticBaseEnvSettingsSource
+
+
+class DictSettingsSource(PydanticBaseEnvSettingsSource):
+    _logger = logging.getLogger("apppy.env.DictSettingsSource")
+
+    def __init__(
+        self,
+        settings_cls: type[BaseSettings],
+        d: dict | None,
+    ) -> None:
+        super().__init__(settings_cls)
+        self._dict: dict | None = d
+
+    def get_field_value(self, field: FieldInfo, field_name: str) -> tuple[Any, str, bool]:
+        # See implementation in EnvSettingsSource
+        dict_val: str | None = None
+        for field_key, env_name, value_is_complex in self._extract_field_info(field, field_name):  # noqa: B007
+            # In some cases (e.g. Env object with no overrides)
+            # the central dictionary will be None so we'll just
+            # return with the field information
+            if self._dict is None:
+                # Because we break here, we're technically
+                # returning the first field information
+                break
+
+            dict_val = self._dict.get(env_name)
+            if dict_val is not None:
+                break
+            # Attempt a lookup by the field key so that we
+            # accept that as well (i.e. the Robustness Principle)
+            dict_val = self._dict.get(field_key)
+            if dict_val is not None:
+                break
+
+        return dict_val, field_key, value_is_complex
+
+
+##### ##### ##### Environment ##### ##### #####
+# An environment represents the external space
+# in which an application is executing.
+
+
+class Env(abc.ABC):
+    _logger = logging.getLogger("apppy.env.Env")
+
+    def __init__(self, prefix: str, name: str, overrides: dict | None = None) -> None:
+        self.prefix: str = prefix
+        self.name: str = name
+        self.overrides: dict | None = overrides
+
+    @abc.abstractmethod
+    def exists(self) -> bool:
+        return False
+
+    @property
+    def is_ci(self) -> bool:
+        return self.name.startswith("ci") or self.name.endswith("ci")
+
+    @property
+    def is_production(self) -> bool:
+        return self.name == "prod" or self.name == "production"
+
+    @property
+    def is_test(self) -> bool:
+        return self.name.startswith("test") or self.name.endswith("test")
+
+    @property
+    @abc.abstractmethod
+    def settings_config(self) -> SettingsConfigDict:
+        pass
+
+    @abc.abstractmethod
+    def settings_sources(
+        self,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        pass
+
+    @staticmethod
+    def load(prefix: str = "APP", name: str | None = None, overrides: dict | None = None) -> "Env":
+        env_prefix = prefix
+
+        # Find the environment name
+        # Prefer an explicitly provided name over an environment variable name
+        if name:
+            env_name = name
+        elif "{env_prefix}_ENV" in os.environ:
+            env_name = os.environ[f"{env_prefix}_ENV"]
+        else:
+            logging.fatal("!!! No environment name provided !!!")
+            os._exit(1)
+
+        file_env = FileEnv(prefix=env_prefix, name=env_name, overrides=overrides)
+        if file_env.exists():
+            return file_env
+
+        vars_env = VarsEnv(prefix=env_prefix, name=env_name, overrides=overrides)
+        if vars_env.exists():
+            return vars_env
+
+        logging.fatal(f"!!! {env_name} environment not found !!!")
+        os._exit(1)
+
+    @staticmethod
+    def find_secrets_dir(env: "Env") -> Path | None:
+        """
+        Search upward from the *caller*'s file for either:
+          - CI/TEST:   <ancestor>/.github/ci/secrets
+          - otherwise: <ancestor>/.secrets/<env.name>
+
+        Returns the resolved Path if found, else None.
+        """
+        if env.is_production:
+            # Never use file-based secrets in production(-like) envs.
+            return None
+
+        # Start from the callsite's directory; fall back to CWD if inspection fails.
+        try:
+            call_stack = inspect.stack()
+            call_file = next(
+                Path(frame.filename).resolve()
+                for frame in call_stack
+                # Skip to the first frame outside of the package
+                if (
+                    frame.filename.find("/apppy/app/") == -1
+                    and frame.filename.find("/apppy/env/") == -1
+                )
+                or
+                # or, as a special case, allow the package to run tests
+                (frame.filename.find("/apppy/env") > -1 and frame.filename.endswith("_test.py"))
+            )
+            start_dir = call_file.parent
+        except Exception:
+            start_dir = Path.cwd()
+
+        # Walk upward: start_dir, then its parents up to filesystem root.
+        search_roots = [start_dir, *start_dir.parents]
+
+        # CI/TEST: prefer .github/ci/secrets anywhere up the tree (usually repo root)
+        if env.is_ci or env.is_test:
+            for base in search_roots:
+                ci_dir = (base / ".github" / "ci" / "secrets").resolve()
+                if ci_dir.is_dir():
+                    logging.info(
+                        "A CI/Test secrets directory was found at %s; it will be INCLUDED "
+                        "in settings configuration.",
+                        ci_dir,
+                    )
+                    return ci_dir
+
+        # Non-CI: look for application-local .secrets/<env.name> up the tree
+        for base in search_roots:
+            candidate = (base / ".secrets" / env.name).resolve()
+            if candidate.is_dir():
+                logging.info(
+                    "A secrets directory exists for environment '%s' at %s; it will be "
+                    "INCLUDED in settings configuration.",
+                    env.name,
+                    candidate,
+                )
+                return candidate
+
+        logging.info(
+            f"No secrets directory exists for environment '{env.name}'. It will be SKIPPED in settings configuration."  # noqa: E501
+        )
+        return None
+
+
+class DictEnv(Env):
+    _logger = logging.getLogger("apppy.env.DictEnv")
+
+    def __init__(self, name: str, d: dict) -> None:
+        super().__init__(prefix="", name=name, overrides=None)
+        self._dict: dict = d
+        # Ensure that the env name is available under
+        # the env key (FileEnv and VarsEnv naturally have this construct)
+        self._dict["env"] = name
+
+    def __hash__(self):
+        # Define a hash function here in order
+        # to cache the same envs used in testing
+        return hash(frozenset(self._dict.items()))
+
+    def exists(self) -> bool:
+        return True
+
+    @property
+    def settings_config(self) -> SettingsConfigDict:
+        return SettingsConfigDict(
+            env_prefix=self.prefix,
+            # A DictEnv is only used in narrow testing flows in which
+            # secrets should not be necessary so we will force that
+            # to be None
+            secrets_dir=None,
+        )
+
+    def settings_sources(
+        self,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        return (
+            init_settings,
+            DictSettingsSource(settings_cls, self._dict),
+            file_secret_settings,
+        )
+
+
+class FileEnv(Env):
+    _logger = logging.getLogger("apppy.env.FileEnv")
+
+    def __init__(self, prefix: str, name: str, overrides: dict | None = None) -> None:
+        super().__init__(prefix=prefix, name=name, overrides=overrides)
+        self._secrets_dir = Env.find_secrets_dir(self)
+        self.env_file: Path = (
+            Path(".github/ci/.env.ci") if self.is_ci or self.is_test else Path(f".env.{self.name}")
+        )
+
+    def exists(self) -> bool:
+        return self.env_file.exists()
+
+    @property
+    def settings_config(self) -> SettingsConfigDict:
+        return SettingsConfigDict(
+            env_file=self.env_file,
+            env_prefix=self.prefix,
+            secrets_dir=self._secrets_dir,
+        )
+
+    def settings_sources(
+        self,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        return (
+            # Put overrides here so they take precedence over
+            # all other settings
+            DictSettingsSource(settings_cls, self.overrides),
+            init_settings,
+            env_settings,
+            dotenv_settings,
+            file_secret_settings,
+        )
+
+
+class VarsEnv(Env):
+    _logger = logging.getLogger("apppy.env.VarsEnv")
+
+    def __init__(self, prefix: str, name: str, overrides: dict | None = None) -> None:
+        super().__init__(prefix=prefix, name=name, overrides=overrides)
+        self._secrets_dir = Env.find_secrets_dir(self)
+
+    def exists(self) -> bool:
+        return f"{self.prefix}_ENV" in os.environ and os.environ[f"{self.prefix}_ENV"] == self.name
+
+    @property
+    def settings_config(self) -> SettingsConfigDict:
+        return SettingsConfigDict(
+            env_prefix=self.prefix,
+            secrets_dir=self._secrets_dir,
+        )
+
+    def settings_sources(
+        self,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        return (
+            # Put overrides here so they take precedence over
+            # all other settings
+            DictSettingsSource(settings_cls, self.overrides),
+            init_settings,
+            env_settings,
+            file_secret_settings,
+        )
+
+
+##### ##### ##### Environment Settings ##### ##### #####
+
+
+class EnvSettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        extra="ignore",
+    )
+
+    def __init__(self, env: Env) -> None:
+        super().__init__(
+            _case_sensitive=env.settings_config.get("case_sensitive"),
+            _nested_model_default_partial_update=env.settings_config.get(
+                "nested_model_default_partial_update"
+            ),
+            _env_prefix=env.settings_config.get("env_prefix"),
+            _env_file=env.settings_config.get("env_file"),
+            _env_file_encoding=env.settings_config.get("env_file_encoding"),
+            _env_ignore_empty=env.settings_config.get("env_ignore_empty"),
+            _env_nested_delimiter=env.settings_config.get("env_nested_delimiter"),
+            _env_parse_none_str=env.settings_config.get("env_parse_none_str"),
+            _env_parse_enums=env.settings_config.get("env_parse_enums"),
+            # _cli_prog_name: str | None = None,
+            # _cli_parse_args: bool | list[str] | tuple[str, ...] | None = None,
+            # _cli_settings_source: CliSettingsSource[Any] | None = None,
+            # _cli_parse_none_str: str | None = None,
+            # _cli_hide_none_type: bool | None = None,
+            # _cli_avoid_json: bool | None = None,
+            # _cli_enforce_required: bool | None = None,
+            # _cli_use_class_docs_for_groups: bool | None = None,
+            # _cli_exit_on_error: bool | None = None,
+            # _cli_prefix: str | None = None,
+            # _cli_flag_prefix_char: str | None = None,
+            # _cli_implicit_flags: bool | None = None,
+            # _cli_ignore_unknown_args: bool | None = None,
+            _secrets_dir=env.settings_config.get("secrets_dir"),
+            values=env,
+        )
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        env = init_settings.init_kwargs["values"]  # type: ignore
+        return env.settings_sources(
+            settings_cls,
+            init_settings,
+            env_settings,
+            dotenv_settings,
+            file_secret_settings,
+        )

apppy_env-0.1.0/src/apppy/env/env_fixtures.py

@@ -0,0 +1,64 @@
+import datetime
+import os
+import pathlib
+
+import pytest
+
+from . import Env
+
+
+@pytest.fixture(scope="session")
+def env_ci():
+    ci_env: Env = Env.load(name="ci")
+    yield ci_env
+
+
+@pytest.fixture(scope="session")
+def env_local():
+    """
+    Environment fixure which reads the currently configured
+    local environment and makes this globally available to
+    all tests.
+
+    This may be helpful in the case where you would like to
+    tweak local settings and run tests against them without
+    having to push those settings into a code change.
+    """
+    test_env: Env = Env.load(name="local")
+    yield test_env
+
+
+@pytest.fixture
+def env_overrides(request):
+    """
+    Environment fixure which allows any test
+    to override the currently configured environment.
+    """
+    return getattr(request, "param", {})
+
+
+@pytest.fixture
+def env_unit(monkeypatch: pytest.MonkeyPatch, env_overrides):
+    """
+    Environment fixure which allows a unit test to
+    use an Env instance.
+    """
+    monkeypatch.setenv("APP_ENV", current_test_name())
+    return Env.load(name=current_test_name(), overrides=env_overrides)
+
+
+def current_test_file() -> str:
+    # Returns the base name (without suffix) of the test file currently being executed.
+    test_path = os.environ["PYTEST_CURRENT_TEST"].split("::")[0]
+    return pathlib.Path(test_path).stem
+
+
+def current_test_name() -> str:
+    test_name = os.environ["PYTEST_CURRENT_TEST"].split(":")[-1].split(" ")[0]
+    # Test names can carry parameterize names (e.g. my_test[my_parameters])
+    # brakcets are not safe for use in some circumstances so strip those out
+    return test_name.replace("[", "_").replace("]", "_")
+
+
+def current_test_time() -> str:
+    return datetime.datetime.now().strftime("%Y%m%d%H%M%S")

apppy_env-0.1.0/src/apppy/env/env_unit_test.py

@@ -0,0 +1,35 @@
+import pytest
+
+from apppy.env import Env
+
+
+def test_find_secrets_dir_for_ci():
+    env = Env.load(name="ci")
+    secrets_dir = Env.find_secrets_dir(env)
+
+    assert secrets_dir.exists() is True
+    assert str(secrets_dir).endswith(
+        ".github/ci/secrets"
+    ), f"Unexpected secrets dir for ci: {secrets_dir}"
+
+
+def test_find_secrets_dir_for_test():
+    env = Env.load(name="test_find_secrets_dir_for_test")
+    secrets_dir = Env.find_secrets_dir(env)
+
+    assert secrets_dir.exists() is True
+    assert str(secrets_dir).endswith(
+        ".github/ci/secrets"
+    ), f"Unexpected secrets dir for test: {secrets_dir}"
+
+
+def test_find_secrets_dir(monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.setenv("APP_ENV", "dummy")
+
+    env = Env.load(name="dummy")
+    secrets_dir = Env.find_secrets_dir(env)
+
+    assert secrets_dir.exists() is True
+    assert str(secrets_dir).endswith(
+        "src/apppy/env/.secrets/dummy"
+    ), f"Unexpected secrets dir found: {secrets_dir}"