cfgable 0.1.0__py3-none-any.whl

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/_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/_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

cfgable/core.py

@@ -0,0 +1,393 @@
+from abc import ABCMeta, abstractmethod
+from dataclasses import asdict, replace, is_dataclass
+from logging import getLogger
+from typing import (
+    Union,
+    Optional,
+    Type,
+    Dict,
+    Any,
+    Literal,
+    Set,
+    List,
+    final,
+    get_type_hints,
+)
+from collections.abc import Mapping, Callable
+from typing_extensions import get_args, Self
+from pydantic import BaseModel, TypeAdapter
+from pydantic_yaml import to_yaml_file
+from pathlib import Path
+from functools import cache
+from weakref import WeakSet
+from ._typing import (
+    DataClassProto,  # noqa: F401  re-exported for backward-compat shims
+    ConfigType,
+    AllConfigType,
+    OtherCfgType,  # noqa: F401  re-exported for backward-compat shims
+)
+from .reflection import import_string, get_fully_qualified_class_name
+from copy import copy, deepcopy
+from ._vendor import get_in
+import inspect
+import yaml
+import json
+import pickle
+
+
+class NoConfig(BaseModel, frozen=True):
+    """A placeholder config class indicating no configuration is needed."""
+
+
+class InitConfigMeta(type):
+    def __call__(cls, config: AllConfigType = None, **kwargs):
+        error_msg = """
+        If not provided as an arg, `config` must be annotated as a subclass of `ConfigType` 
+        either in the `__init__` method or at the class scope. If a class truly does not 
+        require any configuration, you can mark the type as `None` at the class scope."""
+        if isinstance(config, (str, Path)):
+            config = cls.config_from_file(config)
+        config_type = (
+            config
+            if isinstance(config, type)
+            else cls.resolve_config_type(cls)
+            if (config is None or isinstance(config, Mapping))
+            else type(config)
+        )
+        cls_path = None
+        if isinstance(config, Mapping):
+            cls_path = config.pop("_target_", cls_path)
+        cls_path = kwargs.pop("_target_", cls_path)
+        if config_type is None:
+            # try to get from _target_
+            if cls_path is not None:
+                config_type = import_string(cls_path)
+        # TODO: it is better to support more flexible config types
+        # e.g. dict, etc.
+        if not cls._check_config_type(config_type):
+            raise TypeError(f"{cls}" + error_msg + f" Got {config_type} instead.")
+        if not issubclass(config_type, BaseModel):
+            adapter = TypeAdapter(config_type)
+        if isinstance(config, Mapping):
+            # if (
+            #     get_fully_qualified_class_name(config)
+            #     == "omegaconf.dictconfig.DictConfig"
+            # ):
+            #     from omegaconf import OmegaConf
+
+            #     config = OmegaConf.to_object(config)
+            config.update(kwargs)
+            config = config_type(**config)
+        elif config is None or isinstance(config, type):
+            if issubclass(config_type, BaseModel):
+                config = config_type(**kwargs)
+            else:
+                config = adapter.validate_python(kwargs)
+        elif kwargs:  # mainly used by yaml config, e.g. hydra
+            if isinstance(config, BaseModel):
+                config = config.model_copy(update=kwargs)
+                # re-validate
+                config = config.model_validate(config.model_dump(warnings="none"))
+                extra = kwargs.keys() - config_type.model_fields.keys()
+                if extra:
+                    cls.get_logger().warning(
+                        f"Extra fields {extra} found in config, which will be ignored."
+                    )
+            else:  # dataclass
+                config = replace(config, **kwargs)
+                config = adapter.validate_python(asdict(config))
+        # NOTE: since there may be arbitrary instances in the config,
+        # we should not deep copy the config here to avoid potential issues.
+        # if isinstance(config, BaseModel):
+        #     cfg_copy = config.model_copy(deep=True)
+        # else:
+        #     cfg_copy = deepcopy(config)
+        instance: "InitConfigMixinBasis" = super().__call__(config)
+        # instance.__config = cfg_copy
+        if not hasattr(instance, "config"):
+            instance.config = config
+        instance.config_post_init()
+        return instance
+
+    @staticmethod
+    def _check_config_type(config_type: Type) -> bool:
+        return isinstance(config_type, type) and issubclass(
+            config_type, get_args(ConfigType)
+        )
+
+    @classmethod
+    def get_logger(cls):
+        return getLogger(cls.__name__)
+
+    @staticmethod
+    @cache
+    def resolve_config_type(cls) -> Optional[Type]:
+        cfg_type = InitConfigMeta.get_annotation(cls, "config")
+        if cfg_type in (None, ...) or (getattr(cls, "config", object) in (None, ...)):
+            cfg_type = NoConfig
+        elif cfg_type is object:
+            cfg_type = get_type_hints(cls.__init__).get("config", None)
+        return cfg_type
+
+    @staticmethod
+    @cache
+    def get_annotation(cls, name: str) -> Optional[Any]:
+        return getattr(cls, "__annotations__", {}).get(name, object)
+
+    @staticmethod
+    def config_from_file(path: Union[str, Path]) -> AllConfigType:
+        path = Path(path)
+        if not path.exists():
+            raise FileNotFoundError(f"Config file {path} not found.")
+        if path.suffix == ".pkl":
+            with open(path, "rb") as f:
+                config = pickle.load(f)
+        else:  # yaml or json
+            with open(path, "r") as f:
+                config = yaml.safe_load(f)
+        return config
+
+
+class InitConfigABCMeta(InitConfigMeta, ABCMeta):
+    """A metaclass that combines InitConfigMeta and ABCMeta."""
+
+
+class InitConfigMixinBasis:
+    """A mixin class for initializing with a config."""
+
+    def __init__(self, config: ConfigType) -> None:
+        self.config = config
+        """Initialize with a config. It is only used for type hinting in the current class;
+        subclasses can override it at will. Note that you should try to avoid directly modifying
+        the config variable internally, as this may lead to potential problems, such as inconsistent
+        behavior when the same config variable is used to instantiate the class multiple times. Unless
+        there is a special need, such as a class that might be specifically designed to modify external
+        configurations, it is best to update the copied variables and then reassign them to the instance.
+        Furthermore, for maximum security and faster value retrieval, the configuration class should be
+        set to frozen unless there is a clear need for modification. Conversely, due to this security
+        mechanism, in complex configuration chains, the original external configuration may not accurately
+        reflect the internal configuration of the instance. Therefore, when a configuration needs to be
+        referenced externally, this consistency issue should be considered. However, this should not be
+        seen as a drawback of this security mechanism, as it is an issue that must be considered in all
+        circumstances. On the contrary, it forces developers to make more proactive and reasonable designs.
+        It is undeniable that shallow copy operations incur additional time consumption, but this is usually
+        negligible."""
+
+    @classmethod
+    def get_logger(cls):
+        return getLogger(cls.__name__)
+
+    def dump(self, mode: Literal["python", "json"] = "python") -> Dict[str, Any]:
+        """Dump the config to a dictionary.
+        Args:
+            mode: The mode to dump the config. "python" for standard dict, "json" (only applicable when the config is the `BaseModel` of pydantic) for JSON serializable dict.
+        Returns:
+            A dictionary representing the config with a "_target_" key indicating the class path.
+        """
+        if isinstance(self.config, BaseModel):
+            config = self.config.model_dump(mode=mode)
+        else:  # dataclass
+            config = asdict(self.config)
+        cls = self.__class__
+        config["_target_"] = f"{cls.__module__}.{cls.__qualname__}"
+        return config
+
+    def save_config(
+        self,
+        path: Union[str, Path],
+        mode: Optional[Literal["yaml", "json", "pickle"]] = None,
+    ) -> None:
+        """Save the config to a yaml file.
+        Args:
+            path: The file path to save the config.
+            mode: The mode to save the config. If None, it will be inferred from the file extension.
+        """
+        with open(path, "w") as f:
+            mode = Path(path).suffix.removeprefix(".") if mode is None else mode
+            if mode in ("yaml", "yml"):
+                if isinstance(self.config, BaseModel):
+                    try:
+                        to_yaml_file(f, self.config, add_comments=True)
+                    except TypeError:
+                        # Some pydantic-yaml versions don't accept `add_comments`
+                        # (they forward it into model_dump_json). Fall back to a
+                        # plain dump rather than failing the save.
+                        to_yaml_file(f, self.config)
+                else:  # dataclass
+                    yaml.dump(asdict(self.config), f)
+            elif mode == "json":
+                json.dump(self.dump(mode="json"), f, indent=4)
+            elif mode in ("pickle", "pkl"):
+                pickle.dump(self.config, f)
+            else:
+                raise ValueError(f"Unsupported mode: {mode}")
+
+    def config_post_init(self) -> None:
+        """A hook to be called after the config is set."""
+
+    @final
+    def copy(
+        self, update: Optional[Mapping[str, Any]] = None, deep: bool = False
+    ) -> Self:
+        """Create a copy of the current instance with the same config."""
+        if isinstance(self.config, BaseModel):
+            config = self.config.model_copy(deep=deep, update=update)
+        else:
+            if update:
+                raise NotImplementedError(
+                    "Update is only supported for BaseModel config."
+                )
+            method = copy if not deep else deepcopy
+            config = method(self.config)
+        return self.__class__(config)
+
+    def __repr__(self):
+        return f"{self.__module__}.{self.__class__.__qualname__}"
+
+
+class InitConfigMixin(InitConfigMixinBasis, metaclass=InitConfigMeta):
+    """Mixin class for initializing with a config."""
+
+
+class InitConfigABCMixin(InitConfigMixinBasis, metaclass=InitConfigABCMeta):
+    """Mixin class for initializing with a config and supporting abstract methods."""
+
+
+class ConfigurableBasis(InitConfigABCMixin):
+    """A basis class for easy configuring."""
+
+    __instances: Set[Self] = WeakSet()
+
+    def config_post_init(self):
+        self._configured = False
+        self.__class__.__instances.add(self)
+
+    @final
+    def configure(self) -> bool:
+        if self._configured:
+            raise RuntimeError("Already configured")
+        itf_type = InitConfigMeta.get_annotation(self.__class__, "interface")
+        self.interface = self._create_interface(itf_type)
+        self._configured = self.on_configure()
+        return self._configured
+
+    @abstractmethod
+    def on_configure(self) -> bool:
+        """Callback to be called when configuring"""
+        raise NotImplementedError
+
+    @final
+    @property
+    def configured(self) -> bool:
+        return self._configured
+
+    @classmethod
+    def all_configure(cls) -> bool:
+        """Configure all instances of this class and its subclasses."""
+        for instance in cls.__instances:
+            if not instance.configured:
+                if not instance.configure():
+                    cls.get_logger().error(f"Failed to configure instance: {instance}")
+                    return False
+        return True
+
+    def _create_interface(self, class_type: Optional[Type]):
+        """Create the interface instance based on the config and the class type annotation.
+        The subclasses can override this method if needed.
+        """
+        if class_type is None:
+            return None
+        sig = inspect.signature(class_type)
+        if "config" in sig.parameters.keys():
+            interface = class_type(config=self.config)
+        else:
+            # convert the first level config to dict
+            if isinstance(self.config, BaseModel):
+                # dict(self.config) has some bugs
+                # so we use the following way
+                cfg_dict = {
+                    k: getattr(self.config, k)
+                    for k in self.config.__class__.model_fields.keys()
+                }
+            else:  # dataclass
+                # TODO: error when using nested dataclass
+                cfg_dict = asdict(self.config)
+            com_keys = cfg_dict.keys() & sig.parameters.keys()
+            interface = class_type(**{key: cfg_dict[key] for key in com_keys})
+        return interface
+
+
+def dump_omegaconf(obj: Any) -> Dict[str, Any]:
+    """Dump an omegaconf object to a dictionary.
+    Args:
+        obj: The omegaconf object to dump.
+    Returns:
+        A dictionary representing the omegaconf object.
+    Raises:
+        TypeError: If the object is not an omegaconf object.
+    """
+    from omegaconf import OmegaConf
+
+    if get_fully_qualified_class_name(obj) in {
+        "omegaconf.dictconfig.DictConfig",
+        "omegaconf.listconfig.ListConfig",
+    }:
+        return OmegaConf.to_object(obj)
+    raise TypeError("Not an omegaconf object.")
+
+
+def dump_or_repr(
+    obj: Union[Any, ConfigurableBasis], handler: Optional[Callable] = None
+) -> Union[Dict[str, Any], str]:
+    """Dump the config if the object is a ConfigurableBasis, otherwise return the repr.
+    Args:
+        obj: The object to dump or repr.
+    Returns:
+        A dictionary representing the config or the repr string.
+    """
+    if callable(getattr(obj, "dump", None)):
+        try:
+            return obj.dump()
+        except Exception as e:
+            getLogger(f"{dump_or_repr.__name__}").error(f"Failed to dump config: {e}")
+    config = getattr(obj, "config", None)
+    if config is not None:
+        if isinstance(config, BaseModel):
+            return config.model_dump()
+        elif is_dataclass(config):
+            return asdict(config)
+        elif isinstance(config, dict):
+            return config
+    try:
+        return dump_omegaconf(obj)
+    except TypeError:
+        if handler is not None:
+            return handler(obj)
+        return repr(obj)
+
+
+def fetch_config(
+    target: Union[Path, str, Mapping],
+    keys: Union[List[str], str] = "",
+    default=None,
+    no_default: bool = True,
+) -> Any:
+    """Fetch the config from a target mapping or a yaml file.
+    Args:
+        target: The target mapping or file path.
+        keys: The keys or a dot-separated key to the config. If empty, return the whole config.
+        default: The default value if the key is not found.
+        no_default: Whether to raise an error if the key is not found and no default is provided.
+    Returns:
+        The config object.
+    """
+    if isinstance(target, (str, Path)):
+        with open(target, "r") as f:
+            data = yaml.safe_load(f)
+    else:
+        data = target
+    if not keys:
+        return data
+    if isinstance(keys, str):
+        keys = keys.split(".")
+    return get_in(keys, data, default, no_default)

