configaroo 0.1.0__tar.gz

configaroo-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,10 @@
+# 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/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name            = "configaroo"
+version         = "0.1.0"
+description     = "Bouncy handling of configuration files"
+readme          = "README.md"
+authors         = [{ name = "Geir Arne Hjelle", email = "geirarne@gmail.com" }]
+requires-python = ">=3.11"
+dependencies    = ["pydantic>=2.0", "pyplugs>=0.4.0", "python-dotenv>=1.1.0"]
+
+[build-system]
+requires      = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[dependency-groups]
+dev = ["ipython>=8.36.0", "pytest>=8.3.5", "ruff>=0.11.11", "tomli-w>=1.2.0"]

configaroo-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

configaroo-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/src/configaroo.egg-info/PKG-INFO

@@ -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/src/configaroo.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+README.md
+pyproject.toml
+src/configaroo/__init__.py
+src/configaroo/configuration.py
+src/configaroo/exceptions.py
+src/configaroo/py.typed
+src/configaroo.egg-info/PKG-INFO
+src/configaroo.egg-info/SOURCES.txt
+src/configaroo.egg-info/dependency_links.txt
+src/configaroo.egg-info/requires.txt
+src/configaroo.egg-info/top_level.txt
+src/configaroo/loaders/__init__.py
+src/configaroo/loaders/json.py
+src/configaroo/loaders/toml.py
+tests/test_configuration.py
+tests/test_environment.py
+tests/test_json.py
+tests/test_loaders.py
+tests/test_toml.py
+tests/test_validation.py

configaroo-0.1.0/src/configaroo.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

configaroo-0.1.0/src/configaroo.egg-info/requires.txt

@@ -0,0 +1,3 @@
+pydantic>=2.0
+pyplugs>=0.4.0
+python-dotenv>=1.1.0

configaroo-0.1.0/src/configaroo.egg-info/top_level.txt

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

configaroo-0.1.0/tests/test_configuration.py

@@ -0,0 +1,110 @@
+"""Test base Configuration functionality"""
+
+import pytest
+
+from configaroo import Configuration
+
+
+def test_read_simple_values_as_attributes(config):
+    """Test attribute access for simple values."""
+    assert config.number == 42
+    assert config.word == "platypus"
+    assert config.things == ["house", "car", "kayak"]
+
+
+def test_read_simple_values_as_items(config):
+    """Test dictionary access for simple values."""
+    assert config["number"] == 42
+    assert config["word"] == "platypus"
+    assert config["things"] == ["house", "car", "kayak"]
+
+
+def test_missing_attributes_raise_attribute_error(config):
+    """Test that accessing missing attributes raise the appropriate error"""
+    with pytest.raises(AttributeError):
+        config.non_existent
+
+
+def test_nested_values_are_configurations(config):
+    """Test that a nested configuration has type Configuration"""
+    assert isinstance(config["nested"], Configuration)
+
+
+def test_read_nested_values_as_attributes(config):
+    """Test attribute access for nested values."""
+    assert config.nested.pie == 3.14
+    assert config.nested.seven == 7
+
+
+def test_read_nested_values_as_items(config):
+    """Test dictionary access for nested values."""
+    assert config["nested"]["pie"] == 3.14
+    assert config["nested"]["seven"] == 7
+    assert config["with_dot"]["org.num"] == 1234
+
+
+def test_read_nested_values_as_attributes_and_items(config):
+    """Test mixed access for nested values."""
+    assert config["nested"].pie == 3.14
+    assert config.nested["seven"] == 7
+
+
+def test_get_nested_values(config):
+    """Test that .get() can use dotted keys"""
+    assert config.get("nested.seven") == 7
+    assert config.get("with_dot.org.num") == 1234
+
+
+def test_update_preserves_type(config):
+    """Test that an update operation gives a Configuration"""
+    assert isinstance(config | {"new": 1}, Configuration)
+
+    config.update(new=1)
+    assert isinstance(config, Configuration)
+
+
+def test_dump_to_dict(config):
+    """Test that dumping to a dictionary unwraps nested sections"""
+    config_dict = config.to_dict()
+    assert isinstance(config_dict, dict)
+    assert isinstance(config_dict["paths"], dict)
+
+
+def test_dump_to_flat_dict(config):
+    """Test that a configuration can be converted to a flat dictionary"""
+    flat_config_dict = config.to_flat_dict()
+    assert isinstance(flat_config_dict, dict)
+    assert flat_config_dict["number"] == 42
+    assert flat_config_dict["nested.seven"] == 7
+    assert flat_config_dict["nested.deep.sea"] == "Marianer"
+    assert flat_config_dict["with_dot.org.num"] == 1234
+
+
+def test_contains_with_simple_key(config):
+    """Test that "key" in config works for simple keys"""
+    assert "number" in config
+    assert "not_there" not in config
+
+
+def test_contains_with_dotted_key(config):
+    """Test that "key" in config works for dotted keys"""
+    assert "nested.seven" in config
+    assert "with_dot.org.num" in config
+    assert "nested.number" not in config
+
+
+def test_parse_dynamic_default(config):
+    """Test parsing of default dynamic variables"""
+    parsed_config = config.parse_dynamic()
+    assert parsed_config.paths.dynamic == __file__
+    assert parsed_config.phrase == "The meaning of life is 42"
+
+
+def test_parse_dynamic_extra(config):
+    """Test parsing of extra dynamic variables"""
+    parsed_config = (config | {"animal": "{adjective} platypus"}).parse_dynamic(
+        extra={"number": 14, "adjective": "tall"}
+    )
+    assert parsed_config.paths.dynamic == __file__
+    assert parsed_config.phrase == "The meaning of life is 14"
+    assert parsed_config.animal == "tall platypus"

