proteus-config 0.2.0__py3-none-any.whl

proteus/__init__.py

@@ -0,0 +1,48 @@
+"""
+Proteus — Unified configuration management and translation library.
+
+Design patterns implemented:
+    - **Optional Singleton**: ``ConfigurationManager.instance()``
+      (shared global instance when needed)
+    - **Facade**:          ``ConfigurationManager`` (simplified public API)
+    - **Factory Method**:  ``FormatCreator`` (reader/writer pair creation)
+    - **Template Method**: ``BaseReader`` / ``BaseWriter`` (fixed algorithms)
+    - **Adapter**:         ``BaseAdapter`` (wraps external libraries)
+
+Quick start::
+
+    from proteus import ConfigurationManager
+
+    config = ConfigurationManager()
+    config.load("settings.yaml")
+    print(config.get("database.host"))
+    config.translate("settings.yaml", "settings.json")
+    with ConfigurationManager.temporary() as temp:
+        temp.load("settings.yaml")
+"""
+
+from .adapters.base import BaseAdapter
+from .core import ConfigurationManager
+from .exceptions import (
+    ConfigurationError,
+    ConfigurationNotLoadedError,
+    InvalidKeyError,
+    UnsupportedFormatError,
+)
+from .formats.base_format import FormatCreator
+from .readers.base import BaseReader
+from .writers.base import BaseWriter
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ConfigurationManager",
+    "FormatCreator",
+    "BaseReader",
+    "BaseWriter",
+    "BaseAdapter",
+    "ConfigurationError",
+    "UnsupportedFormatError",
+    "InvalidKeyError",
+    "ConfigurationNotLoadedError",
+]

proteus/adapters/__init__.py

@@ -0,0 +1,20 @@
+"""
+Adapter layer — wraps external libraries behind the uniform BaseAdapter interface.
+
+Adapter pattern (GoF):
+    Target  → BaseAdapter
+    Adapter → JSONAdapter, YAMLAdapter, EnvAdapter
+    Adaptee → json (stdlib), yaml (PyYAML), dotenv (python-dotenv)
+"""
+
+from .base import BaseAdapter
+from .env_adapter import EnvAdapter
+from .json_adapter import JSONAdapter
+from .yaml_adapter import YAMLAdapter
+
+__all__ = [
+    "BaseAdapter",
+    "JSONAdapter",
+    "YAMLAdapter",
+    "EnvAdapter",
+]

proteus/adapters/base.py

@@ -0,0 +1,57 @@
+from abc import ABC, abstractmethod
+from typing import Any, Dict
+
+
+class BaseAdapter(ABC):
+    """
+    Adapter pattern (GoF) — Target interface.
+
+    Defines the uniform contract that all concrete adapters must fulfill.
+    Readers and Writers depend exclusively on this abstraction, never on
+    external libraries (Adaptees) directly. Swapping a library requires
+    changes only inside the concrete adapter, nowhere else.
+
+    GoF roles:
+        Target  → BaseAdapter                  (this class)
+        Adapter → JSONAdapter, YAMLAdapter, EnvAdapter, ...
+        Adaptee → json, yaml, dotenv, ...      (external libraries)
+
+    Internal representation (IR):
+        Every load()  call returns Dict[str, Any].
+        Every dump()  call accepts Dict[str, Any].
+        Semantics depend on the format (e.g. .env is flat while
+        JSON/YAML support nesting). Conversion logic lives in the
+        concrete adapter, not in the Reader or Writer.
+    """
+
+    @abstractmethod
+    def load(self, raw: str) -> Dict[str, Any]:
+        """
+        Parse a raw string in the format-specific encoding into the IR.
+
+        Args:
+            raw: Full text content of the configuration file.
+
+        Returns:
+            A Dict[str, Any] representing the parsed configuration.
+
+        Raises:
+            ValueError: If the raw content cannot be parsed.
+        """
+        pass
+
+    @abstractmethod
+    def dump(self, data: Dict[str, Any]) -> str:
+        """
+        Serialize the IR (a plain Python dict) into a format-specific string.
+
+        Args:
+            data: Configuration data as a plain Python dict.
+
+        Returns:
+            A string ready to be written to disk.
+
+        Raises:
+            ValueError: If the data cannot be serialized.
+        """
+        pass

proteus/adapters/env_adapter.py