cfgable/enums.py

@@ -0,0 +1,44 @@
+from enum import Enum
+
+
+class ReprEnum(Enum):
+    """
+    Only changes the repr(), leaving str() and format() to the mixed-in type.
+    """
+
+
+class StrEnum(str, ReprEnum):
+    """
+    Enum where members are also (and must be) strings
+    """
+
+    def __new__(cls, *values):
+        "values must already be of type `str`"
+        if len(values) > 3:
+            raise TypeError(f"too many arguments for str(): {values!r}")
+        if len(values) == 1:
+            # it must be a string
+            if not isinstance(values[0], str):
+                raise TypeError(f"{values[0]!r} is not a string")
+        if len(values) >= 2:
+            # check that encoding argument is a string
+            if not isinstance(values[1], str):
+                raise TypeError(f"encoding must be a string, not {values[1]!r}")
+        if len(values) == 3:
+            # check that errors argument is a string
+            if not isinstance(values[2], str):
+                raise TypeError("errors must be a string, not %r" % (values[2]))
+        value = str(*values)
+        member = str.__new__(cls, value)
+        member._value_ = value
+        return member
+
+    @staticmethod
+    def _generate_next_value_(name, start, count, last_values):
+        """
+        Return the lower-cased version of the member name.
+        """
+        return name.lower()
+
+    def __str__(self):
+        return self.value