configaroo-0.1.0/tests/test_environment.py

@@ -0,0 +1,53 @@
+"""Test handling of environment variables"""
+
+import pytest
+
+from configaroo import MissingEnvironmentVariableError
+
+
+def test_add_one_env(config, monkeypatch):
+    """Test that we can add one environment variable in a new field"""
+    monkeypatch.setenv("WORD", "platypus")
+    config_w_env = config.add_envs({"WORD": "nested.word"})
+    assert config_w_env.nested.word == "platypus"
+
+
+def test_overwrite_one_env(config, monkeypatch):
+    """Test that we can overwrite a value with an environment value"""
+    monkeypatch.setenv("NEW_PATH", "files/config.json")
+    config_w_env = config.add_envs({"NEW_PATH": "path"})
+    assert config_w_env.path == "files/config.json"
+
+
+def test_several_envs(config, monkeypatch):
+    """Test that we can read several environment variables"""
+    monkeypatch.setenv("WORD", "platypus")
+    monkeypatch.setenv("NEW_PATH", "files/config.json")
+    config_w_env = config.add_envs({"WORD": "nested.word", "NEW_PATH": "path"})
+    assert config_w_env.nested.word == "platypus"
+    assert config_w_env.path == "files/config.json"
+
+
+def test_error_on_missing_env(config):
+    """Test that a missing environment variable raises an error if the value is not set already"""
+    with pytest.raises(KeyError):
+        config.add_envs({"NON_EXISTENT": "non_existent"})
+    with pytest.raises(MissingEnvironmentVariableError):
+        config.add_envs({"NON_EXISTENT": "non_existent"})
+
+
+def test_missing_env_ok_if_optional(config):
+    """Test that a missing environment variable is ok if the value is already set"""
+    config_w_env = config.add_envs({"NON_EXISTENT": "number"})
+    assert config_w_env.number == 42
+
+
+def test_env_prefix(config, monkeypatch):
+    """Test that a common prefix can be used for environment_variables"""
+    monkeypatch.setenv("EXAMPLE_NUMBER", "14")
+    monkeypatch.setenv("EXAMPLE_WORD", "platypus")
+    config_w_env = config.add_envs(
+        {"NUMBER": "number", "WORD": "nested.word"}, prefix="EXAMPLE_"
+    )
+    assert config_w_env.number == "14"
+    assert config_w_env.nested.word == "platypus"

configaroo-0.1.0/tests/test_json.py

@@ -0,0 +1,44 @@
+"""Test handling of JSON files"""
+
+import json
+
+import pytest
+
+from configaroo import Configuration
+
+
+def test_can_load_config_from_toml(json_path):
+    """Test that the TOML file can be loaded"""
+    config = Configuration.from_file(json_path)
+    assert config
+
+
+def test_can_load_config_with_path_as_str(json_path):
+    """Test that the path can be specified in a string"""
+    config = Configuration.from_file(str(json_path))
+    assert config
+
+
+def test_can_specify_loader(other_json_path):
+    """Test that we can specify the "json" loader"""
+    config = Configuration.from_file(other_json_path, loader="json")
+    assert config
+
+
+def test_error_on_nonexisting_file():
+    """Test that a FileNotFoundError is raised if the file doesn't exist"""
+    with pytest.raises(FileNotFoundError):
+        Configuration.from_file("non-existent.json")
+
+
+def test_error_on_wrong_format(toml_path):
+    """Test that a JSONDecodeError is raised if the file is not a valid JSON-file"""
+    with pytest.raises(json.JSONDecodeError):
+        Configuration.from_file(toml_path, loader="json")
+
+
+def test_can_read_json_values(json_path):
+    """Test that values can be accessed"""
+    config = Configuration.from_file(json_path)
+    assert config.word == "platypus"
+    assert config.nested.seven == 7

