confkit 0.1.1__py3-none-any.whl

confkit/__init__.py

@@ -0,0 +1,37 @@
+"""Module that provides the main interface for the configurator package.
+
+It includes the Config class and various data types used for configuration values.
+"""
+
+from .config import Config
+from .data_types import (
+    BaseDataType,
+    Boolean,
+    Enum,
+    Float,
+    Integer,
+    IntEnum,
+    IntFlag,
+    NoneType,
+    Optional,
+    StrEnum,
+    String,
+)
+from .exceptions import InvalidConverterError, InvalidDefaultError
+
+__all__ = [
+    "BaseDataType",
+    "Boolean",
+    "Config",
+    "Enum",
+    "Float",
+    "IntEnum",
+    "IntFlag",
+    "Integer",
+    "InvalidConverterError",
+    "InvalidDefaultError",
+    "NoneType",
+    "Optional",
+    "StrEnum",
+    "String",
+]

confkit/config.py

@@ -0,0 +1,299 @@
+"""Module for a config descriptor.
+
+The Config descriptor is used to read and write config values from a ConfigParser object.
+It is used to create a descriptor for config values, preserving type information.
+It also provides a way to set default values and to set config values using decorators.
+"""
+from __future__ import annotations
+
+from functools import wraps
+from typing import TYPE_CHECKING, ClassVar, cast, overload
+
+from .data_types import BaseDataType, Boolean, Float, Integer, NoneType, Optional, String
+from .exceptions import InvalidConverterError, InvalidDefaultError
+from .sentinels import UNSET
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from configparser import ConfigParser
+    from pathlib import Path
+
+
+class Config[VT]:
+    """A descriptor for config values, preserving type information.
+
+    the ValueType (VT) is the type you want the config value to be.
+    """
+
+    validate_types: ClassVar[bool] = True # Validate that the converter returns the same type as the default value. (not strict)
+    write_on_edit: ClassVar[bool] = True # Write to the config file when updating a value.
+    optional: bool = False # if True, allows None as an extra type when validating types. (both instance and class variables.)
+
+    _parser: ConfigParser = UNSET
+    _file: Path = UNSET
+    _has_read_config: bool = False
+
+    if TYPE_CHECKING:
+        # Overloads for type checkers to understand the different settings of the Config descriptors.
+        @overload
+        def __init__(self: Config[str], default: str) -> None: ...
+        @overload
+        def __init__(self: Config[None], default: None) -> None: ...
+        @overload
+        def __init__(self: Config[bool], default: bool) -> None: ...  # noqa: FBT001
+        @overload
+        def __init__(self: Config[int], default: int) -> None: ...
+        @overload
+        def __init__(self: Config[float], default: float) -> None: ...
+        @overload
+        def __init__(self: Config[str | None], default: str, *, optional: bool) -> None: ...
+        @overload
+        def __init__(self: Config[None], default: None, *, optional: bool) -> None: ...
+        @overload
+        def __init__(self: Config[bool | None], default: bool, *, optional: bool) -> None: ...  # noqa: FBT001
+        @overload
+        def __init__(self: Config[int | None], default: int, *, optional: bool) -> None: ...
+        @overload
+        def __init__(self: Config[float | None], default: float, *, optional: bool) -> None: ...
+        @overload # Custom data type, like Enum's or custom class.
+        def __init__(self, default: BaseDataType[VT]) -> None: ...
+
+    # type Complains about the self and default overloads for None and str
+    # they are explicitly set for type checkers, the actual representation doesn't matter
+    # in runtime, as VT is allowed to be any type.
+    def __init__( # type: ignore[reportInconsistentOverload]
+        self,
+        default: VT | None | BaseDataType[VT] = UNSET,
+        *,
+        optional: bool = False,
+    ) -> None:
+        """Initialize the config descriptor with a default value.
+
+        Validate that parser and filepath are present.
+        """
+        self.optional = optional or Config.optional # Be truthy when either one is true.
+
+        if not self.optional and default is UNSET:
+            msg = "Default value cannot be None when optional is False."
+            raise InvalidDefaultError(msg)
+
+        self._initialize_data_type(default)
+        self._validate_init()
+        self._read_parser()
+
+    def _initialize_data_type(self, default: VT | None | BaseDataType[VT]) -> None:
+        """Initialize the data type based on the default value."""
+        if not self.optional and default is not None:
+            self._data_type = self._cast_data_type(default)
+        else:
+            self._data_type = self._cast_optional_data_type(default)
+
+    def _cast_optional_data_type(self, default: VT | None | BaseDataType[VT]) -> BaseDataType[VT | None]:
+        """Convert the default value to an Optional data type."""
+        if default is None:
+            return cast("BaseDataType[VT | None]", NoneType())
+        return Optional(self._cast_data_type(default))
+
+    def _cast_data_type(self, default: VT | BaseDataType[VT]) -> BaseDataType[VT]:
+        """Convert the default value to a BaseDataType."""
+        # We use Cast to shut up type checkers, as we know primitive types will be correct.
+        # If a custom type is passed, it should be a BaseDataType subclass, which already has the correct types.
+        match default:
+            case bool():
+                data_type = cast("BaseDataType[VT]", Boolean(default))
+            case None:
+                data_type = cast("BaseDataType[VT]", NoneType())
+            case int():
+                data_type = cast("BaseDataType[VT]", Integer(default))
+            case float():
+                data_type = cast("BaseDataType[VT]", Float(default))
+            case str():
+                data_type = cast("BaseDataType[VT]", String(default))
+            case BaseDataType():
+                data_type = default
+            case _:
+                msg = (
+                    f"Unsupported default value type: {type(default).__name__}. "
+                    "Use a BaseDataType subclass for custom types."
+                )
+                raise InvalidDefaultError(msg)
+        return data_type
+
+    def _read_parser(self) -> None:
+        """Ensure the parser has read the file at initialization. Avoids rewriting the file when settings are already set."""
+        if not self._has_read_config:
+            Config._parser.read(Config._file)
+            Config._has_read_config = True
+
+    def _validate_init(self) -> None:
+        """Validate the config descriptor, ensuring it's properly set up."""
+        self.validate_file()
+        self.validate_parser()
+
+    def convert(self, value: str) -> VT:
+        """Convert the value to the desired type using the given converter method."""
+        # Ignore the type errror of VT, type checkers don't like None as an option
+        # We handle it using the `optional` flag. so we can safely ignore it.
+        return self._data_type.convert(value) # type: ignore[reportReturnType]
+
+    @staticmethod
+    def set_parser(parser: ConfigParser) -> None:
+        """Set the parser for ALL descriptors."""
+        Config._parser = parser
+
+    @staticmethod
+    def set_file(file: Path) -> None:
+        """Set the file for ALL descriptors."""
+        Config._file = file
+
+    def validate_strict_type(self) -> None:
+        """Validate the type of the converter matches the desired type."""
+        if not Config.validate_types:
+            return
+        if self._data_type.convert is UNSET:
+            msg = "Converter is not set."
+            raise InvalidConverterError(msg)
+
+        config_value = Config._parser.get(self._section, self._setting)
+        converted_value = self.convert(config_value)
+        converted_type = type(converted_value)
+
+        if not self._data_type.validate():
+            msg = f"Invalid value for {self._section}.{self._setting}: {converted_value}"
+            raise InvalidConverterError(msg)
+
+        if self.optional and converted_type in (type(self._data_type.default), type(None)):
+            # Allow None or the same type as the default value to be returned by the converter when _optional is True.
+            return
+        if type(converted_value) is not type(self._data_type.default):
+            msg = f"Converter does not return the same type as the default value <{type(self._data_type.default)}>."
+            raise InvalidConverterError(msg)
+
+    def validate_file(self) -> None:
+        """Validate the config file."""
+        if Config._file is UNSET:
+            msg = f"Config file is not set. use {Config.__class__.__name__}.set_file to set it."
+            raise ValueError(msg)
+
+    def validate_parser(self) -> None:
+        """Validate the config parser."""
+        if Config._parser is UNSET:
+            msg = f"Config parser is not set. use {Config.__class__.__name__}.set_parser to set it."
+            raise ValueError(msg)
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        """Set the name of the attribute to the name of the descriptor."""
+        self.name = name
+        self._section = owner.__name__
+        self._setting = name
+        self._ensure_option()
+        self._original_value = Config._parser.get(self._section, self._setting) or self._data_type.default
+        self.private = f"_{self._section}_{self._setting}_{self.name}"
+
+    def _ensure_section(self) -> None:
+        """Ensure the section exists in the config file. Creates one if it doesn't exist."""
+        if not self._parser.has_section(self._section):
+            self._parser.add_section(self._section)
+
+    def _ensure_option(self) -> None:
+        """Ensure the option exists in the config file. Creates one if it doesn't exist."""
+        self._ensure_section()
+        if not self._parser.has_option(self._section, self._setting):
+            Config._set(self._section, self._setting, self._data_type.default)
+
+    def __get__(self, obj: object, obj_type: object) -> VT:
+        """Get the value of the attribute."""
+        # obj_type is the class in which the variable is defined
+        # so it can be different than type of VT
+        # but we don't need obj or it's type to get the value from config in our case.
+        self.validate_strict_type()
+        return self.convert(Config._parser.get(self._section, self._setting))
+
+    def __set__(self, obj: object, value: VT) -> None:
+        """Set the value of the attribute."""
+        Config._set(self._section, self._setting, value)
+        setattr(obj, self.private, value)
+
+    @staticmethod
+    def _sanitize_str(value: str) -> str:
+        """Escape the percent sign in the value."""
+        return value.replace("%", "%%")
+
+    @staticmethod
+    def _set(section: str, setting: str, value: VT) -> None:
+        """Set a config value, and write it to the file."""
+        if not Config._parser.has_section(section):
+            Config._parser.add_section(section)
+        sanitized_str = Config._sanitize_str(str(value))
+        Config._parser.set(section, setting, sanitized_str)
+        if Config.write_on_edit:
+            with Config._file.open("w") as f:
+                Config._parser.write(f)
+
+    @staticmethod
+    def set(section: str, setting: str, value: VT):  # noqa: ANN205
+        """Set a config value using this descriptor."""
+
+        def wrapper[F, **P](func: Callable[P, F]) -> Callable[P, F]:
+            @wraps(func)
+            def inner(*args: P.args, **kwargs: P.kwargs) -> F:
+                Config._set(section, setting, value)
+                return func(*args, **kwargs)
+
+            return inner
+        return wrapper
+
+    @staticmethod
+    def with_setting[OVT](setting: Config[OVT]):  # noqa: ANN205
+        """Insert a config value into **kwargs to a given method/function using this decorator."""
+        def wrapper[F, **P](func: Callable[P, F]) -> Callable[P, F]:
+            @wraps(func)
+            def inner(*args: P.args, **kwargs: P.kwargs) -> F:
+                kwargs[setting.name] = setting.convert(Config._parser.get(setting._section, setting._setting))
+                return func(*args, **kwargs)
+
+            return inner
+        return wrapper
+
+    @staticmethod
+    def as_kwarg(section: str, setting: str, name: str | None = None, default: VT = UNSET):  # noqa: ANN205
+        """Insert a config value into **kwargs to a given method/function using this descriptor.
+
+        Use kwarg.get(`name`) to get the value.
+        `name` is the name the kwarg gets if passed, if None, it will be the same as `setting`.
+        Section parameter is just for finding the config value.
+        """
+        if name is None:
+            name = setting
+        if default is UNSET and not Config._parser.has_option(section, setting):
+            msg = f"Config value {section=} {setting=} is not set. and no default value is given."
+            raise ValueError(msg)
+
+        def wrapper[F, **P](func: Callable[P, F]) -> Callable[P, F]:
+            @wraps(func)
+            def inner(*args: P.args, **kwargs: P.kwargs) -> F:
+                if default is not UNSET:
+                    Config._set_default(section, setting, default)
+                kwargs[name] = Config._parser.get(section, setting) # ty: ignore[call-non-callable]
+                return func(*args, **kwargs)
+
+            return inner
+        return wrapper
+
+    @staticmethod
+    def _set_default(section: str, setting: str, value: VT) -> None:
+        if Config._parser.get(section, setting, fallback=UNSET) is UNSET:
+            Config._set(section, setting, value)
+
+    @staticmethod
+    def default(section: str, setting: str, value: VT):  # noqa: ANN205
+        """Set a default config value if none are set yet using this descriptor."""
+
+        def wrapper[F, **P](func: Callable[P, F]) -> Callable[P, F]:
+            @wraps(func)
+            def inner(*args: P.args, **kwargs: P.kwargs) -> F:
+                Config._set_default(section, setting, value)
+                return func(*args, **kwargs)
+
+            return inner
+        return wrapper

