cfgable 0.1.0__tar.gz

cfgable-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.egg
+
+# Tooling / caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store

cfgable-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenGHz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cfgable-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: cfgable
+Version: 0.1.0
+Summary: Reusable pydantic/dataclass-driven configuration framework with an optional Hydra bridge.
+Project-URL: Repository, https://github.com/OpenGHz/cfgable
+Author: OpenGHz
+License: MIT
+License-File: LICENSE
+Keywords: config,configuration,hydra,pydantic,settings
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: pydantic-yaml
+Requires-Dist: pydantic>=2
+Requires-Dist: typing-extensions
+Provides-Extra: cli
+Requires-Dist: pydantic-settings; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: hydra-core; extra == 'dev'
+Requires-Dist: omegaconf; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Provides-Extra: hydra
+Requires-Dist: hydra-core; extra == 'hydra'
+Requires-Dist: omegaconf; extra == 'hydra'
+Description-Content-Type: text/markdown
+
+# cfgable
+
+A small, reusable configuration framework for Python, built on
+[pydantic](https://docs.pydantic.dev/). It lets every component declare a **single
+`config` object** and be constructed uniformly — from Python, from a YAML file, or from
+Hydra — with validation happening once at the boundary.
+
+The core depends only on pydantic; the Hydra bridge is optional.
+
+## Install
+
+```bash
+pip install cfgable            # core
+pip install "cfgable[hydra]"   # + Hydra bridge (hydra-core, omegaconf)
+```
+
+## The idea
+
+1. A component's settings are a pydantic model (`*Config`), documented with attribute
+   docstrings.
+2. Every class takes **one** `config` parameter and reads fields off it.
+3. Inheriting `ConfigurableBasis` lets the same class be built from an explicit config,
+   a plain mapping, or **flat keyword arguments** — the shape Hydra's `instantiate`
+   passes — because the `InitConfigMeta` metaclass assembles and validates the config
+   for you, then calls `config_post_init()`.
+
+```python
+from typing import Optional
+from pydantic import BaseModel, ConfigDict, PositiveInt
+from cfgable import ConfigurableBasis
+
+
+class CameraConfig(BaseModel, frozen=True):
+    """Configuration for a camera."""
+
+    model_config = ConfigDict(use_attribute_docstrings=True, extra="forbid")
+
+    device: str = "/dev/video0"
+    """Video device path."""
+    fps: PositiveInt = 30
+    """Capture rate in frames per second."""
+    serial: Optional[str] = None
+    """Optional camera serial number for disambiguation."""
+
+
+class Camera(ConfigurableBasis):
+    """A camera built from a single validated config."""
+
+    def __init__(self, config: CameraConfig):
+        self.config = config
+
+    def config_post_init(self):
+        super().config_post_init()
+        self._opened = False
+
+    def on_configure(self) -> bool:
+        self._opened = True
+        return True
+
+
+# All three build the same object:
+cam = Camera(CameraConfig(fps=60))            # explicit config
+cam = Camera({"fps": 60})                     # mapping
+cam = Camera(fps=60)                          # flat kwargs (Hydra-style)
+```
+
+## With Hydra
+
+Point `_target_` at the class and list the config fields as siblings; the metaclass turns
+them into the `config` model:
+
+```yaml
+# camera.yaml
+_target_: my_pkg.Camera
+fps: 60
+device: /dev/video2
+```
+
+```python
+from cfgable.hydra_utils import init_hydra_config, hydra_instance
+
+cam = hydra_instance(init_hydra_config("camera.yaml"))
+```
+
+For plain classes you can also nest the config under its own `_target_` so standard
+`hydra.utils.instantiate` builds `Camera(config=CameraConfig(...))`.
+
+## Round-tripping
+
+Because a component keeps its whole `config`, it can serialize back to the config that
+would rebuild it:
+
+```python
+cam.dump()                 # -> dict of fields + a "_target_" pointing at the class
+cam.save_config("cam.yaml")
+```
+
+## What's in the box
+
+- `ConfigurableBasis`, `InitConfigMixin`, `InitConfigABCMixin` — base classes for the
+  single-`config` construction protocol.
+- `InitConfigMeta` / `InitConfigABCMeta` — the metaclass that assembles configs.
+- `NoConfig` — placeholder for components that need no settings.
+- `StrEnum`, `ReprEnum` — a string-enum backport (use this `StrEnum`, not `enum.StrEnum`,
+  for consistent behavior across Python 3.9–3.13).
+- `ForceSetAttr` / `force_set_attr` — controlled mutation of otherwise-frozen configs.
+- `import_string`, `get_fully_qualified_class_name`, `dump_or_repr`, `fetch_config`.
+- `cfgable.hydra_utils` — `init_hydra_config`, `hydra_instance`,
+  `hydra_instance_from_dict`, `hydra_instance_from_config_path` (needs `[hydra]`).
+
+`import cfgable` never imports Hydra — the bridge is loaded only when you import
+`cfgable.hydra_utils`.
+
+## License
+
+MIT.

cfgable-0.1.0/README.md

@@ -0,0 +1,116 @@
+# cfgable
+
+A small, reusable configuration framework for Python, built on
+[pydantic](https://docs.pydantic.dev/). It lets every component declare a **single
+`config` object** and be constructed uniformly — from Python, from a YAML file, or from
+Hydra — with validation happening once at the boundary.
+
+The core depends only on pydantic; the Hydra bridge is optional.
+
+## Install
+
+```bash
+pip install cfgable            # core
+pip install "cfgable[hydra]"   # + Hydra bridge (hydra-core, omegaconf)
+```
+
+## The idea
+
+1. A component's settings are a pydantic model (`*Config`), documented with attribute
+   docstrings.
+2. Every class takes **one** `config` parameter and reads fields off it.
+3. Inheriting `ConfigurableBasis` lets the same class be built from an explicit config,
+   a plain mapping, or **flat keyword arguments** — the shape Hydra's `instantiate`
+   passes — because the `InitConfigMeta` metaclass assembles and validates the config
+   for you, then calls `config_post_init()`.
+
+```python
+from typing import Optional
+from pydantic import BaseModel, ConfigDict, PositiveInt
+from cfgable import ConfigurableBasis
+
+
+class CameraConfig(BaseModel, frozen=True):
+    """Configuration for a camera."""
+
+    model_config = ConfigDict(use_attribute_docstrings=True, extra="forbid")
+
+    device: str = "/dev/video0"
+    """Video device path."""
+    fps: PositiveInt = 30
+    """Capture rate in frames per second."""
+    serial: Optional[str] = None
+    """Optional camera serial number for disambiguation."""
+
+
+class Camera(ConfigurableBasis):
+    """A camera built from a single validated config."""
+
+    def __init__(self, config: CameraConfig):
+        self.config = config
+
+    def config_post_init(self):
+        super().config_post_init()
+        self._opened = False
+
+    def on_configure(self) -> bool:
+        self._opened = True
+        return True
+
+
+# All three build the same object:
+cam = Camera(CameraConfig(fps=60))            # explicit config
+cam = Camera({"fps": 60})                     # mapping
+cam = Camera(fps=60)                          # flat kwargs (Hydra-style)
+```
+
+## With Hydra
+
+Point `_target_` at the class and list the config fields as siblings; the metaclass turns
+them into the `config` model:
+
+```yaml
+# camera.yaml
+_target_: my_pkg.Camera
+fps: 60
+device: /dev/video2
+```
+
+```python
+from cfgable.hydra_utils import init_hydra_config, hydra_instance
+
+cam = hydra_instance(init_hydra_config("camera.yaml"))
+```
+
+For plain classes you can also nest the config under its own `_target_` so standard
+`hydra.utils.instantiate` builds `Camera(config=CameraConfig(...))`.
+
+## Round-tripping
+
+Because a component keeps its whole `config`, it can serialize back to the config that
+would rebuild it:
+
+```python
+cam.dump()                 # -> dict of fields + a "_target_" pointing at the class
+cam.save_config("cam.yaml")
+```
+
+## What's in the box
+
+- `ConfigurableBasis`, `InitConfigMixin`, `InitConfigABCMixin` — base classes for the
+  single-`config` construction protocol.
+- `InitConfigMeta` / `InitConfigABCMeta` — the metaclass that assembles configs.
+- `NoConfig` — placeholder for components that need no settings.
+- `StrEnum`, `ReprEnum` — a string-enum backport (use this `StrEnum`, not `enum.StrEnum`,
+  for consistent behavior across Python 3.9–3.13).
+- `ForceSetAttr` / `force_set_attr` — controlled mutation of otherwise-frozen configs.
+- `import_string`, `get_fully_qualified_class_name`, `dump_or_repr`, `fetch_config`.
+- `cfgable.hydra_utils` — `init_hydra_config`, `hydra_instance`,
+  `hydra_instance_from_dict`, `hydra_instance_from_config_path` (needs `[hydra]`).
+
+`import cfgable` never imports Hydra — the bridge is loaded only when you import
+`cfgable.hydra_utils`.
+
+## License
+
+MIT.

cfgable-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cfgable"
+version = "0.1.0"
+description = "Reusable pydantic/dataclass-driven configuration framework with an optional Hydra bridge."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "OpenGHz" }]
+keywords = ["pydantic", "hydra", "configuration", "config", "settings"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic >=2",
+    "typing-extensions",
+    "pydantic-yaml",
+]
+
+[project.optional-dependencies]
+hydra = ["hydra-core", "omegaconf"]
+cli = ["pydantic-settings"]
+dev = ["pytest", "hydra-core", "omegaconf"]
+
+[project.urls]
+Repository = "https://github.com/OpenGHz/cfgable"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cfgable"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

