envbase 1.0.0__tar.gz

envbase-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: pytest (python ${{ matrix.python }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+          activate-environment: true
+
+      - name: Install
+        run: uv pip install -e ".[dev]"
+
+      - name: Test
+        run: pytest --cov --cov-report=xml --cov-report=term-missing
+
+      - name: Upload coverage
+        if: matrix.python == '3.13'
+        uses: codecov/codecov-action@v5
+        with:
+          files: coverage.xml
+          token: ${{ secrets.CODECOV_TOKEN }}
+          fail_ci_if_error: false

envbase-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,58 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    uses: ./.github/workflows/ci.yml
+    secrets: inherit
+
+  build:
+    name: Build distributions
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+
+      - name: Check the tag matches the version
+        run: |
+          version=$(uv run --no-project python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          tag="${GITHUB_REF_NAME#v}"
+          if [ "$version" != "$tag" ]; then
+            echo "release tag $GITHUB_REF_NAME does not match pyproject version $version"
+            exit 1
+          fi
+
+      - name: Build
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/envbase
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

envbase-1.0.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+coverage.xml
+.coverage
+dist/

envbase-1.0.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.5
+Name: envbase
+Version: 1.0.0
+Summary: Pydantic settings with class name prefixes and per environment dotenv files
+Project-URL: Homepage, https://github.com/parkermmr/envbase
+Project-URL: Issues, https://github.com/parkermmr/envbase/issues
+Author: Parker
+Classifier: Framework :: Pydantic :: 2
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.12
+Requires-Dist: pydantic-settings>=2.4
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+[![CI Status][ci-shield]][ci-url]
+[![Coverage][coverage-shield]][coverage-url]
+[![Contributors][contributors-shield]][contributors-url]
+[![Forks][forks-shield]][forks-url]
+[![Stargazers][stars-shield]][stars-url]
+[![Issues][issues-shield]][issues-url]
+
+# Envbase
+
+Pydantic settings with class name prefixes and per environment dotenv
+files.
+
+```
+pip install envbase
+```
+
+## Usage
+
+```python
+from envbase import EnvBase
+
+class RedisConfig(EnvBase):
+    uri: str = "localhost"
+    port: int = 9010
+    ssl: bool = False
+
+config = RedisConfig()
+config.uri        # REDIS_CONFIG_URI, else resources/.env, else "localhost"
+config.dump()     # {"uri": "localhost", "port": 9010, "ssl": False}
+config.json()     # same, json safe values (secrets masked, paths as strings)
+```
+
+## Prefixes
+
+Each field reads `PREFIX_FIELD`. The prefix is the snake case class name
+unless `_prefix` is set. Matching is case insensitive.
+
+| Class                           | `uri` reads        |
+|---------------------------------|--------------------|
+| `class RedisConfig(EnvBase)`    | `REDIS_CONFIG_URI` |
+| `class HTTPServer(EnvBase)`     | `HTTP_SERVER_URI`  |
+| `_prefix = "redis"`             | `REDIS_URI`        |
+| `_prefix = ""`                  | `URI`              |
+
+Nested models read `PREFIX_FIELD__SUBFIELD`. Subclasses inherit `_prefix`.
+
+## Files
+
+Values are loaded from a dotenv file in the resources directory:
+
+| `EXECUTION_ENVIRONMENT` | File                     |
+|-------------------------|--------------------------|
+| unset                   | `./resources/.env`       |
+| `prod`                  | `./resources/.env.prod`  |
+
+A missing file is skipped. Keys in the file that belong to other classes
+are ignored, so one file can hold every class's settings.
+
+Precedence, highest first: keyword arguments, environment variables, the
+dotenv file, field defaults.
+
+## Options
+
+```python
+class RedisConfig(EnvBase):
+    uri: str = "localhost"
+
+    _prefix = "redis"               # default: snake case class name
+    _resources = "./config"         # default: ./resources (relative to cwd)
+    _variable = "STAGE"             # default: EXECUTION_ENVIRONMENT
+```
+
+`RedisConfig.prefix()` and `RedisConfig.file()` show what a class resolves
+to. Everything else is plain pydantic settings: validators, `SecretStr`,
+`model_config`, and the `_env_file` keyword all work as usual.
+
+## Tests
+
+```
+pytest --cov
+```
+
+[ci-shield]: https://img.shields.io/github/actions/workflow/status/parkermmr/envbase/ci.yml?branch=main&style=for-the-badge&label=CI
+[ci-url]: https://github.com/parkermmr/envbase/actions/workflows/ci.yml
+[coverage-shield]: https://img.shields.io/codecov/c/github/parkermmr/envbase?style=for-the-badge
+[coverage-url]: https://codecov.io/gh/parkermmr/envbase
+[contributors-shield]: https://img.shields.io/github/contributors/parkermmr/envbase.svg?style=for-the-badge
+[contributors-url]: https://github.com/parkermmr/envbase/graphs/contributors
+[forks-shield]: https://img.shields.io/github/forks/parkermmr/envbase.svg?style=for-the-badge
+[forks-url]: https://github.com/parkermmr/envbase/network/members
+[stars-shield]: https://img.shields.io/github/stars/parkermmr/envbase.svg?style=for-the-badge
+[stars-url]: https://github.com/parkermmr/envbase/stargazers
+[issues-shield]: https://img.shields.io/github/issues/parkermmr/envbase.svg?style=for-the-badge
+[issues-url]: https://github.com/parkermmr/envbase/issues

envbase-1.0.0/README.md

@@ -0,0 +1,94 @@
+[![CI Status][ci-shield]][ci-url]
+[![Coverage][coverage-shield]][coverage-url]
+[![Contributors][contributors-shield]][contributors-url]
+[![Forks][forks-shield]][forks-url]
+[![Stargazers][stars-shield]][stars-url]
+[![Issues][issues-shield]][issues-url]
+
+# Envbase
+
+Pydantic settings with class name prefixes and per environment dotenv
+files.
+
+```
+pip install envbase
+```
+
+## Usage
+
+```python
+from envbase import EnvBase
+
+class RedisConfig(EnvBase):
+    uri: str = "localhost"
+    port: int = 9010
+    ssl: bool = False
+
+config = RedisConfig()
+config.uri        # REDIS_CONFIG_URI, else resources/.env, else "localhost"
+config.dump()     # {"uri": "localhost", "port": 9010, "ssl": False}
+config.json()     # same, json safe values (secrets masked, paths as strings)
+```
+
+## Prefixes
+
+Each field reads `PREFIX_FIELD`. The prefix is the snake case class name
+unless `_prefix` is set. Matching is case insensitive.
+
+| Class                           | `uri` reads        |
+|---------------------------------|--------------------|
+| `class RedisConfig(EnvBase)`    | `REDIS_CONFIG_URI` |
+| `class HTTPServer(EnvBase)`     | `HTTP_SERVER_URI`  |
+| `_prefix = "redis"`             | `REDIS_URI`        |
+| `_prefix = ""`                  | `URI`              |
+
+Nested models read `PREFIX_FIELD__SUBFIELD`. Subclasses inherit `_prefix`.
+
+## Files
+
+Values are loaded from a dotenv file in the resources directory:
+
+| `EXECUTION_ENVIRONMENT` | File                     |
+|-------------------------|--------------------------|
+| unset                   | `./resources/.env`       |
+| `prod`                  | `./resources/.env.prod`  |
+
+A missing file is skipped. Keys in the file that belong to other classes
+are ignored, so one file can hold every class's settings.
+
+Precedence, highest first: keyword arguments, environment variables, the
+dotenv file, field defaults.
+
+## Options
+
+```python
+class RedisConfig(EnvBase):
+    uri: str = "localhost"
+
+    _prefix = "redis"               # default: snake case class name
+    _resources = "./config"         # default: ./resources (relative to cwd)
+    _variable = "STAGE"             # default: EXECUTION_ENVIRONMENT
+```
+
+`RedisConfig.prefix()` and `RedisConfig.file()` show what a class resolves
+to. Everything else is plain pydantic settings: validators, `SecretStr`,
+`model_config`, and the `_env_file` keyword all work as usual.
+
+## Tests
+
+```
+pytest --cov
+```
+
+[ci-shield]: https://img.shields.io/github/actions/workflow/status/parkermmr/envbase/ci.yml?branch=main&style=for-the-badge&label=CI
+[ci-url]: https://github.com/parkermmr/envbase/actions/workflows/ci.yml
+[coverage-shield]: https://img.shields.io/codecov/c/github/parkermmr/envbase?style=for-the-badge
+[coverage-url]: https://codecov.io/gh/parkermmr/envbase
+[contributors-shield]: https://img.shields.io/github/contributors/parkermmr/envbase.svg?style=for-the-badge
+[contributors-url]: https://github.com/parkermmr/envbase/graphs/contributors
+[forks-shield]: https://img.shields.io/github/forks/parkermmr/envbase.svg?style=for-the-badge
+[forks-url]: https://github.com/parkermmr/envbase/network/members
+[stars-shield]: https://img.shields.io/github/stars/parkermmr/envbase.svg?style=for-the-badge
+[stars-url]: https://github.com/parkermmr/envbase/stargazers
+[issues-shield]: https://img.shields.io/github/issues/parkermmr/envbase.svg?style=for-the-badge
+[issues-url]: https://github.com/parkermmr/envbase/issues

envbase-1.0.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "envbase"
+version = "1.0.0"
+description = "Pydantic settings with class name prefixes and per environment dotenv files"
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [{ name = "Parker" }]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: Pydantic :: 2",
+]
+dependencies = ["pydantic-settings>=2.4"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-cov>=5"]
+
+[project.urls]
+Homepage = "https://github.com/parkermmr/envbase"
+Issues = "https://github.com/parkermmr/envbase/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/envbase"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["envbase"]
+branch = true

envbase-1.0.0/sample/example.py

@@ -0,0 +1,25 @@
+from pydantic import SecretStr
+
+from envbase import EnvBase
+
+
+class RedisConfig(EnvBase):
+    """Reads REDIS_CONFIG_URI, REDIS_CONFIG_PORT and REDIS_CONFIG_SSL."""
+
+    uri: str = "localhost"
+    port: int = 9010
+    ssl: bool = False
+
+
+class Postgres(EnvBase):
+    """Reads PG_HOST and PG_PASSWORD."""
+
+    host: str = "localhost"
+    password: SecretStr = SecretStr("")
+
+    _prefix = "pg"
+
+
+if __name__ == "__main__":
+    print(RedisConfig.file(), RedisConfig().dump())
+    print(Postgres.file(), Postgres().json())

envbase-1.0.0/sample/resources/.env

@@ -0,0 +1,3 @@
+REDIS_CONFIG_URI=redis.local
+PG_HOST=db.local
+PG_PASSWORD=local

envbase-1.0.0/sample/resources/.env.prod

@@ -0,0 +1,4 @@
+REDIS_CONFIG_URI=redis.prod
+REDIS_CONFIG_SSL=true
+PG_HOST=db.prod
+PG_PASSWORD=prod

envbase-1.0.0/src/envbase/__init__.py

@@ -0,0 +1,8 @@
+"""
+envbase: pydantic settings with class name prefixes and per
+environment dotenv files.
+"""
+
+from envbase.env_base import EnvBase
+
+__all__ = ["EnvBase"]

envbase-1.0.0/src/envbase/env_base.py

@@ -0,0 +1,86 @@
+"""
+EnvBase is a pydantic settings model with class name prefixes and
+per environment dotenv files.
+"""
+
+from os import environ
+from pathlib import Path
+from re import sub
+from typing import Any
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+def snake(name: str) -> str:
+    """
+    Converts a class name to snake case, keeping acronyms together.
+    """
+    return sub(r"(?<=[a-z0-9])(?=[A-Z])|(?<=[A-Z])(?=[A-Z][a-z])", "_", name).lower()
+
+
+class EnvBase(BaseSettings):
+    """
+    Settings read from the environment and a dotenv file.
+
+    Each field reads the variable PREFIX_FIELD, where the prefix is the
+    snake case class name (RedisConfig.uri reads REDIS_CONFIG_URI) or
+    _prefix when set (_prefix = "redis" reads REDIS_URI). An empty
+    _prefix reads bare field names.
+
+    The dotenv file is .env in the _resources directory, or
+    .env.{name} when the variable named by _variable holds a name.
+    Keyword arguments win over the environment, the environment wins
+    over the file, and the file wins over defaults.
+    """
+
+    model_config = SettingsConfigDict(
+        extra="ignore",
+        env_nested_delimiter="__",
+    )
+
+    _prefix: str | None = None
+    _resources: str = "./resources"
+    _variable: str = "EXECUTION_ENVIRONMENT"
+
+    def __init__(self, **values: Any) -> None:
+        values.setdefault("_env_prefix", type(self).prefix())
+        values.setdefault("_env_file", type(self).file())
+        super().__init__(**values)
+
+    @classmethod
+    def option(cls, name: str) -> Any:
+        """
+        Returns the class level value of an underscore option.
+        """
+        return cls.__private_attributes__[name].default
+
+    @classmethod
+    def prefix(cls) -> str:
+        """
+        Returns the variable prefix, with its trailing underscore.
+        """
+        prefix = cls.option("_prefix")
+        if prefix is None:
+            prefix = snake(cls.__name__)
+        return f"{prefix.upper()}_" if prefix else ""
+
+    @classmethod
+    def file(cls) -> Path:
+        """
+        Returns the dotenv file for the current execution environment.
+        """
+        name = environ.get(cls.option("_variable"))
+        resources = Path(cls.option("_resources"))
+        return resources / (f".env.{name}" if name else ".env")
+
+    def dump(self, **options: Any) -> dict[str, Any]:
+        """
+        Returns the fields as a dictionary of python values.
+        """
+        return self.model_dump(**options)
+
+    def json(self, **options: Any) -> dict[str, Any]:
+        """
+        Returns the fields as a dictionary of json safe values.
+        """
+        return self.model_dump(mode="json", **options)

envbase-1.0.0/tests/test_env_base.py

@@ -0,0 +1,123 @@
+from pathlib import Path
+
+import pytest
+from pydantic import SecretStr
+
+from envbase import EnvBase
+from envbase.env_base import snake
+
+
+class RedisConfig(EnvBase):
+    uri: str = "localhost"
+    port: int = 9010
+    ssl: bool = False
+
+
+class Redis(EnvBase):
+    uri: str = "localhost"
+    port: int = 9010
+    _prefix = "redis"
+
+
+class Bare(EnvBase):
+    uri: str = "localhost"
+    _prefix = ""
+
+
+class Custom(EnvBase):
+    uri: str = "localhost"
+    password: SecretStr = SecretStr("")
+    path: Path = Path("/tmp")
+    _prefix = "custom"
+    _resources = "config"
+    _variable = "STAGE"
+
+
+@pytest.fixture(autouse=True)
+def workspace(tmp_path, monkeypatch):
+    for name in ("EXECUTION_ENVIRONMENT", "STAGE", "REDIS_URI", "REDIS_CONFIG_URI", "URI"):
+        monkeypatch.delenv(name, raising=False)
+    monkeypatch.chdir(tmp_path)
+    (tmp_path / "resources").mkdir()
+    return tmp_path
+
+
+def write(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text)
+
+
+def test_snake():
+    assert snake("RedisConfig") == "redis_config"
+    assert snake("HTTPServer") == "http_server"
+    assert snake("S3Store") == "s3_store"
+
+
+def test_defaults():
+    assert RedisConfig().dump() == {"uri": "localhost", "port": 9010, "ssl": False}
+
+
+def test_class_name_prefix(monkeypatch):
+    monkeypatch.setenv("REDIS_CONFIG_URI", "cache")
+    monkeypatch.setenv("REDIS_CONFIG_PORT", "6379")
+    monkeypatch.setenv("REDIS_CONFIG_SSL", "true")
+    assert RedisConfig().dump() == {"uri": "cache", "port": 6379, "ssl": True}
+
+
+def test_explicit_prefix(monkeypatch):
+    monkeypatch.setenv("REDIS_URI", "cache")
+    assert Redis().uri == "cache"
+    assert RedisConfig().uri == "localhost"
+
+
+def test_empty_prefix(monkeypatch):
+    monkeypatch.setenv("URI", "cache")
+    assert Bare().uri == "cache"
+
+
+def test_default_file(workspace):
+    write(workspace / "resources/.env", "REDIS_URI=fromfile\nOTHER_KEY=ignored\n")
+    assert Redis().uri == "fromfile"
+
+
+def test_environment_file(workspace, monkeypatch):
+    write(workspace / "resources/.env", "REDIS_URI=base\n")
+    write(workspace / "resources/.env.prod", "REDIS_URI=prod\n")
+    monkeypatch.setenv("EXECUTION_ENVIRONMENT", "prod")
+    assert Redis().uri == "prod"
+    assert Redis.file() == Path("resources/.env.prod")
+
+
+def test_missing_file(monkeypatch):
+    monkeypatch.setenv("EXECUTION_ENVIRONMENT", "nowhere")
+    assert Redis().uri == "localhost"
+
+
+def test_precedence(workspace, monkeypatch):
+    write(workspace / "resources/.env", "REDIS_URI=file\nREDIS_PORT=1\n")
+    monkeypatch.setenv("REDIS_URI", "environ")
+    assert Redis().dump() == {"uri": "environ", "port": 1}
+    assert Redis(uri="keyword").uri == "keyword"
+
+
+def test_custom_options(workspace, monkeypatch):
+    write(workspace / "config/.env.dev", "CUSTOM_URI=dev\n")
+    monkeypatch.setenv("STAGE", "dev")
+    assert Custom().uri == "dev"
+    assert Custom()._prefix == "custom"
+
+
+def test_subclass_inherits_options(monkeypatch):
+    class Replica(Redis):
+        replicas: int = 1
+
+    monkeypatch.setenv("REDIS_REPLICAS", "3")
+    assert Replica().replicas == 3
+
+
+def test_dump_and_json():
+    config = Custom(password="secret")
+    assert config.dump()["password"].get_secret_value() == "secret"
+    assert config.dump()["path"] == Path("/tmp")
+    assert config.json() == {"uri": "localhost", "password": "**********", "path": "/tmp"}
+    assert config.json(include={"uri"}) == {"uri": "localhost"}