configaroo-0.1.0/tests/test_loaders.py

@@ -0,0 +1,38 @@
+"""Test file loader framework"""
+
+import pytest
+
+from configaroo import UnsupportedLoaderError, loaders
+
+
+def test_unsupported_loader(toml_path):
+    """Test that calling an unsupported loader fails"""
+    with pytest.raises(UnsupportedLoaderError):
+        loaders.from_file(toml_path, loader="non_existent")
+
+
+def test_unsupported_suffix(toml_path):
+    """Test that loading a file with an unsupported suffix fails"""
+    with pytest.raises(UnsupportedLoaderError):
+        loaders.from_file(toml_path.with_suffix(".non_existent"))
+
+
+def test_error_lists_supported_loaders(toml_path):
+    """Test that the names of supported loaders are listed when failing"""
+    try:
+        loaders.from_file(toml_path.with_suffix(".non_existent"))
+    except UnsupportedLoaderError as err:
+        for loader in ["json", "toml"]:
+            assert loader in str(err)
+
+
+def test_toml_returns_dict(toml_path):
+    """Test that the TOML loader returns a nonempty dictionary"""
+    config_dict = loaders.from_file(toml_path, loader="toml")
+    assert config_dict and isinstance(config_dict, dict)
+
+
+def test_json_returns_dict(json_path):
+    """Test that the JSON loader returns a nonempty dictionary"""
+    config_dict = loaders.from_file(json_path, loader="json")
+    assert config_dict and isinstance(config_dict, dict)

configaroo-0.1.0/tests/test_toml.py

@@ -0,0 +1,44 @@
+"""Test handling of TOML files"""
+
+import tomllib
+
+import pytest
+
+from configaroo import Configuration
+
+
+def test_can_load_config_from_toml(toml_path):
+    """Test that the TOML file can be loaded"""
+    config = Configuration.from_file(toml_path)
+    assert config
+
+
+def test_can_load_config_with_path_as_str(toml_path):
+    """Test that the path can be specified in a string"""
+    config = Configuration.from_file(str(toml_path))
+    assert config
+
+
+def test_can_specify_loader(other_toml_path):
+    """Test that we can specify the "toml" loader"""
+    config = Configuration.from_file(other_toml_path, loader="toml")
+    assert config
+
+
+def test_error_on_nonexisting_file():
+    """Test that a FileNotFoundError is raised if the file doesn't exist"""
+    with pytest.raises(FileNotFoundError):
+        Configuration.from_file("non-existent.toml")
+
+
+def test_error_on_wrong_format(json_path):
+    """Test that a TOMLDecodeError is raised if the file is not a valid TOML-file"""
+    with pytest.raises(tomllib.TOMLDecodeError):
+        Configuration.from_file(json_path, loader="toml")
+
+
+def test_can_read_toml_values(toml_path):
+    """Test that values can be accessed"""
+    config = Configuration.from_file(toml_path)
+    assert config.word == "platypus"
+    assert config.nested.seven == 7

configaroo-0.1.0/tests/test_validation.py

@@ -0,0 +1,42 @@
+"""Test validation and type conversion with Pydantic"""
+
+from pathlib import Path
+
+import pydantic
+import pytest
+
+from configaroo import Configuration
+
+
+def test_can_validate(config, model):
+    """Test that a configuration can be validated"""
+    assert config.validate(model)
+
+
+def test_wrong_key_raises(model):
+    """Test that a wrong key raises an error"""
+    config = Configuration(
+        digit=4, nested={"pie": 3.14, "seven": 7}, path="files/config.toml"
+    )
+    with pytest.raises(pydantic.ValidationError):
+        config.validate(model)
+
+
+def test_missing_key_raises(model):
+    """Test that a missing key raises an error"""
+    config = Configuration(nested={"pie": 3.14, "seven": 7}, path="files/config.toml")
+    with pytest.raises(pydantic.ValidationError):
+        config.validate(model)
+
+
+def test_extra_key_ok(config, model):
+    """Test that an extra key raises when the model is strict"""
+    updated_config = config | {"new_word": "cuckoo-bird"}
+    with pytest.raises(pydantic.ValidationError):
+        updated_config.validate(model)
+
+
+def test_type_conversion(config, model):
+    config_w_types = config.convert(model)
+    assert isinstance(config.paths.relative, str)
+    assert isinstance(config_w_types.paths.relative, Path)