confkit 0.10.0__py3-none-any.whl

confkit/__init__.py

@@ -0,0 +1,59 @@
+"""Module that provides the main interface for the confkit package.
+
+It includes the Config class and various data types used for configuration values.
+"""
+
+from .config import Config
+from .data_types import (
+    BaseDataType,
+    Binary,
+    Boolean,
+    Date,
+    DateTime,
+    Dict,
+    Enum,
+    Float,
+    Hex,
+    Integer,
+    IntEnum,
+    IntFlag,
+    List,
+    NoneType,
+    Octal,
+    Optional,
+    Set,
+    StrEnum,
+    String,
+    Time,
+    TimeDelta,
+    Tuple,
+)
+from .exceptions import InvalidConverterError, InvalidDefaultError
+
+__all__ = [
+    "BaseDataType",
+    "Binary",
+    "Boolean",
+    "Config",
+    "Date",
+    "DateTime",
+    "Dict",
+    "Enum",
+    "Float",
+    "Hex",
+    "IntEnum",
+    "IntFlag",
+    "Integer",
+    "InvalidConverterError",
+    "InvalidDefaultError",
+    "List",
+    "NoneType",
+    "Octal",
+    "Optional",
+    "Set",
+    "StrEnum",
+    "String",
+    "Time",
+    "TimeDelta",
+    "Tuple",
+]

confkit/config.py

