configaroo 0.1.0__py3-none-any.whl

configaroo/__init__.py

@@ -0,0 +1,8 @@
+"""Bouncy configuration handling"""
+
+from configaroo.configuration import Configuration  # noqa
+from configaroo.exceptions import (  # noqa
+    ConfigarooException,
+    MissingEnvironmentVariableError,
+    UnsupportedLoaderError,
+)

configaroo/configuration.py

@@ -0,0 +1,168 @@
+"""A dict-like configuration with support for envvars, validation and type conversion"""
+
+import os
+from collections import UserDict
+from pathlib import Path
+from typing import Any, Self, Type
+
+import dotenv
+from pydantic import BaseModel
+
+from configaroo import loaders
+from configaroo.exceptions import MissingEnvironmentVariableError
+
+
+class Configuration(UserDict):
+    """A Configuration is a dict-like structure with some conveniences"""
+
+    @classmethod
+    def from_file(
+        cls,
+        file_path: str | Path,
+        loader: str | None = None,
+        envs: dict[str, str] | None = None,
+        env_prefix: str = "",
+        extra_dynamic: dict[str, Any] | None = None,
+        model: Type[BaseModel] | None = None,
+    ) -> Self:
+        """Read a Configuration from a file"""
+        config_dict = loaders.from_file(file_path, loader=loader)
+        return cls(**config_dict).initialize(envs=envs, model=model)
+
+    def initialize(
+        self,
+        envs: dict[str, str] | None = None,
+        env_prefix: str = "",
+        extra_dynamic: dict[str, Any] | None = None,
+        model: Type[BaseModel] | None = None,
+    ) -> Self:
+        """Initialize a configuration.
+
+        The initialization adds environment variables, parses dynamic values,
+        validates against a Pydantic model, and converts value types using the
+        same model.
+        """
+        self = self if envs is None else self.add_envs(envs, prefix=env_prefix)
+        self = self.parse_dynamic(extra_dynamic)
+        self = self if model is None else self.validate(model).convert(model)
+        return self
+
+    def __getitem__(self, key: str) -> Any:
+        """Make sure nested sections have type Configuration"""
+        value = self.data[key]
+        if isinstance(value, dict | UserDict | Configuration):
+            return Configuration(**value)
+        else:
+            return value
+
+    def __getattr__(self, key: str) -> Any:
+        """Create attribute access for config keys for convenience"""
+        try:
+            return self[key]
+        except KeyError:
+            raise AttributeError(
+                f"'{type(self).__name__}' has no attribute or key '{key}'"
+            )
+
+    def __contains__(self, key: str) -> bool:
+        """Add support for dotted keys"""
+        if key in self.data:
+            return True
+        prefix, _, rest = key.partition(".")
+        try:
+            return rest in self[prefix]
+        except KeyError:
+            return False
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Allow dotted keys when using .get()"""
+        if key not in self.data:
+            prefix, _, rest = key.partition(".")
+            try:
+                return self[prefix].get(rest, default=default)
+            except KeyError:
+                return default
+        else:
+            return self[key]
+
+    def add(self, key: str, value: Any) -> Self:
+        """Add a value, allow dotted keys"""
+        prefix, _, rest = key.partition(".")
+        if rest:
+            cls = type(self)
+            return self | {prefix: cls(**self.setdefault(prefix, {})).add(rest, value)}
+        else:
+            return self | {key: value}
+
+    def add_envs(self, envs: dict[str, str], prefix: str = "", use_dotenv=True) -> Self:
+        """Add environment variables to configuration"""
+        if use_dotenv:
+            dotenv.load_dotenv()
+
+        for env, key in envs.items():
+            env_key = f"{prefix}{env}"
+            env_value = os.getenv(env_key)
+            if env_value:
+                self = self.add(key, env_value)
+            else:
+                if key not in self:
+                    raise MissingEnvironmentVariableError(
+                        f"required environment variable '{env_key}' not found"
+                    )
+        return self
+
+    def parse_dynamic(self, extra: dict[str, Any] | None = None) -> Self:
+        """Parse dynamic values of the form {section.key}"""
+        cls = type(self)
+        variables = (
+            self.to_flat_dict()
+            | {"project_path": Path(__file__).parent.parent.parent}
+            | ({} if extra is None else extra)
+        )
+        return cls(
+            **{
+                key: (
+                    value.parse_dynamic(extra=variables)
+                    if isinstance(value, Configuration)
+                    else value.format(**variables)
+                    if isinstance(value, str)
+                    else value
+                )
+                for key, value in self.items()
+            }
+        )
+
+    def validate(self, model: Type[BaseModel]) -> Self:
+        """Validate the configuration against the given model."""
+        model.model_validate(self.data)
+        return self
+
+    def convert(self, model: Type[BaseModel]) -> Self:
+        """Convert data types to match the given model"""
+        cls = type(self)
+        return cls(**model(**self.data).model_dump())
+
+    def to_dict(self) -> dict[str, Any]:
+        """Dump the configuration into a Python dictionary"""
+        return {
+            key: value.to_dict() if isinstance(value, Configuration) else value
+            for key, value in self.items()
+        }
+
+    def to_flat_dict(self, _prefix: str = "") -> dict[str, Any]:
+        """Dump the configuration into a flat dictionary.
+
+        Nested configurations are converted into dotted keys.
+        """
+        return {
+            f"{_prefix}{key}": value
+            for key, value in self.items()
+            if not isinstance(value, Configuration)
+        } | {
+            key: value
+            for nested_key, nested_value in self.items()
+            if isinstance(nested_value, Configuration)
+            for key, value in (
+                self[nested_key].to_flat_dict(_prefix=f"{_prefix}{nested_key}.").items()
+            )
+        }

configaroo/exceptions.py

@@ -0,0 +1,13 @@
+"""Configaroo specific exceptions"""
+
+
+class ConfigarooException(Exception):
+    """Base exception for more specific Configaroo exceptions"""
+
+
+class MissingEnvironmentVariableError(ConfigarooException, KeyError):
+    """A required environment variable is missing"""
+
+
+class UnsupportedLoaderError(ConfigarooException, ValueError):
+    """An unsupported loader is called"""

configaroo/loaders/__init__.py

@@ -0,0 +1,24 @@
+"""Loaders that read configuration files."""
+
+from pathlib import Path
+from typing import Any
+
+import pyplugs
+
+from configaroo.exceptions import UnsupportedLoaderError
+
+load = pyplugs.call_factory(__package__)
+loader_names = pyplugs.names_factory(__package__)
+
+
+def from_file(path: str | Path, loader: str | None = None) -> dict[str, Any]:
+    """Load a file using a loader defined by the suffix if necessary."""
+    path = Path(path)
+    loader = path.suffix.lstrip(".") if loader is None else loader
+    try:
+        return load(loader, path=path)
+    except pyplugs.UnknownPluginError:
+        raise UnsupportedLoaderError(
+            f"file type '{loader}' isn't supported. "
+            f"Use one of: {', '.join(loader_names())}"
+        ) from None

configaroo/loaders/json.py

@@ -0,0 +1,13 @@
+"""Loader for JSON-files"""
+
+import json
+from pathlib import Path
+from typing import Any
+
+import pyplugs
+
+
+@pyplugs.register
+def load_json_file(path: Path) -> dict[str, Any]:
+    """Read a JSON-file"""
+    return json.loads(path.read_text(encoding="utf-8"))

configaroo/loaders/toml.py

@@ -0,0 +1,13 @@
+"""Loader for TOML-files"""
+
+import tomllib
+from pathlib import Path
+from typing import Any
+
+import pyplugs
+
+
+@pyplugs.register
+def load_toml_file(path: Path) -> dict[str, Any]:
+    """Read a TOML-file"""
+    return tomllib.loads(path.read_text(encoding="utf-8"))

configaroo-0.1.0.dist-info/METADATA

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: configaroo
+Version: 0.1.0
+Summary: Bouncy handling of configuration files
+Author-email: Geir Arne Hjelle <geirarne@gmail.com>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyplugs>=0.4.0
+Requires-Dist: python-dotenv>=1.1.0
+
+# Configaroo - Bouncy Configuration Handling
+
+Configaroo is a light configuration package for Python that offers the following features:
+
+- Access configuration settings with dotted keys: `config.nested.key`
+- Use different configuration file formats, including TOML and JSON
+- Override key configuration settings with environment variables
+- Validate a configuration based on a Pydantic model
+- Convert the type of configuration values based on a Pydantic model
+- Dynamically format certain configuration values

configaroo-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+configaroo/__init__.py,sha256=10BHeYLHiIz-oAGM1IdfaqBKyHbn2hiNnjS_zrFOtC8,232
+configaroo/configuration.py,sha256=V1Dx9LdkRlUSq46Djdq12sWb9JfNi_8N4VBnkXdB11s,5821
+configaroo/exceptions.py,sha256=1h-6hV7VqqKaRFnu539pjsO0ESSNDibt2kUeF7jAM2M,374
+configaroo/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+configaroo/loaders/__init__.py,sha256=-6GAR4g7vYW7Zagq9Ev479kpkfY7kbvDl4JPXd4wQQ0,756
+configaroo/loaders/json.py,sha256=6gs_ZegUEe70vb6uSJfKBos7UjfuJnyWgPE_kjDQISw,258
+configaroo/loaders/toml.py,sha256=ZVbHutZ7V-Z_jf2aHjV18jwaqCXumlr06j48rojHcBM,264
+configaroo-0.1.0.dist-info/METADATA,sha256=Oy67b4ut26KSC43oh5g50fpjR_Mz5chJ0iqvo4nrWIo,827
+configaroo-0.1.0.dist-info/WHEEL,sha256=zaaOINJESkSfm_4HQVc5ssNzHCPXhJm0kEUakpsEHaU,91
+configaroo-0.1.0.dist-info/top_level.txt,sha256=JVYICl1cWSjvSOZuZMYm976z9lnZaWtHVRSt373QCxg,11
+configaroo-0.1.0.dist-info/RECORD,,

configaroo-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.8.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

configaroo-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+configaroo