cfgable/frozen.py

@@ -0,0 +1,62 @@
+"""Helpers for mutating otherwise-frozen pydantic models in a controlled way.
+
+Frozen configs are the default in this framework (a component should not rewrite
+the settings it was handed). Occasionally a component genuinely needs to update a
+frozen config — e.g. it is specifically designed to derive and reassign values.
+``ForceSetAttr`` / ``force_set_attr`` make that explicit and localized rather than
+dropping ``frozen`` altogether.
+"""
+
+from functools import wraps
+from typing import Any, Generic
+
+from pydantic import BaseModel
+
+from ._typing import BaseModelT
+
+
+def validate_field(obj: BaseModel, name: str, value: Any):
+    """Validate a field value using the pydantic model's assignment validator."""
+    obj.__pydantic_validator__.validate_assignment(obj, name, value)
+
+
+class ForceSetAttr(Generic[BaseModelT]):
+    """Context manager to temporarily allow setting attributes on frozen models."""
+
+    def __init__(self, obj: BaseModelT):
+        if not isinstance(obj, BaseModel):
+            raise TypeError("Only Pydantic BaseModel instances are supported.")
+        self._obj = obj
+
+    def __enter__(self) -> BaseModelT:
+        self._original_setattr = self._obj.__class__.__setattr__
+        self._obj.__class__.__setattr__ = self._setattr
+        return self._obj
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self._obj.__class__.__setattr__ = self._original_setattr
+
+    def _setattr(self, name, value):
+        obj = self._obj
+        config = obj.model_config
+        if config.get("frozen", False):
+            if config.get("validate_assignment", False):
+                validate_field(obj, name, value)
+            else:
+                object.__setattr__(obj, name, value)
+        else:
+            setattr(obj, name, value)
+
+
+def force_set_attr(method):
+    """Decorator to force attribute setting on frozen pydantic models."""
+
+    @wraps(method)
+    def wrapper(self, *args, **kwargs):
+        with ForceSetAttr(self):
+            return method(self, *args, **kwargs)
+
+    return wrapper
+
+
+force_validate_field = force_set_attr(validate_field)