confkit/data_types.py

@@ -0,0 +1,154 @@
+"""Module that contains the base data types used in the config system."""
+
+from __future__ import annotations
+
+import enum
+from abc import ABC, abstractmethod
+
+from .exceptions import InvalidConverterError
+
+
+class BaseDataType[T](ABC):
+    """Base class used for Config descriptors to define a data type."""
+
+    def __init__(self, default: T) -> None:
+        """Initialize the base data type."""
+        self.default = default
+        self.value = default
+
+    @abstractmethod
+    def convert(self, value: str) -> T:
+        """Convert a string value to the desired type."""
+
+    def validate(self) -> bool:
+        """Validate that the value matches the expected type."""
+        orig_bases: tuple[type, ...] | None = getattr(self.__class__, "__orig_bases__", None)
+
+        if not orig_bases:
+            msg = "No type information available for validation."
+            raise InvalidConverterError(msg)
+
+        # Extract type arguments from the generic base
+        for base in orig_bases:
+            if hasattr(base, "__args__"):
+                type_args = base.__args__
+                if type_args:
+                    for type_arg in type_args:
+                        if isinstance(self.value, type_arg):
+                            return True
+                    msg = f"Value {self.value} is not any of {type_args}."
+                    raise InvalidConverterError(msg)
+        msg = "This should not have raised. Report to the library maintainers with code: `DTBDT38`"
+        raise TypeError(msg)
+
+class Enum(BaseDataType[enum.Enum]):
+    """A config value that is an enum."""
+
+    def convert(self, value: str) -> enum.Enum:
+        """Convert a string value to an enum."""
+        parsed_enum_name = value.split(".")[-1]
+        return self.value.__class__[parsed_enum_name]
+
+class StrEnum(BaseDataType[enum.StrEnum]):
+    """A config value that is an enum."""
+
+    def convert(self, value: str) -> enum.StrEnum:
+        """Convert a string value to an enum."""
+        return self.value.__class__(value)
+
+class IntEnum(BaseDataType[enum.IntEnum]):
+    """A config value that is an enum."""
+
+    def convert(self, value: str) -> enum.IntEnum:
+        """Convert a string value to an enum."""
+        return self.value.__class__(int(value))
+
+class IntFlag(BaseDataType[enum.IntFlag]):
+    """A config value that is an enum."""
+
+    def convert(self, value: str) -> enum.IntFlag:
+        """Convert a string value to an enum."""
+        return self.value.__class__(int(value))
+
+class NoneType(BaseDataType[None]):
+    """A config value that is None."""
+
+    def __init__(self) -> None:
+        """Initialize the NoneType data type."""
+        super().__init__(None)
+
+    def convert(self, value: str) -> None:
+        """Convert a string value to None."""
+        if value.lower().strip() in {"none", "null", "nil", ""}:
+            return
+        msg = f"Cannot convert {value} to None."
+        raise ValueError(msg)
+
+
+class String(BaseDataType[str]):
+    """A config value that is a string."""
+
+    def convert(self, value: str) -> str:
+        """Convert a string value to a string."""
+        return value
+
+
+class Float(BaseDataType[float]):
+    """A config value that is a float."""
+
+    def convert(self, value: str) -> float:
+        """Convert a string value to a float."""
+        return float(value)
+
+
+class Boolean(BaseDataType[bool]):
+    """A config value that is a boolean."""
+
+    def convert(self, value: str) -> bool:
+        """Convert a string value to a boolean."""
+        if value.lower() in {"true", "1", "yes"}:
+            return True
+        if value.lower() in {"false", "0", "no"}:
+            return False
+        msg = f"Cannot convert {value} to boolean."
+        raise ValueError(msg)
+
+
+class Integer(BaseDataType[int]):
+    """A config value that is an integer."""
+
+    def convert(self, value: str) -> int:
+        """Convert a string value to an integer."""
+        return int(value)
+
+class Optional[T](BaseDataType[T | None]):
+    """A config value that is optional, can be None or a specific type."""
+
+    _none_type = NoneType()
+
+    def __init__(self, data_type: BaseDataType[T]) -> None:
+        """Initialize the optional data type. Wrapping the provided data type."""
+        self._data_type = data_type
+
+    @property
+    def default(self) -> T | None:
+        """Get the default value of the wrapped data type."""
+        return self._data_type.default
+
+    @property
+    def value(self) -> T | None:
+        """Get the current value of the wrapped data type."""
+        return self._data_type.value
+
+    def convert(self, value: str) -> T | None:
+        """Convert a string value to the optional type."""
+        try:
+            return self._none_type.convert(value)
+        except ValueError:
+            return self._data_type.convert(value)
+
+    def validate(self) -> bool:
+        """Validate that the value is of the wrapped data type or None."""
+        if self._data_type.value is None:
+            return True
+        return self._data_type.validate()