cfgable-0.1.0/src/cfgable/__init__.py

@@ -0,0 +1,75 @@
+"""cfgable: a reusable pydantic/dataclass-driven configuration framework.
+
+Components declare a single ``config`` parameter and (optionally) inherit
+``ConfigurableBasis``; the ``InitConfigMeta`` metaclass assembles that config from
+explicit objects, plain mappings, or flat keyword arguments (the shape Hydra's
+``instantiate`` passes), validating it once at construction.
+
+The core exported here depends only on pydantic. The optional Hydra bridge lives
+in ``cfgable.hydra_utils`` and is imported on demand, so ``import cfgable``
+never pulls in hydra/omegaconf.
+
+NOTE: do NOT add ``from .hydra_utils import ...`` to this module — it would make
+hydra a hard dependency of the core. Import it explicitly where you need it.
+"""
+
+from ._typing import (
+    AllConfigType,
+    BaseModelT,
+    ConfigType,
+    DataClassProto,
+    OtherCfgType,
+    T,
+)
+from .core import (
+    ConfigurableBasis,
+    InitConfigABCMeta,
+    InitConfigABCMixin,
+    InitConfigMeta,
+    InitConfigMixin,
+    InitConfigMixinBasis,
+    NoConfig,
+    dump_omegaconf,
+    dump_or_repr,
+    fetch_config,
+)
+from .enums import ReprEnum, StrEnum
+from .frozen import ForceSetAttr, force_set_attr, force_validate_field, validate_field
+from .reflection import (
+    get_full_class_name,
+    get_fully_qualified_class_name,
+    import_string,
+)
+
+__all__ = [
+    # typing
+    "ConfigType",
+    "AllConfigType",
+    "OtherCfgType",
+    "DataClassProto",
+    "BaseModelT",
+    "T",
+    # core
+    "NoConfig",
+    "InitConfigMeta",
+    "InitConfigABCMeta",
+    "InitConfigMixinBasis",
+    "InitConfigMixin",
+    "InitConfigABCMixin",
+    "ConfigurableBasis",
+    "dump_or_repr",
+    "dump_omegaconf",
+    "fetch_config",
+    # enums
+    "StrEnum",
+    "ReprEnum",
+    # frozen
+    "ForceSetAttr",
+    "force_set_attr",
+    "validate_field",
+    "force_validate_field",
+    # reflection
+    "import_string",
+    "get_fully_qualified_class_name",
+    "get_full_class_name",
+]