@@ -0,0 +1,121 @@
+"""
+Adapter pattern (GoF) — Concrete adapter for .env files.
+
+Adaptee: python-dotenv  (dotenv.dotenv_values)
+Target:  BaseAdapter
+
+.env format: flat KEY=value pairs, one entry per line.
+Supports comments (#), single/double quotes, and the export prefix.
+
+IR: Dict[str, str] — all values are strings (inherent to the format).
+    Keys preserve the original casing from the file.
+    Convention: keys are typically UPPER_CASE.
+"""
+
+import io
+from typing import Any, Dict
+
+from dotenv import dotenv_values
+
+from .base import BaseAdapter
+
+
+class EnvAdapter(BaseAdapter):
+    """
+    Wraps python-dotenv (Adaptee) behind the BaseAdapter interface (Target).
+
+    Note on the IR for .env files:
+        The .env format is inherently flat: it does not support nesting.
+        The resulting IR is therefore Dict[str, str] with all keys and
+        values as plain strings.
+
+        When dump() receives a nested dict (e.g. translated from JSON),
+        nested keys are flattened using "__" as separator:
+            {"database": {"host": "localhost"}} → DATABASE__HOST=localhost
+
+    GoF roles:
+        Target  → BaseAdapter
+        Adapter → EnvAdapter             (this class)
+        Adaptee → dotenv.dotenv_values    (python-dotenv)
+    """
+
+    def load(self, raw: str) -> Dict[str, Any]:
+        """
+        Delegate to dotenv_values(stream=...) and return the IR dict.
+
+        Args:
+            raw: Full text content of a .env file.
+
+        Returns:
+            Dict[str, str] with the KEY=value pairs from the file.
+            Keys with no value (e.g. KEY=) are mapped to an empty string.
+
+        Raises:
+            ValueError: If raw cannot be parsed as a .env file.
+        """
+        try:
+            parsed = dotenv_values(stream=io.StringIO(raw))
+        except Exception as exc:
+            raise ValueError(f"Invalid .env content: {exc}") from exc
+
+        # dotenv_values may return None for keys with no assigned value
+        return {k: (v if v is not None else "") for k, v in parsed.items()}
+
+    def dump(self, data: Dict[str, Any]) -> str:
+        """
+        Serialize a Dict (IR) into .env KEY=value format.
+
+        Nested dicts are flattened using "__" as separator:
+            {'database': {'host': 'localhost'}} → DATABASE__HOST=localhost
+
+        Non-string values are converted via str().
+        Values containing spaces or special characters are automatically
+        wrapped in double quotes.
+
+        Args:
+            data: Configuration dict (IR).
+
+        Returns:
+            String in .env format.
+        """
+        flat = self._flatten(data)
+        lines = []
+        for key, value in flat.items():
+            str_value = str(value)
+            # .env uses double quotes; quote manually instead of shlex.quote
+            if self._needs_quoting(str_value):
+                str_value = '"' + str_value.replace('"', '\\"') + '"'
+            lines.append(f"{key}={str_value}")
+        return "\n".join(lines) + ("\n" if lines else "")
+
+    # ------------------------------------------------------------------ #
+    # Private helpers                                                       #
+    # ------------------------------------------------------------------ #
+
+    def _flatten(
+        self,
+        data: Dict[str, Any],
+        prefix: str = "",
+    ) -> Dict[str, str]:
+        """
+        Recursively flatten a nested dict into a flat string dict.
+
+        {'db': {'host': 'localhost', 'port': 5432}, 'debug': True}
+        →  {'DB__HOST': 'localhost', 'DB__PORT': '5432', 'DEBUG': 'True'}
+        """
+        result: Dict[str, str] = {}
+        for key, value in data.items():
+            full_key = f"{prefix}__{key}".upper() if prefix else key.upper()
+            if isinstance(value, dict):
+                result.update(self._flatten(value, prefix=full_key))
+            else:
+                result[full_key] = str(value)
+        return result
+
+    @staticmethod
+    def _needs_quoting(value: str) -> bool:
+        """Return True if the value must be wrapped in double quotes."""
+        # Quoting required for: empty string, spaces, =, #, $, newlines
+        return value == "" or any(
+            c in value for c in (" ", "\t", "=", "#", "$", "\n", "'", '"')
+        )

proteus/adapters/json_adapter.py

@@ -0,0 +1,67 @@
+"""
+Adapter pattern (GoF) — Concrete adapter for JSON.
+
+Adaptee: json  (Python standard library)
+Target:  BaseAdapter
+"""
+
+import json
+from typing import Any, Dict
+
+from .base import BaseAdapter
+
+
+class JSONAdapter(BaseAdapter):
+    """
+    Wraps the json stdlib module (Adaptee) behind the BaseAdapter interface (Target).
+
+    Shared by JSONReader and JSONWriter: replacing the underlying library
+    (e.g. switching to orjson) requires changes only here.
+
+    GoF roles:
+        Target  → BaseAdapter
+        Adapter → JSONAdapter        (this class)
+        Adaptee → json (stdlib)       json.loads / json.dumps
+    """
+
+    def load(self, raw: str) -> Dict[str, Any]:
+        """
+        Delegate to json.loads() and return the IR dict.
+
+        Args:
+            raw: JSON-encoded string.
+
+        Returns:
+            Dict representing the parsed configuration.
+
+        Raises:
+            ValueError: If raw is not valid JSON or the root is not an object.
+        """
+        try:
+            result = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"Invalid JSON content: {exc}") from exc
+
+        if not isinstance(result, dict):
+            raise ValueError(
+                f"JSON document root must be an object, got: {type(result).__name__}"
+            )
+        return result
+
+    def dump(self, data: Dict[str, Any]) -> str:
+        """
+        Delegate to json.dumps() and return the JSON string.
+
+        Args:
+            data: Configuration dict (IR).
+
+        Returns:
+            Pretty-printed JSON string (2-space indent, unicode preserved).
+
+        Raises:
+            ValueError: If data cannot be serialized to JSON.
+        """
+        try:
+            return json.dumps(data, indent=2, ensure_ascii=False)
+        except (TypeError, ValueError) as exc:
+            raise ValueError(f"Cannot serialize to JSON: {exc}") from exc