cfgable/hydra_utils.py

@@ -0,0 +1,67 @@
+"""Optional Hydra bridge. Requires the ``[hydra]`` extra (hydra-core + omegaconf).
+
+Importing this module pulls in hydra/omegaconf, so it is deliberately NOT imported
+by ``cfgable/__init__.py`` — import it explicitly:
+``from cfgable.hydra_utils import init_hydra_config``.
+"""
+
+from __future__ import annotations
+
+import hydra
+import os.path as osp
+from omegaconf import DictConfig
+from typing import Optional
+from pathlib import Path
+
+
+def relative_path_between(path1: Path, path2: Path) -> Path:
+    """Returns path1 relative to path2."""
+    path1 = Path(path1).absolute()
+    path2 = Path(path2).absolute()
+    try:
+        return path1.relative_to(path2)
+    except ValueError:  # most likely because path1 is not a subpath of path2
+        common_parts = Path(osp.commonpath([path1, path2])).parts
+        return Path(
+            "/".join(
+                [".."] * (len(path2.parts) - len(common_parts))
+                + list(path1.parts[len(common_parts) :])
+            )
+        )
+
+
+def init_hydra_config(
+    config_path: str, overrides: Optional[list[str]] = None
+) -> DictConfig:
+    """Initialize a Hydra config given only the path to the relevant config file.
+
+    For config resolution, it is assumed that the config file's parent is the Hydra config dir.
+    """
+    # TODO(alexander-soare): Resolve configs without Hydra initialization.
+    hydra.core.global_hydra.GlobalHydra.instance().clear()
+    # Hydra needs a path relative to this file.
+    hydra.initialize(
+        str(
+            relative_path_between(
+                Path(config_path).absolute().parent, Path(__file__).absolute().parent
+            )
+        ),
+        version_base="1.2",
+    )
+    cfg = hydra.compose(Path(config_path).stem, overrides)
+    return cfg
+
+
+def hydra_instance(cfg: DictConfig):
+    return hydra.utils.instantiate(cfg)
+
+
+def hydra_instance_from_config_path(config_path: str, params: dict = None):
+    config = init_hydra_config(config_path)
+    if params:
+        config.update(params)
+    return hydra_instance(config)
+
+
+def hydra_instance_from_dict(config: dict):
+    return hydra_instance(DictConfig(config))