confkit/exceptions.py

@@ -0,0 +1,8 @@
+"""Module for custom exceptions used in the configurator package."""
+
+class InvalidDefaultError(ValueError):
+    """Raised when the default value is not set or invalid."""
+
+
+class InvalidConverterError(ValueError):
+    """Raised when the converter is not set or invalid."""

confkit/sentinels.py

@@ -0,0 +1,21 @@
+"""Private sentinel for missing values."""
+
+from typing import Any
+
+
+class _MissingSentinel:
+    __slots__ = ()
+
+    def __eq__(self, other: object) -> bool:
+        return False
+
+    def __bool__(self) -> bool:
+        return False
+
+    def __hash__(self) -> int:
+        return 0
+
+    def __repr__(self) -> str:
+        return "MISSING"
+
+UNSET: Any = _MissingSentinel()

confkit-0.1.1.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: confkit
+Version: 0.1.1
+Summary: Lightweight and Easy to use configuration manager for Python projects
+Author-email: HEROgold <martijnwieringa28@gmail.com>
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# confkit
+
+[![Test](https://github.com/HEROgold/confkit/actions/workflows/test.yml/badge.svg)](https://github.com/HEROgold/confkit/actions/workflows/test.yml)
+
+Type-safe configuration manager for Python projects using descriptors and ConfigParser.
+
+## What is it?
+
+confkit is a Python library that provides type-safe configuration management with automatic type conversion and validation.
+It uses descriptors to define configuration values as class attributes that automatically read from and write to INI files.
+
+## What does it do?
+
+- Type-safe configuration with automatic type conversion
+- Automatic INI file management
+- Default value handling with file persistence
+- Optional value support
+- Enum support (Enum, StrEnum, IntEnum, IntFlag)
+- Method decorators for injecting configuration values
+- Runtime type validation
+
+## How to use it?
+
+### Setup
+
+```python
+from configparser import ConfigParser
+from pathlib import Path
+from confkit import Config
+
+parser = ConfigParser()
+Config.set_parser(parser)
+Config.set_file(Path("config.ini"))
+```
+
+### Basic Usage
+
+- Note: imports have been left out. see [examples/basic.py](basic.py) for the entire example.
+
+```python
+class AppConfig:
+    debug = Config(False)
+    port = Config(8080)
+    host = Config("localhost")
+    timeout = Config(30.5)
+    api_key = Config("", optional=True)
+
+config = AppConfig()
+print(config.debug)  # False
+config.port = 9000   # Automatically saves to config.ini if write_on_edit is true (default).
+```
+
+### Enums and Custom Types
+
+- Note: imports have been left out. see [examples/enums.py](enums.py) for the entire example.
+
+```python
+class LogLevel(StrEnum):
+    DEBUG = "debug"
+    INFO = "info"
+    ERROR = "error"
+
+class ServerConfig:
+    log_level = Config(ConfigEnum(LogLevel.INFO))
+    db_url = Config(String("sqlite:///app.db"))
+    fallback_level = Config(Optional(ConfigEnum(LogLevel.ERROR)))
+
+config = ServerConfig()
+config.log_level = LogLevel.DEBUG  # Type-safe
+```
+
+### Method Decorators
+
+- Note: imports have been left out. see [examples/decorators.py](decorators.py) for the entire example.
+
+```python
+class ServiceConfig:
+    retry_count = Config(3)
+    timeout = Config(30)
+
+    @Config.with_setting(retry_count)
+    def process(self, data, **kwargs):
+        retries = kwargs.get('retry_count')
+        return f"Processing with {retries} retries"
+
+    @Config.as_kwarg("ServiceConfig", "timeout", "request_timeout", 60)
+    def request(self, url, **kwargs):
+        timeout = kwargs.get('request_timeout')
+        return f"Request timeout: {timeout}s"
+
+service = ServiceConfig()
+result = service.process("data")  # Uses current retry_count
+```
+
+### Configuration File
+
+Generated INI file structure see [examples/config.ini](config.ini) for the entire example.:
+
+```ini
+[AppConfig]
+debug = False
+port = 9000
+host = localhost
+timeout = 30.5
+api_key = 
+
+[ServiceConfig]
+retry_count = 3
+timeout = 30
+
+[ServerConfig]
+log_level = debug
+db_url = sqlite:///app.db
+fallback_level = error
+```
+
+## How to contribute?
+
+1. Fork the repository and clone locally
+2. Install dependencies: `uv sync --group test`
+3. Run tests: `pytest .`
+4. Run linting: `ruff check .`
+5. Make changes following existing patterns
+6. Add tests for new functionality
+7. Submit a pull request
+
+### Development
+
+```bash
+git clone https://github.com/HEROgold/confkit.git
+cd confkit
+uv sync --group test
+pytest .
+ruff check .
+```

confkit-0.1.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+confkit/__init__.py,sha256=H4eKKhRm0joSURblV_hN5JFBJkeUsshnN-tiifuNnlA,679
+confkit/config.py,sha256=WiXYbsew1APIFYBYN3YhWMTgYO3yh1m1FV_6tTy9zdM,13230
+confkit/data_types.py,sha256=CQepO7F-pTa169rZBHAqfrdwHX8rs3ggGGgRUXyESIg,5026
+confkit/exceptions.py,sha256=BSDW9I-DzHDBnb_uCL_p5tsqa3cR0ULNI4VybnUv_CU,274
+confkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+confkit/sentinels.py,sha256=qiqeYxW7Mavhedd9RaVHqNn71vok-x9PJBlbYxnmcRY,372
+confkit-0.1.1.dist-info/METADATA,sha256=2n2ro_5bf5JJPHFkVjkMA9egmscMUSgVJf7vOkbpXp8,3640
+confkit-0.1.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+confkit-0.1.1.dist-info/RECORD,,

confkit-0.1.1.dist-info/WHEEL

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