envbase 1.0.0__py3-none-any.whl

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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,5 @@
+envbase/__init__.py,sha256=JsOf5uZ1INiA563jmmek5CHNjWycHvz1DGqzD3ZwVN4,155
+envbase/env_base.py,sha256=B6vPwVJEzNPyCSXVguT9qiEFMUVTjf8772wA_F24X38,2666
+envbase-1.0.0.dist-info/METADATA,sha256=8gGXRUoAGL0pAqftoWXfkrYnlpWLWsqGSjWthT_r3B8,4091
+envbase-1.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+envbase-1.0.0.dist-info/RECORD,,

envbase-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any