@@ -0,0 +1,325 @@
+"""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
+
+import warnings
+from functools import wraps
+from types import NoneType
+from typing import TYPE_CHECKING, Any, ClassVar, Generic, Literal, ParamSpec, TypeVar, overload
+
+from .data_types import BaseDataType, Optional
+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
+
+# Type variables for Python 3.10+ (pre-PEP 695) compatibility
+VT = TypeVar("VT")
+OVT = TypeVar("OVT")  # Separate TypeVar for nested generic to avoid scope collision
+F = TypeVar("F")
+P = ParamSpec("P")
+
+class Config(Generic[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 # Custom data type, like Enum's or custom class.
+        def __init__(self, default: BaseDataType[VT]) -> None: ...
+        @overload
+        def __init__(self, default: VT) -> None: ...
+        # Specify the states of optional explicitly for type checkers.
+        @overload
+        def __init__(self: Config[VT], default: VT, *, optional: Literal[False]) -> None: ... # pyright: ignore[reportInvalidTypeVarUse]
+        @overload
+        def __init__(self: Config[VT], default: BaseDataType[VT], *, optional: Literal[False]) -> None: ... # pyright: ignore[reportInvalidTypeVarUse]
+        @overload
+        def __init__(self: Config[VT | None], default: VT, *, optional: Literal[True]) -> None: ... # pyright: ignore[reportInvalidTypeVarUse]
+        @overload
+        def __init__(self: Config[VT | None], default: BaseDataType[VT], *, optional: Literal[True]) -> None: ... # pyright: ignore[reportInvalidTypeVarUse]
+
+    # 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.
+        """
+        cls = self.__class__
+        self.optional = optional or cls.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 __init_subclass__(cls) -> None:
+        """Allow for multiple config files/parsers without conflicts."""
+        super().__init_subclass__()
+
+        parent = cls._find_parent()
+
+        cls.validate_types = parent.validate_types
+        cls.write_on_edit = parent.write_on_edit
+        cls._parser = parent._parser  # noqa: SLF001
+        cls._file = parent._file  # noqa: SLF001
+        cls._has_read_config = parent._has_read_config  # noqa: SLF001
+
+    @classmethod
+    def _find_parent(cls) -> type[Config[Any]]:
+        for base in cls.__bases__:
+            if issubclass(base, Config):
+                parent = base
+                break
+        else:
+            parent = Config
+        return parent
+
+    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 = BaseDataType[VT].cast(default)
+        else:
+            self._data_type = BaseDataType[VT].cast_optional(default)
+
+    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:
+            self._parser.read(self._file)
+            self._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 error of VT, type checkers don't like None as an option
+        # We handle it using the `optional` flag, or using Optional DataType. so we can safely ignore it.
+        return self._data_type.convert(value) # type: ignore[reportReturnType]
+
+    @staticmethod
+    def _warn_base_class_usage() -> None:
+        """Warn users that setting parser/file on the base class can lead to unexpected behavior."""
+        warnings.warn("<Config> is the base class. Subclass <Config> to avoid unexpected behavior.", stacklevel=2)
+
+    @classmethod
+    def set_parser(cls, parser: ConfigParser) -> None:
+        """Set the parser for ALL descriptors."""
+        if cls is Config:
+            # Warn users that setting this value on the base class can lead to unexpected behavoir.
+            # Tell the user to subclass <Config> first.
+            cls._warn_base_class_usage()
+        cls._parser = parser
+
+    @classmethod
+    def set_file(cls, file: Path) -> None:
+        """Set the file for ALL descriptors."""
+        if cls is Config:
+            # Warn users that setting this value on the base class can lead to unexpected behavoir.
+            # Tell the user to subclass <Config> first.
+            cls._warn_base_class_usage()
+        cls._file = file
+
+    def validate_strict_type(self) -> None:
+        """Validate the type of the converter matches the desired type."""
+        if self._data_type.convert is UNSET:
+            msg = "Converter is not set."
+            raise InvalidConverterError(msg)
+
+        cls = self.__class__
+        self.__config_value = cls._parser.get(self._section, self._setting)
+        self.__converted_value = self.convert(self.__config_value)
+
+        if not cls.validate_types:
+            return
+
+        self.__converted_type = type(self.__converted_value)
+        default_value_type = type(self._data_type.default)
+
+        is_optional = self.optional or isinstance(self._data_type, Optional)
+        if (is_optional) and self.__converted_type in (default_value_type, NoneType):
+            # Allow None or the same type as the default value to be returned by the converter when _optional is True.
+            return
+        if self.__converted_type is not default_value_type:
+            msg = f"Converter does not return the same type as the default value <{default_value_type}> got <{self.__converted_type}>."  # noqa: E501
+            raise InvalidConverterError(msg)
+
+        # Set the data_type value. ensuring validation works as expected.
+        self._data_type.value = self.__converted_value
+        if not self._data_type.validate():
+            msg = f"Invalid value for {self._section}.{self._setting}: {self.__converted_value}"
+            raise InvalidConverterError(msg)
+
+    @classmethod
+    def validate_file(cls) -> None:
+        """Validate the config file."""
+        if cls._file is UNSET:
+            msg = f"Config file is not set. use {cls.__name__}.set_file() to set it."
+            raise ValueError(msg)
+
+    @classmethod
+    def validate_parser(cls) -> None:
+        """Validate the config parser."""
+        if cls._parser is UNSET:
+            msg = f"Config parser is not set. use {cls.__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()
+        cls = self.__class__
+        self._original_value = cls._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):
+            cls = self.__class__
+            cls._set(self._section, self._setting, self._data_type)
+
+    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.__converted_value
+
+    def __set__(self, obj: object, value: VT) -> None:
+        """Set the value of the attribute."""
+        self._data_type.value = value
+        cls = self.__class__
+        cls._set(self._section, self._setting, self._data_type)
+        setattr(obj, self.private, value)
+
+    @staticmethod
+    def _sanitize_str(value: str) -> str:
+        """Escape the percent sign in the value."""
+        return value.replace("%", "%%")
+
+    @classmethod
+    def _set(cls, section: str, setting: str, value: VT | BaseDataType[VT] | BaseDataType[VT | None]) -> None:
+        """Set a config value, and write it to the file."""
+        if not cls._parser.has_section(section):
+            cls._parser.add_section(section)
+
+        sanitized_str = cls._sanitize_str(str(value))
+        cls._parser.set(section, setting, sanitized_str)
+
+        if cls.write_on_edit:
+            cls.write()
+
+
+    @classmethod
+    def write(cls) -> None:
+        """Write the config parser to the file."""
+        cls.validate_file()
+        with cls._file.open("w") as f:
+            cls._parser.write(f)
+
+    @classmethod
+    def set(cls, section: str, setting: str, value: VT):  # noqa: ANN206
+        """Set a config value using this descriptor."""
+
+        def wrapper(func: Callable[..., F]) -> Callable[..., F]:
+            @wraps(func)
+            def inner(*args: P.args, **kwargs: P.kwargs) -> F:
+                cls._set(section, setting, value)
+                return func(*args, **kwargs)
+
+            return inner
+        return wrapper
+
+
+    @classmethod
+    def with_setting(cls, setting: Config[OVT]):  # noqa: ANN206
+        """Insert a config value into **kwargs to the wrapped method/function using this decorator."""
+        def wrapper(func: Callable[..., F]) -> Callable[..., F]:
+            @wraps(func)
+            def inner(*args: P.args, **kwargs: P.kwargs) -> F:
+                kwargs[setting.name] = setting.convert(cls._parser.get(setting._section, setting._setting))
+                return func(*args, **kwargs)
+
+            return inner
+        return wrapper
+
+
+    @classmethod
+    def with_kwarg(cls, section: str, setting: str, name: str | None = None, default: VT = UNSET):  # noqa: ANN206
+        """Insert a config value into **kwargs to the wrapped 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 cls._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(func: Callable[..., F]) -> Callable[..., F]:
+            @wraps(func)
+            def inner(*args: P.args, **kwargs: P.kwargs) -> F:
+                if default is not UNSET:
+                    cls._set_default(section, setting, default)
+                kwargs[name] = cls._parser.get(section, setting) # ty: ignore[invalid-assignment]
+                return func(*args, **kwargs)
+
+            return inner
+        return wrapper
+
+    @classmethod
+    def _set_default(cls, section: str, setting: str, value: VT) -> None:
+        if cls._parser.get(section, setting, fallback=UNSET) is UNSET:
+            cls._set(section, setting, value)
+
+    @classmethod
+    def default(cls, section: str, setting: str, value: VT):  # noqa: ANN206
+        """Set a default config value if none are set yet using this descriptor."""
+        def wrapper(func: Callable[..., F]) -> Callable[..., F]:
+            @wraps(func)
+            def inner(*args: P.args, **kwargs: P.kwargs) -> F:
+                cls._set_default(section, setting, value)
+                return func(*args, **kwargs)
+
+            return inner
+        return wrapper

confkit/data_types.py

@@ -0,0 +1,724 @@
+"""Module that contains the base data types used in the config system."""
+
+from __future__ import annotations
+
+import enum
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from datetime import UTC, date, datetime, time, timedelta, tzinfo
+from typing import ClassVar, Generic, NotRequired, Required, TypedDict, TypeVar, Unpack, cast, overload
+
+from confkit.sentinels import UNSET
+
+from .exceptions import InvalidConverterError, InvalidDefaultError
+
+T = TypeVar("T")
+
+
+class BaseDataType(ABC, Generic[T]):
+    """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
+        self.type = type(default)
+
+    def __str__(self) -> str:
+        """Return the string representation of the stored value."""
+        return str(self.value)
+
+    @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 hasattr(type_arg, "__origin__"):
+                            # For parameterized generics, check against the origin type
+                            if isinstance(self.value, type_arg.__origin__):
+                                return True
+                        elif isinstance(self.value, (self.type, 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: `DTBDT`"
+        raise TypeError(msg)
+
+    @staticmethod
+    def cast_optional(default: T | None | BaseDataType[T]) -> BaseDataType[T | None]:
+        """Convert the default value to an Optional data type."""
+        if default is None:
+            return cast("BaseDataType[T | None]", NoneType())
+        return Optional(BaseDataType.cast(default))
+
+    @staticmethod
+    def cast(default: T | BaseDataType[T]) -> BaseDataType[T]:
+        """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[T]", Boolean(default))
+            case None:
+                data_type = cast("BaseDataType[T]", NoneType())
+            case int():
+                data_type = cast("BaseDataType[T]", Integer(default))
+            case float():
+                data_type = cast("BaseDataType[T]", Float(default))
+            case str():
+                data_type = cast("BaseDataType[T]", 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
+
+
+class _EnumBase(BaseDataType[T]):
+    """Base class for enum types with common functionality."""
+
+    @staticmethod
+    def _strip_comment(value: str) -> str:
+        """Strip inline comments from value.
+
+        Since hex values use 0x prefix (not #), we can safely strip everything after #.
+        """
+        if "#" in value:
+            return value.split("#")[0].strip()
+        return value
+
+    @abstractmethod
+    def _format_allowed_values(self) -> str:
+        """Format the allowed values string. Override in subclasses."""
+        raise NotImplementedError
+
+    def __str__(self) -> str:
+        """Return the string representation with allowed values."""
+        if self.value is None:
+            return str(self.value)
+        return f"{self._get_value_str()}  # allowed: {self._format_allowed_values()}"
+
+    @abstractmethod
+    def _get_value_str(self) -> str:
+        """Get the string representation of the current value. Override in subclasses."""
+        raise NotImplementedError
+
+
+EnumType = TypeVar("EnumType", bound=enum.Enum)
+class Enum(_EnumBase[EnumType]):
+    """A config value that is an enum."""
+
+    def convert(self, value: str) -> EnumType:
+        """Convert a string value to an enum."""
+        value = self._strip_comment(value)
+        parsed_enum_name = value.split(".")[-1]
+        return self.value.__class__[parsed_enum_name]
+
+    def _format_allowed_values(self) -> str:
+        """Format allowed values as comma-separated member names."""
+        enum_class = self.value.__class__
+        return ", ".join(member.name for member in enum_class)
+
+    def _get_value_str(self) -> str:
+        """Get the member name."""
+        return self.value.name
+
+StrEnumType = TypeVar("StrEnumType", bound=enum.StrEnum)
+class StrEnum(_EnumBase[StrEnumType]):
+    """A config value that is an enum."""
+
+    def convert(self, value: str) -> StrEnumType:
+        """Convert a string value to an enum."""
+        value = self._strip_comment(value)
+        return self.value.__class__(value) # ty: ignore[invalid-return-type] # this is correct. ty says "Unknown | StrEnum"
+
+    def _format_allowed_values(self) -> str:
+        """Format allowed values as comma-separated member values."""
+        enum_class = self.value.__class__
+        return ", ".join(member.value for member in enum_class)
+
+    def _get_value_str(self) -> str:
+        """Get the member value."""
+        return self.value.value
+
+IntEnumType = TypeVar("IntEnumType", bound=enum.IntEnum)
+class IntEnum(_EnumBase[IntEnumType]):
+    """A config value that is an enum."""
+
+    def convert(self, value: str) -> IntEnumType:
+        """Convert a string value to an enum."""
+        value = self._strip_comment(value)
+        return self.value.__class__(int(value)) # ty: ignore[invalid-return-type] # ty says "Unknown | IntEnum"
+
+    def _format_allowed_values(self) -> str:
+        """Format allowed values as comma-separated name(value) pairs."""
+        enum_class = self.value.__class__
+        return ", ".join(f"{member.name}({member.value})" for member in enum_class)
+
+    def _get_value_str(self) -> str:
+        """Get the member value as string."""
+        return str(self.value.value)
+
+IntFlagType = TypeVar("IntFlagType", bound=enum.IntFlag)
+class IntFlag(_EnumBase[IntFlagType]):
+    """A config value that is an enum."""
+
+    def convert(self, value: str) -> IntFlagType:
+        """Convert a string value to an enum."""
+        value = self._strip_comment(value)
+        return self.value.__class__(int(value)) # ty: ignore[invalid-return-type] # ty says "Unknown | IntFlag"
+
+    def _format_allowed_values(self) -> str:
+        """Format allowed values as comma-separated name(value) pairs."""
+        enum_class = self.value.__class__
+        return ", ".join(f"{member.name}({member.value})" for member in enum_class)
+
+    def _get_value_str(self) -> str:
+        """Get the member value as string."""
+        return str(self.value.value)
+
+class NoneType(BaseDataType[None]):
+    """A config value that is None."""
+
+    null_values: ClassVar[set[str]] = {"none", "null", "nil"}
+
+    def __init__(self) -> None:
+        """Initialize the NoneType data type."""
+        super().__init__(None)
+
+    def convert(self, value: str) -> bool: # type: ignore[reportIncompatibleMethodOverride]
+        """Convert a string value to None."""
+        # Ignore type exception as convert should return True/False for NoneType
+        # to determine if we have a valid null value or not.
+        return value.casefold().strip() in NoneType.null_values
+
+
+class String(BaseDataType[str]):
+    """A config value that is a string."""
+
+    def __init__(self, default: str = "") -> None:  # noqa: D107
+        super().__init__(default)
+
+    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 __init__(self, default: float = 0.0) -> None:  # noqa: D107
+        super().__init__(default)
+
+    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 __init__(self, default: bool = False) -> None:  # noqa: D107, FBT001, FBT002
+        super().__init__(default)
+
+    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)
+
+DECIMAL = 10
+HEXADECIMAL = 16
+OCTAL = 8
+BINARY = 2
+
+class Integer(BaseDataType[int]):
+    """A config value that is an integer."""
+
+    # Define constants for common bases
+
+    def __init__(self, default: int = 0, base: int = DECIMAL) -> None:  # noqa: D107
+        super().__init__(default)
+        self.base = base
+
+    @staticmethod
+    def int_to_base(number: int, base: int) -> int:
+        """Convert an integer to a string representation in a given base."""
+        if number == 0:
+            return 0
+        digits = []
+        while number:
+            digits.append(str(number % base))
+            number //= base
+        return int("".join(reversed(digits)))
+
+    def __str__(self) -> str:  # noqa: D105
+        if self.base == DECIMAL:
+            return str(self.value)
+        # Convert the base 10 int to base 5
+        self.value = self.int_to_base(int(self.value), self.base)
+        return f"{self.base}c{self.value}"
+
+    def convert(self, value: str) -> int:
+        """Convert a string value to an integer."""
+        if "c" in value:
+            base_str, val_str = value.split("c")
+            base = int(base_str)
+            if base != self.base:
+                msg = "Base in string does not match base in Integer while converting."
+                raise ValueError(msg)
+            return int(val_str, self.base)
+        return int(value, self.base)
+
+class Hex(Integer):
+    """A config value that represents hexadecimal."""
+
+    def __init__(self, default: int = 0, base: int = HEXADECIMAL) -> None:  # noqa: D107
+        super().__init__(default, base)
+
+    def __str__(self) -> str:  # noqa: D105
+        return f"0x{self.value:x}"
+
+    def convert(self, value: str) -> int:
+        """Convert a string value to an integer. from hexadecimal."""
+        return int(value.removeprefix("0x"), 16)
+
+class Octal(Integer):
+    """A config value that represents octal."""
+
+    def __init__(self, default: int = 0, base: int = OCTAL) -> None:  # noqa: D107
+        super().__init__(default, base)
+
+    def __str__(self) -> str:  # noqa: D105
+        return f"0o{self.value:o}"
+
+    def convert(self, value: str) -> int:
+        """Convert a string value to an integer from octal."""
+        return int(value.removeprefix("0o"), 8)
+
+class Binary(BaseDataType[bytes | int]):
+    """A config value that represents binary."""
+
+    def __init__(self, default: bytes | int = 0) -> None:  # noqa: D107
+        if isinstance(default, bytes):
+            default = int.from_bytes(default)
+        super().__init__(default)
+
+    def __str__(self) -> str:  # noqa: D105
+        if isinstance(self.value, bytes):
+            self.value = int.from_bytes(self.value)
+        return f"0b{self.value:b}"
+
+    def convert(self, value: str) -> int:
+        """Convert a string value to an integer from binary."""
+        return int(value.removeprefix("0b"), 2)
+
+class Optional(BaseDataType[T | None], Generic[T]):
+    """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
+
+    @value.setter
+    def value(self, value: T | None) -> None:
+        """Set the current value of the wrapped data type."""
+        self._data_type.value = value # type: ignore[reportAttributeAccessIssue]
+
+    def convert(self, value: str) -> T | None:
+        """Convert a string value to the optional type."""
+        if self._none_type.convert(value):
+            return None
+        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()
+
+    def __str__(self) -> str:
+        """Return the string representation of the wrapped data type."""
+        return str(self._data_type)
+
+class _SequenceType(BaseDataType[Sequence[T]], Generic[T]):
+    """A ABC for sequence types like List and Tuples."""
+
+    separator = ","
+    escape_char = "\\"
+
+    @overload
+    def __init__(self, default: Sequence[T]) -> None: ...
+    @overload
+    def __init__(self, *, data_type: BaseDataType[T]) -> None: ...
+    @overload
+    def __init__(
+        self,
+        default: Sequence[T],
+        *,
+        data_type: BaseDataType[T] = ...,
+    ) -> None: ...
+
+    def __init__(self, default: Sequence[T] = UNSET, *, data_type: BaseDataType[T] = UNSET) -> None:
+        """Initialize the sequence data type."""
+        if default is UNSET and data_type is UNSET:
+            msg = "Sequence requires either a default with at least one element, or data_type to be specified."
+            raise InvalidDefaultError(msg)
+        if default is UNSET:
+            default = []
+        super().__init__(default)
+        self._infer_type(default, data_type)
+
+    def _infer_type(self, default: Sequence[T], data_type: BaseDataType[T]) -> None:
+        if len(default) <= 0 and data_type is UNSET:
+            msg = "Sequence default must have at least one element to infer type. or specify `data_type=<BaseDataType>`"
+            raise InvalidDefaultError(msg)
+        if data_type is UNSET:
+            self._data_type = BaseDataType[T].cast(default[0])
+        else:
+            self._data_type = data_type
+
+    def _convert(self, value: str) -> Sequence[T]:
+        """Convert a string to a Sequence."""
+        # Handle empty string as empty list
+        if not value:
+            return []
+
+        # Split string but respect escaped separators
+        result: list[T] = []
+        current = ""
+        i = 0
+        while i < len(value):
+            # Check for escaped separator
+            if i < len(value) - 1 and value[i] == self.escape_char and value[i + 1] == self.separator:
+                current += self.separator
+                i += 2  # Skip both the escape char and the separator
+            # Check for escaped escape char
+            elif i < len(value) - 1 and value[i] == self.escape_char and value[i + 1] == self.escape_char:
+                current += self.escape_char
+                i += 2  # Skip both escape chars
+            # Handle separator
+            elif value[i] == self.separator:
+                c = self._data_type.convert(current)
+                result.append(c)
+                current = ""
+                i += 1
+            # Handle regular character
+            else:
+                current += value[i]
+                i += 1
+
+        # Add the last element
+        result.append(self._data_type.convert(current))
+
+        return result
+
+    def __str__(self) -> str:
+        """Return a string representation of the list."""
+        values: list[str] = []
+        for item in self.value:
+            # Escape escape char
+            escaped_item = str(item).replace(self.escape_char, self.escape_char*2)
+            # Escape separator
+            escaped_item = escaped_item.replace(self.separator, f"{self.escape_char}{self.separator}")
+            values.append(escaped_item)
+
+        return self.separator.join(values)
+
+class List(_SequenceType[T], Generic[T]):
+    """A config value that is a list of values."""
+
+    def convert(self, value: str) -> list[T]:
+        """Convert a string to a list."""
+        return list(super()._convert(value))
+
+class Tuple(_SequenceType[T], Generic[T]):
+    """A config value that is a tuple of values."""
+
+    def convert(self, value: str) -> tuple[T, ...]:
+        """Convert a string to a tuple."""
+        return tuple(super()._convert(value))
+
+class Set(BaseDataType[set[T]], Generic[T]):
+    """A config value that is a set of values."""
+
+    @overload
+    def __init__(self, default: set[T]) -> None: ...
+    @overload
+    def __init__(self, *, data_type: BaseDataType[T]) -> None: ...
+    @overload
+    def __init__(
+        self,
+        default: set[T],
+        *,
+        data_type: BaseDataType[T] = ...,
+    ) -> None: ...
+
+    def __init__(self, default: set[T] = UNSET, *, data_type: BaseDataType[T] = UNSET) -> None:
+        """Initialize the set data type."""
+        if default is UNSET and data_type is UNSET:
+            msg = "Set requires either a default with at least one element, or data_type to be specified."
+            raise InvalidDefaultError(msg)
+        if default is UNSET:
+            default = set()
+        super().__init__(default)
+        self._infer_type(default, data_type)
+
+    def _infer_type(self, default: set[T], data_type: BaseDataType[T]) -> None:
+        if len(default) <= 0 and data_type is UNSET:
+            msg = "Set default must have at least one element to infer type. or specify `data_type=<BaseDataType>`"
+            raise InvalidDefaultError(msg)
+        if data_type is UNSET:
+            sample_element = default.pop()
+            default.add(sample_element)
+            self._data_type = BaseDataType[T].cast(sample_element)
+        else:
+            self._data_type = data_type
+
+    def convert(self, value: str) -> set[T]:
+        """Convert a string to a set."""
+        if not value:
+            return set()
+        parts = value.split(",")
+        return {self._data_type.convert(item.strip()) for item in parts}
+
+    def __str__(self) -> str:
+        """Return a string representation of the set."""
+        return ",".join(str(item) for item in self.value)
+
+KT = TypeVar("KT")
+VT = TypeVar("VT")
+class Dict(BaseDataType[dict[KT, VT]], Generic[KT, VT]):
+    """A config value that is a dictionary of string keys and values of type T."""
+
+    @overload
+    def __init__(self, default: dict[KT, VT]) -> None: ...
+    @overload
+    def __init__(self, *, key_type: BaseDataType[KT], value_type: BaseDataType[VT]) -> None: ...
+    @overload
+    def __init__(
+        self,
+        default: dict[KT, VT],
+        *,
+        key_type: BaseDataType[KT] = ...,
+        value_type: BaseDataType[VT] = ...,
+    ) -> None: ...
+
+    def __init__(
+        self,
+        default: dict[KT, VT] = UNSET,
+        *,
+        key_type: BaseDataType[KT] = UNSET,
+        value_type: BaseDataType[VT] = UNSET,
+    ) -> None:
+        """Initialize the dict data type."""
+        if default is UNSET and (key_type is UNSET or value_type is UNSET):
+            msg = "Dict requires either a default with at least one key/value pair, or both key_type and value_type to be specified."  # noqa: E501
+            raise InvalidDefaultError(msg)
+        if default is UNSET:
+            default = {}
+        super().__init__(default)
+
+        self._infer_key_type(default, key_type)
+        self._infer_value_type(default, value_type)
+
+    def _infer_key_type(self, default: dict[KT, VT], key_type: BaseDataType[KT]) -> None:
+        """Infer the key type from the default dictionary if not provided."""
+        if len(default.keys()) <= 0 and key_type is UNSET:
+            msg = "Dict default must have at least one key element to infer type. or specify `key_type=<BaseDataType>`"
+            raise InvalidDefaultError(msg)
+        if key_type is UNSET:
+            for key in default:
+                self._key_data_type = BaseDataType[KT].cast(key)
+                break
+        else:
+            self._key_data_type = key_type
+
+    def _infer_value_type(self, default: dict[KT, VT], value_type: BaseDataType[VT]) -> None:
+        """Infer the value type from the default dictionary if not provided."""
+        if len(default.values()) <= 0 and value_type is UNSET:
+            msg = "Dict default must have at least one value element to infer type. or specify `value_type=<BaseDataType>`"
+            raise InvalidDefaultError(msg)
+        if value_type is UNSET:
+            for value in default.values():
+                self._value_data_type = BaseDataType[VT].cast(value)
+                break
+        else:
+            self._value_data_type = value_type
+
+    def convert(self, value: str) -> dict[KT, VT]:
+        """Convert a string to a dictionary."""
+        if not value:
+            return {}
+
+        parts = value.split(",")
+        result: dict[KT, VT] = {}
+        for part in parts:
+            if "=" not in part:
+                msg = f"Invalid dictionary entry: {part}. Expected format key=value."
+                raise ValueError(msg)
+            key_str, val_str = part.split("=", 1)
+            key = self._key_data_type.convert(key_str.strip())
+            val = self._value_data_type.convert(val_str.strip())
+            result[key] = val
+        return result
+
+    def __str__(self) -> str:
+        """Return a string representation of the dictionary."""
+        items = [
+            f"{self._key_data_type.convert(str(k))}={self._value_data_type.convert(str(v))}"
+            for k, v in self.value.items()
+        ]
+        return ",".join(items)
+
+class _DateTimeKwargs(TypedDict, total=False):
+    year: Required[int]
+    month: Required[int]
+    day: Required[int]
+    hour: int
+    minute: int
+    second: int
+    microsecond: int
+    tzinfo: tzinfo | None
+    fold: int
+
+class DateTime(BaseDataType[datetime]):
+    """A config value that is a datetime."""
+
+    @overload
+    def __init__(self, default: datetime = UNSET) -> None: ...
+    @overload
+    def __init__(self, **kwargs: Unpack[_DateTimeKwargs]) -> None: ...
+
+    def __init__(self, default: datetime = UNSET, **kwargs: Unpack[_DateTimeKwargs]) -> None: # pyright: ignore[reportInconsistentOverload]
+        """Initialize the datetime data type. Defaults to current datetime (datetime.now) if not provided."""
+        if default is UNSET:
+            try:
+                default = datetime(**kwargs)  # ty: ignore[missing-argument]  # noqa: DTZ001
+            except TypeError:
+                default = datetime.now(tz=UTC)
+        super().__init__(default)
+
+    def convert(self, value: str) -> datetime:
+        """Convert a string value to a datetime."""
+        return datetime.fromisoformat(value)
+
+    def __str__(self) -> str:
+        """Return the string representation of the stored value."""
+        return self.value.isoformat()
+
+class _DateKwargs(TypedDict):
+    year: int
+    month: int
+    day: int
+
+class Date(BaseDataType[date]):
+    """A config value that is a date."""
+
+    @overload
+    def __init__(self, default: date = UNSET) -> None: ...
+    @overload
+    def __init__(self, **kwargs: Unpack[_DateKwargs]) -> None: ...
+
+    def __init__(self, default: date = UNSET, **kwargs: Unpack[_DateKwargs]) -> None: # pyright: ignore[reportInconsistentOverload]
+        """Initialize the date data type. Defaults to current date if not provided."""
+        if default is UNSET:
+            default = date(**kwargs)
+        super().__init__(default)
+
+    def convert(self, value: str) -> date:
+        """Convert a string value to a date."""
+        return date.fromisoformat(value)
+
+    def __str__(self) -> str:  # noqa: D105
+        return self.value.isoformat()
+
+class _TimeKwargs(TypedDict, total=False):
+    hour: NotRequired[int]
+    minute: NotRequired[int]
+    second: NotRequired[int]
+    microsecond: NotRequired[int]
+    tzinfo: tzinfo | None
+    fold: NotRequired[int]
+
+class Time(BaseDataType[time]):
+    """A config value that is a time."""
+
+    @overload
+    def __init__(self, default: time = UNSET) -> None: ...
+    @overload
+    def __init__(self, **kwargs: Unpack[_TimeKwargs]) -> None: ...
+
+    def __init__(self, default: time = UNSET, **kwargs: Unpack[_TimeKwargs]) -> None:
+        """Initialize the time data type. Defaults to current time if not provided."""
+        if default is UNSET:
+            default = time(**kwargs) # ty: ignore[missing-argument]
+        super().__init__(default)
+
+    def convert(self, value: str) -> time:
+        """Convert a string value to a time."""
+        return time.fromisoformat(value)
+
+    def __str__(self) -> str:  # noqa: D105
+        return self.value.isoformat()
+
+class _TimeDeltaKwargs(TypedDict, total=False):
+    days: NotRequired[float]
+    seconds: NotRequired[float]
+    microseconds: NotRequired[float]
+    milliseconds: NotRequired[float]
+    minutes: NotRequired[float]
+    hours: NotRequired[float]
+    weeks: NotRequired[float]
+
+class TimeDelta(BaseDataType[timedelta]):
+    """A config value that is a timedelta."""
+
+    def __init__(
+        self,
+        default: timedelta = UNSET,
+        **kwargs: Unpack[_TimeDeltaKwargs],
+    ) -> None:
+        """Initialize the timedelta data type. Defaults to 0 if not provided."""
+        if default is UNSET:
+            default = timedelta(**kwargs)
+        super().__init__(default)
+
+    def convert(self, value: str) -> timedelta:
+        """Convert a string value to a timedelta."""
+        return timedelta(seconds=float(value))
+
+    def __str__(self) -> str:  # noqa: D105
+        return str(self.value.total_seconds())

confkit/exceptions.py

@@ -0,0 +1,8 @@
+"""Module for custom exceptions used in the confkit 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/ext/__init__.py

@@ -0,0 +1,8 @@
+"""Optional extension modules for confkit.
+
+Modules inside this package may rely on optional extras. They are intentionally
+not imported eagerly so users can access the pieces they installed without
+pulling in additional dependencies.
+"""
+
+__all__: list[str] = []

confkit/ext/pydantic.py

@@ -0,0 +1,21 @@
+"""Helper utilities for working with Pydantic models and confkit."""
+from __future__ import annotations
+
+try:
+    from pydantic import BaseModel  # noqa: TC002
+except ImportError as exc:  # pragma: no cover - executed only when optional extra missing
+    msg = (
+        "confkit.ext.pydantic requires the optional 'pydantic' extra. "
+        "Install it via 'pip install "
+        "confkit[pydantic]' or 'uv add confkit[pydantic]'."
+    )
+    raise ImportError(msg) from exc
+
+
+def apply_model(config_instance: object, model: BaseModel) -> None:
+    """Apply values from a Pydantic model to matching Config descriptors."""
+    for field, value in model.model_dump().items():
+        if hasattr(type(config_instance), field):
+            setattr(config_instance, field, value)
+
+__all__ = ["apply_model"]

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.10.0.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: confkit
+Version: 0.10.0
+Summary: Lightweight and Easy to use configuration manager for Python projects
+Author-email: HEROgold <martijnwieringa28@gmail.com>
+Requires-Python: >=3.11
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2.12.5; extra == 'pydantic'
+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)
+[![Coverage Status](https://coveralls.io/repos/github/HEROgold/confkit/badge.svg?branch=master)](https://coveralls.io/github/HEROgold/confkit?branch=master)
+
+Type-safe configuration manager for Python projects using descriptors and ConfigParser.
+
+Full documentation: [confkit docs](https://HEROgold.github.io/confkit/)
+
+## Supported Python Versions
+
+confkit follows the [Python version support policy](https://devguide.python.org/versions/) as outlined in the Python Developer's Guide:
+
+- We support all active and maintenance releases of Python, starting with 3.11
+- End-of-life (EOL) Python versions are **not** supported
+- We aim to support Python release candidates to stay ahead of the release cycle
+
+This ensures that confkit remains compatible with current Python versions while allowing us to leverage modern language features.
+
+## 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
+
+## Getting Started / Usage
+
+For full quickstart, advanced patterns (custom data types, decorators, argparse integration), and runnable examples, visit the documentation site:
+
+👉 [confkit documentation site](https://HEROgold.github.io/confkit/usage)
+
+Direct entry points:
+
+- Quickstart & descriptor patterns: Usage Guide
+- All examples: Examples Overview
+- Custom datatype tutorial: Custom Data Type example
+- API reference: pdoc-generated symbol index
+
+You can still browse example source locally under `examples/`.
+
+## 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 .
+```
+
+#### Building Documentation
+
+To build and preview documentation locally:
+
+```bash
+# Install documentation dependencies
+uv sync --group docs
+
+# Generate API documentation with pdoc
+uv run pdoc confkit -o docs/api
+
+# Build documentation site with mkdocs
+uv run mkdocs build -d site
+
+# Or serve locally for live preview (with auto-reload)
+uv run mkdocs serve
+```
+
+Documentation is automatically built and deployed to GitHub Pages when changes are pushed to the `master` branch.
+
+**After updating code that affects documentation:**
+
+1. Update relevant `.md` files in `docs/` directory (examples, reference, etc.)
+2. Run `uv run pdoc confkit -o docs/api` to regenerate API documentation
+3. Preview changes with `uv run mkdocs serve` and verify at `http://127.0.0.1:8000`
+4. Commit both code and documentation changes together

confkit-0.10.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+confkit/__init__.py,sha256=TVnB-w14Yb1hivFtFvIP89uObg2xXJemfmPLvO6io0s,938
+confkit/config.py,sha256=KRoEsZrw5wYaZYfWT-v4AFdvLNC1WN2xvAkrEw_XLPU,13834
+confkit/data_types.py,sha256=cnQymjNDmar_gl_Je-mRmvYMyY3hV61T6dFAml7SLt8,26497
+confkit/exceptions.py,sha256=IlSnRkQM4hueDxK0kpGzcC3_ZPH9gMGEMtLTuE-zW_g,269
+confkit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+confkit/sentinels.py,sha256=qiqeYxW7Mavhedd9RaVHqNn71vok-x9PJBlbYxnmcRY,372
+confkit/ext/__init__.py,sha256=8EWGwP4amL2le1BdzgIew1gI3toVkb0aB4T5xZMS-U8,264
+confkit/ext/pydantic.py,sha256=YpgPDzU4Ax-DOqhwLNpvgCgjA7xs-kHvVNKmadUPj8s,803
+confkit-0.10.0.dist-info/METADATA,sha256=ayBdJW5bSNSKQBjKVEVpyUw_VOSzTlI4DJBr8ADskn0,3649
+confkit-0.10.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+confkit-0.10.0.dist-info/RECORD,,

confkit-0.10.0.dist-info/WHEEL

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