cfgable-0.1.0/src/cfgable/_typing.py

@@ -0,0 +1,28 @@
+"""Shared typing primitives for the cfgable framework."""
+
+from pathlib import Path
+from typing import Any, Dict, Optional, Protocol, Type, TypeVar, Union
+
+from pydantic import BaseModel
+from typing_extensions import runtime_checkable
+
+BaseModelT = TypeVar("BaseModelT", bound=BaseModel)
+T = TypeVar("T")
+
+
+@runtime_checkable
+class DataClassProto(Protocol):
+    """Protocol for dataclass types."""
+
+    @classmethod
+    def __dataclass_fields__(cls) -> Dict[str, Any]: ...
+
+
+# A config is a pydantic model or a dataclass instance.
+ConfigType = Union[BaseModel, DataClassProto]
+# Things that can be *resolved into* a config: a config type, a mapping of
+# fields, or a path/dotted-string pointing at one.
+OtherCfgType = Optional[
+    Union[Type[Union[DataClassProto, BaseModel]], Dict[str, Any], str, Path]
+]
+AllConfigType = Union[ConfigType, OtherCfgType]

cfgable-0.1.0/src/cfgable/_vendor.py

@@ -0,0 +1,19 @@
+"""Small vendored helpers, kept here to avoid extra runtime dependencies."""
+
+
+def get_in(keys, coll, default=None, no_default=False):
+    """Return ``coll[k0][k1][...]`` following the sequence ``keys``.
+
+    Vendored equivalent of ``toolz.dicttoolz.get_in``. On a missing key/index
+    (``KeyError``, ``IndexError``, ``TypeError``) return ``default`` — unless
+    ``no_default`` is set, in which case the original exception propagates.
+    """
+    try:
+        out = coll
+        for key in keys:
+            out = out[key]
+        return out
+    except (KeyError, IndexError, TypeError):
+        if no_default:
+            raise
+        return default