cfgable/reflection.py

@@ -0,0 +1,29 @@
+"""Class/string reflection helpers used by the cfgable framework."""
+
+from inspect import isclass
+from typing import Any, Type, Union
+
+from pydantic import ImportString, validate_call
+
+from ._typing import T
+
+
+def get_fully_qualified_class_name(obj_or_cls) -> str:
+    """Return ``"module.QualName"`` for a class or an instance."""
+    if isinstance(obj_or_cls, type):
+        cls = obj_or_cls
+    else:
+        cls = type(obj_or_cls)
+    return f"{cls.__module__}.{cls.__qualname__}"
+
+
+def get_full_class_name(obj: Union[Any, Type]) -> str:
+    """Return ``"module.QualName"`` for a class or an instance."""
+    cls = obj if isclass(obj) else obj.__class__
+    return f"{cls.__module__}.{cls.__qualname__}"
+
+
+@validate_call
+def import_string(import_path: ImportString[T]) -> T:
+    """Import and return the object at a dotted path (validated by pydantic)."""
+    return import_path

cfgable-0.1.0.dist-info/METADATA

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

@@ -0,0 +1,12 @@
+cfgable/__init__.py,sha256=5xqkTfc6N736oSNJrEDigjM6hdKDvGbOhaNaKOb8H0U,1935
+cfgable/_typing.py,sha256=tlwb39Uqx5rAuijMXHzlb_8ILnzdEr9XrrCGdTzv8dk,855
+cfgable/_vendor.py,sha256=2WP0bQI8G7F96mX4AZuRvFbJqIWWA5cG9lSX075AwM8,656
+cfgable/core.py,sha256=Kv89PEa35YM72CUi7hljG-MWxLV8czJH2GH-aDy-HiU,15285
+cfgable/enums.py,sha256=gvbWZL2MqLRMRNeA1dbNGmTZ42QUnKhGV1kO4o7qEs0,1387
+cfgable/frozen.py,sha256=OUPek9XLeTBkJ4XEhNSy-GtfIEOHnxrLt7moWcV6thA,2087
+cfgable/hydra_utils.py,sha256=rOgpf7PK2L_lFjS8qLUoHeuhTMcgPsp3Zm-Oy2htpn4,2126
+cfgable/reflection.py,sha256=xMmFoAAiE5zcYwq90aak7hTW-57cW6hkaSAOJUH-nX8,883
+cfgable-0.1.0.dist-info/METADATA,sha256=lVsUTydh_rucrMhf2eNsx9erpEViYgnMZsQGrluhsf4,4676
+cfgable-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+cfgable-0.1.0.dist-info/licenses/LICENSE,sha256=IK18Ynsk1Qfz9vu19VmMNNoce7f61SRRwrZA48PbOGc,1064
+cfgable-0.1.0.dist-info/RECORD,,

cfgable-0.1.0.dist-info/WHEEL

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

cfgable-0.1.0.dist-info/licenses/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.