proteus/adapters/toml_adapter.py

@@ -0,0 +1,59 @@
+import sys
+from typing import Any, Dict, cast
+
+from .base import BaseAdapter
+
+# Handle TOML parsing based on Python version
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+import tomli_w
+
+
+class TOMLAdapter(BaseAdapter):
+    """
+    Adapter for TOML configuration format.
+
+    Uses the standard library ``tomllib`` (Python 3.11+) or the ``tomli``
+    backport for parsing, and ``tomli-w`` for serialization.
+    """
+
+    def load(self, raw: str) -> Dict[str, Any]:
+        """
+        Parse a TOML string into a dictionary.
+
+        Args:
+            raw: TOML formatted string.
+
+        Returns:
+            A dictionary representation of the TOML data.
+
+        Raises:
+            ValueError: If the TOML is invalid.
+        """
+        try:
+            data = tomllib.loads(raw)
+            if not isinstance(data, dict):
+                raise ValueError("TOML root must be a dictionary")
+            return cast(Dict[str, Any], data)
+        except Exception as e:
+            raise ValueError(f"Invalid TOML content: {e}") from e
+
+    def dump(self, data: Dict[str, Any]) -> str:
+        """
+        Serialize a dictionary into a TOML string.
+
+        Args:
+            data: Dictionary to serialize.
+
+        Returns:
+            A TOML formatted string.
+
+        Raises:
+            TypeError: If data is not a dictionary.
+        """
+        if not isinstance(data, dict):
+            raise TypeError("TOML serialization requires a dictionary at the root")
+        return cast(str, tomli_w.dumps(data))

proteus/adapters/yaml_adapter.py

@@ -0,0 +1,79 @@
+"""
+Adapter pattern (GoF) — Concrete adapter for YAML.
+
+Adaptee: yaml  (PyYAML)
+Target:  BaseAdapter
+"""
+
+from typing import Any, Dict
+
+import yaml
+
+from .base import BaseAdapter
+
+
+class YAMLAdapter(BaseAdapter):
+    """
+    Wraps PyYAML (Adaptee) behind the BaseAdapter interface (Target).
+
+    Uses yaml.safe_load() instead of yaml.load() for security:
+    it prevents arbitrary Python object deserialization.
+
+    Shared by YAMLReader and YAMLWriter.
+
+    GoF roles:
+        Target  → BaseAdapter
+        Adapter → YAMLAdapter        (this class)
+        Adaptee → yaml (PyYAML)       yaml.safe_load / yaml.dump
+    """
+
+    def load(self, raw: str) -> Dict[str, Any]:
+        """
+        Delegate to yaml.safe_load() and return the IR dict.
+
+        Args:
+            raw: YAML-encoded string.
+
+        Returns:
+            Dict representing the parsed configuration.
+
+        Raises:
+            ValueError: If raw is not valid YAML or the root is not a mapping.
+        """
+        try:
+            result = yaml.safe_load(raw)
+        except yaml.YAMLError as exc:
+            raise ValueError(f"Invalid YAML content: {exc}") from exc
+
+        # Empty file or comments-only → safe_load returns None
+        if result is None:
+            return {}
+
+        if not isinstance(result, dict):
+            raise ValueError(
+                f"YAML document root must be a mapping, got: {type(result).__name__}"
+            )
+        return result
+
+    def dump(self, data: Dict[str, Any]) -> str:
+        """
+        Delegate to yaml.dump() and return the YAML string.
+
+        Args:
+            data: Configuration dict (IR).
+
+        Returns:
+            Human-readable YAML string (block style, unicode preserved).
+
+        Raises:
+            ValueError: If data cannot be serialized to YAML.
+        """
+        try:
+            return yaml.dump(
+                data,
+                default_flow_style=False,
+                allow_unicode=True,
+                sort_keys=False,
+            )
+        except yaml.YAMLError as exc:
+            raise ValueError(f"Cannot serialize to YAML: {exc}") from exc