confkit

23class BaseDataType(ABC, Generic[T]):
24    """Base class used for Config descriptors to define a data type."""
25
26    def __init__(self, default: T) -> None:
27        """Initialize the base data type."""
28        self.default = default
29        self.value = default
30        self.type = type(default)
31
32    def __str__(self) -> str:
33        """Return the string representation of the stored value."""
34        return str(self.value)
35
36    @abstractmethod
37    def convert(self, value: str) -> T:
38        """Convert a string value to the desired type."""
39
40    def validate(self) -> bool:
41        """Validate that the value matches the expected type."""
42        orig_bases: tuple[type, ...] | None = getattr(self.__class__, "__orig_bases__", None)
43
44        if not orig_bases:
45            msg = "No type information available for validation."
46            raise InvalidConverterError(msg)
47
48        # Extract type arguments from the generic base
49        for base in orig_bases:
50            if hasattr(base, "__args__"):
51                type_args = base.__args__
52                if type_args:
53                    for type_arg in type_args:
54                        if hasattr(type_arg, "__origin__"):
55                            # For parameterized generics, check against the origin type
56                            if isinstance(self.value, type_arg.__origin__):
57                                return True
58                        elif isinstance(self.value, (self.type, type_arg)):
59                            return True
60                    msg = f"Value {self.value} is not any of {type_args}."
61                    raise InvalidConverterError(msg)
62        msg = "This should not have raised. Report to the library maintainers with code: `DTBDT`"
63        raise TypeError(msg)
64
65    @staticmethod
66    def cast_optional(default: T | None | BaseDataType[T]) -> BaseDataType[T | None]:
67        """Convert the default value to an Optional data type."""
68        if default is None:
69            return cast("BaseDataType[T | None]", NoneType())
70        return Optional(BaseDataType.cast(default))
71
72    @staticmethod
73    def cast(default: T | BaseDataType[T]) -> BaseDataType[T]:  # noqa: C901, PLR0911
74        """Convert the default value to a BaseDataType."""
75        # We use Cast to shut up type checkers, as we know primitive types will be correct.
76        # If a custom type is passed, it should be a BaseDataType subclass, which already has the correct types.
77        # Check enum types BEFORE basic types since some enums inherit from str/int
78        match default:
79            case dStrEnum():     return cast("BaseDataType[T]", StrEnum(default))
80            case dIntFlag():     return cast("BaseDataType[T]", IntFlag(default))
81            case dIntEnum():     return cast("BaseDataType[T]", IntEnum(default))
82            case dEnum():        return cast("BaseDataType[T]", Enum(default))
83            case bool():         return cast("BaseDataType[T]", Boolean(default))
84            case None:           return cast("BaseDataType[T]", NoneType())
85            case int():          return cast("BaseDataType[T]", Integer(default))
86            case float():        return cast("BaseDataType[T]", Float(default))
87            case str():          return cast("BaseDataType[T]", String(default))
88            case BaseDataType(): return default
89            case _:
90                msg = (
91                    f"Unsupported default value type: {type(default).__name__}. "
92                    "Use a BaseDataType subclass for custom types."
93                )
94                raise InvalidDefaultError(msg)

327class Binary(BaseDataType[bytes | int]):
328    """A config value that represents binary."""
329
330    def __init__(self, default: bytes | int = 0) -> None:  # noqa: D107
331        if isinstance(default, bytes):
332            default = int.from_bytes(default)
333        super().__init__(default)
334
335    def __str__(self) -> str:  # noqa: D105
336        if isinstance(self.value, bytes):
337            self.value = int.from_bytes(self.value)
338        return f"0b{self.value:b}"
339
340    def convert(self, value: str) -> int:
341        """Convert a string value to an integer from binary."""
342        return int(value.removeprefix("0b"), 2)

243class Boolean(BaseDataType[bool]):
244    """A config value that is a boolean."""
245
246    def __init__(self, default: bool = False) -> None:  # noqa: D107, FBT001, FBT002
247        super().__init__(default)
248
249    def convert(self, value: str) -> bool:
250        """Convert a string value to a boolean."""
251        if value.lower() in {"true", "1", "yes"}:
252            return True
253        if value.lower() in {"false", "0", "no"}:
254            return False
255        msg = f"Cannot convert {value} to boolean."
256        raise ValueError(msg)

 48class Config(Generic[VT]):
 49    """A descriptor for config values, preserving type information.
 50
 51    the ValueType (VT) is the type you want the config value to be.
 52    """
 53
 54    validate_types: ClassVar[bool] = True
 55    """Validate that the converter returns the same type as the default value. (not strict)"""
 56    write_on_edit: ClassVar[bool] = True
 57    """Write to the config file when updating a value."""
 58    optional: bool = False
 59    """If True, allows None as an extra type when validating types. (both instance and class variables.)"""
 60
 61    _parser: ConfkitParser = UNSET
 62    _file: Path = UNSET
 63    _has_read_config: bool = False
 64    _data_type: BaseDataType[VT]
 65
 66    if TYPE_CHECKING:
 67        # Overloads for type checkers to understand the different settings of the Config descriptors.
 68        @overload # Custom data type, like Enum's or custom class.
 69        def __init__(self, default: BaseDataType[VT]) -> None: ...
 70        @overload
 71        def __init__(self, default: VT) -> None: ...
 72        # Specify the states of optional explicitly for type checkers.
 73        @overload
 74        def __init__(self: Config[OVT], default: OVT, *, optional: Literal[False]) -> None: ...
 75        @overload
 76        def __init__(self: Config[OVT], default: BaseDataType[OVT], *, optional: Literal[False]) -> None: ...
 77        @overload
 78        def __init__(self: Config[OVT | None], default: OVT, *, optional: Literal[True]) -> None: ...
 79        @overload
 80        def __init__(self: Config[OVT | None], default: BaseDataType[OVT], *, optional: Literal[True]) -> None: ...
 81
 82    def __init__(
 83        self,
 84        default: VT | None | BaseDataType[VT] = UNSET,
 85        *,
 86        optional: bool = False,
 87    ) -> None:
 88        """Initialize the config descriptor with a default value.
 89
 90        Validate that parser and filepath are present.
 91        """
 92        cls = self.__class__
 93        self.optional = optional or cls.optional # Be truthy when either one is true.
 94
 95        if not self.optional and default is UNSET:
 96            msg = "Default value cannot be None when optional is False."
 97            raise InvalidDefaultError(msg)
 98
 99        if not self._parser:
100            self._detect_parser()
101
102        self._initialize_data_type(default)
103        self._validate_init()
104        self._read_parser()
105
106    def __init_subclass__(cls) -> None:
107        """Allow for multiple config files/parsers without conflicts."""
108        super().__init_subclass__()
109
110        parent = cls._find_parent()
111
112        cls.validate_types = parent.validate_types
113        cls.write_on_edit = parent.write_on_edit
114        cls._parser = parent._parser  # noqa: SLF001
115        cls._file = parent._file  # noqa: SLF001
116        cls._has_read_config = parent._has_read_config  # noqa: SLF001
117
118    @classmethod
119    def _find_parent(cls) -> type[Config[Any]]:
120        for base in cls.__bases__:
121            if issubclass(base, Config):
122                parent = base
123                break
124        else:
125            parent = Config
126        return parent
127
128    def _initialize_data_type(self, default: VT | None | BaseDataType[VT]) -> None:
129        """Initialize the data type based on the default value."""
130        if not self.optional and default is not None:
131            self._data_type = BaseDataType[VT].cast(default)
132        else:
133            self._data_type = BaseDataType[VT].cast_optional(default)
134
135    def _read_parser(self) -> None:
136        """Ensure the parser has read the file at initialization. Avoids rewriting the file when settings are already set."""
137        cls = self.__class__
138        if not cls._has_read_config:
139            self._parser.read(self._file)
140            cls._has_read_config = True
141
142    def _validate_init(self) -> None:
143        """Validate the config descriptor, ensuring it's properly set up."""
144        self.validate_file()
145        self.validate_parser()
146
147    def convert(self, value: str) -> VT:
148        """Convert the value to the desired type using the given converter method."""
149        return self._data_type.convert(value)
150
151    @staticmethod
152    def _warn_base_class_usage() -> None:
153        """Warn users that setting parser/file on the base class can lead to unexpected behavior.
154        Tell the user to subclass <Config> first.
155        """  # noqa: D205
156        warnings.warn("<Config> is the base class. Subclass <Config> to avoid unexpected behavior.", stacklevel=2)
157
158    @classmethod
159    @deprecated("Avoid using set_parser. Confkit will automatically assign a parser based on the file extension. In 2.0 this will be a private method.")  # noqa: E501
160    def set_parser(cls, parser: ConfkitParser) -> None:
161        """Set the parser for ALL descriptor instances (of this type/class)."""
162        if cls is Config:
163            cls._warn_base_class_usage()
164        cls._parser = parser
165
166    @classmethod
167    def _detect_parser(cls) -> None:
168        """Set the parser for descriptors based on the file extension of cls._file.
169
170        Uses msgspec-based parsers for yaml, json, toml. Defaults to dict structure.
171        Only sets the parser if there is no parser set.
172        """
173        if cls._file is UNSET:
174            msg = "Config file is not set. Use `set_file()`."
175            raise ValueError(msg)
176        match cls._file.suffix.lower():
177            case ".ini":
178                cls._parser = IniParser()
179            case ".yaml" | ".yml" | ".json" | ".toml":
180                from confkit.ext.parsers import MsgspecParser  # noqa: PLC0415  Only import if actually used.
181                cls._parser = MsgspecParser()
182            case ".env":
183                cls._parser = EnvParser()
184            case _:
185                msg = f"Unsupported config file extension: {cls._file.suffix.lower()}"
186                raise ValueError(msg)
187
188    @classmethod
189    def set_file(cls, file: Path) -> None:
190        """Set the file for ALL descriptors."""
191        if cls is Config:
192            cls._warn_base_class_usage()
193        cls._file = file
194        cls._watcher = FileWatcher(file)
195
196    def validate_strict_type(self) -> None:
197        """Validate the type of the converter matches the desired type."""
198        if self._data_type.convert is UNSET:
199            msg = "Converter is not set."
200            raise InvalidConverterError(msg)
201
202        cls = self.__class__
203        self.__config_value = cls._parser.get(self._section, self._setting)
204        self.__converted_value = self.convert(self.__config_value)
205
206        if not cls.validate_types:
207            return
208
209        self.__converted_type = type(self.__converted_value)
210        default_value_type = type(self._data_type.default)
211
212        is_optional = self.optional or isinstance(self._data_type, Optional)
213        if (is_optional) and self.__converted_type in (default_value_type, NoneType):
214            # Allow None or the same type as the default value to be returned by the converter when _optional is True.
215            return
216        if self.__converted_type is not default_value_type:
217            msg = f"Converter does not return the same type as the default value <{default_value_type}> got <{self.__converted_type}>."  # noqa: E501
218            raise InvalidConverterError(msg)
219
220        # Set the data_type value. ensuring validation works as expected.
221        self._data_type.value = self.__converted_value
222        if not self._data_type.validate():
223            msg = f"Invalid value for {self._section}.{self._setting}: {self.__converted_value}"
224            raise InvalidConverterError(msg)
225
226    @classmethod
227    def validate_file(cls) -> None:
228        """Validate the config file."""
229        if cls._file is UNSET:
230            msg = f"Config file is not set. use {cls.__name__}.set_file() to set it."
231            raise ValueError(msg)
232
233    @classmethod
234    def validate_parser(cls) -> None:
235        """Validate the config parser."""
236        if cls._parser is UNSET:
237            msg = f"Config parser is not set. use {cls.__name__}.set_parser() to set it."
238            raise ValueError(msg)
239
240    def __set_name__(self, owner: type, name: str) -> None:
241        """Set the name of the attribute to the name of the descriptor."""
242        self.name = name
243        self._section = self._build_section_name(owner)
244        self._setting = name
245        self._ensure_option()
246        cls = self.__class__
247        self._original_value = cls._parser.get(self._section, self._setting) or self._data_type.default
248        self.private = f"_{self._section}_{self._setting}_{self.name}"
249
250    @staticmethod
251    def _build_section_name(owner: type) -> str:
252        """Build a section name from the class hierarchy using dot notation.
253
254        Strips out function-local scope markers like <locals>.
255        """
256        if qualname := getattr(owner, "__qualname__", None):
257            split_at = qualname.find("<locals>.")
258            if split_at != -1:
259                qualname = qualname[split_at + len("<locals>.") :]
260            return ".".join(
261                part
262                for part in qualname.split(".")
263            )
264        return owner.__name__
265
266    def _ensure_section(self) -> None:
267        """Ensure the section exists in the config file. Creates one if it doesn't exist."""
268        if not self._parser.has_section(self._section):
269            self._parser.add_section(self._section)
270
271    def _ensure_option(self) -> None:
272        """Ensure the option exists in the config file. Creates one if it doesn't exist."""
273        self._ensure_section()
274        if not self._parser.has_option(self._section, self._setting):
275            cls = self.__class__
276            cls._set(self._section, self._setting, self._data_type)
277
278    def __get__(self, obj: object, obj_type: object) -> VT:
279        """Get the value of the attribute."""
280        # obj_type is the class in which the variable is defined
281        # so it can be different than type of VT
282        # but we don't need obj or it's type to get the value from config in our case.
283        if self._watcher.has_changed():
284            self.on_file_change(
285                "get",
286                self._data_type.value,
287                self.convert(self._parser.get(self._section, self._setting)),
288            )
289
290        self.validate_strict_type()
291        return self.__converted_value  # This is already used when checking type validation, so it's safe to return it.
292
293    def __set__(self, obj: object, value: VT) -> None:
294        """Set the value of the attribute."""
295        if self._watcher.has_changed():
296            self.on_file_change("set", self._data_type.value, value)
297
298        self._data_type.value = value
299        cls = self.__class__
300        cls._set(self._section, self._setting, self._data_type)
301        setattr(obj, self.private, value)
302
303    @classmethod
304    def _set(cls, section: str, setting: str, value: VT | BaseDataType[VT] | BaseDataType[VT | None]) -> None:
305        """Set a config value, and write it to the file."""
306        if not cls._parser.has_section(section):
307            cls._parser.add_section(section)
308
309        cls._parser.set(section, setting, value)
310
311        if cls.write_on_edit:
312            cls.write()
313
314
315    @classmethod
316    def write(cls) -> None:
317        """Write the config parser to the file."""
318        cls.validate_file()
319        with cls._file.open("w") as f:
320            cls._parser.write(f)
321
322    @classmethod
323    def set(cls, section: str, setting: str, value: VT) -> Callable[[Callable[P, F]], Callable[P, F]]:
324        """Set a config value using this descriptor."""
325
326        def wrapper(func: Callable[P, F]) -> Callable[P, F]:
327            @wraps(func)
328            def inner(*args: P.args, **kwargs: P.kwargs) -> F:
329                cls._set(section, setting, value)
330                return func(*args, **kwargs)
331
332            return inner
333        return wrapper
334
335
336    @classmethod
337    def with_setting(cls, setting: Config[OVT]) -> Callable[[Callable[P, F]], Callable[P, F]]:
338        """Insert a config value into **kwargs to the wrapped method/function using this decorator."""
339        def wrapper(func: Callable[P, F]) -> Callable[P, F]:
340            @wraps(func)
341            def inner(*args: P.args, **kwargs: P.kwargs) -> F:
342                kwargs[setting.name] = setting.convert(cls._parser.get(setting._section, setting._setting))
343                return func(*args, **kwargs)
344
345            return inner
346        return wrapper
347
348
349    @classmethod
350    def with_kwarg(
351        cls, section: str, setting: str, name: str | None = None, default: VT = UNSET,
352    ) -> Callable[[Callable[P, F]], Callable[P, F]]:
353        """Insert a config value into **kwargs to the wrapped method/function using this descriptor.
354
355        Use kwarg.get(`name`) to get the value.
356        `name` is the name the kwarg gets if passed, if None, it will be the same as `setting`.
357        Section parameter is just for finding the config value.
358        """
359        if name is None:
360            name = setting
361        if default is UNSET and not cls._parser.has_option(section, setting):
362            msg = f"Config value {section=} {setting=} is not set. and no default value is given."
363            raise ValueError(msg)
364
365        def wrapper(func: Callable[P, F]) -> Callable[P, F]:
366            @wraps(func)
367            def inner(*args: P.args, **kwargs: P.kwargs) -> F:
368                if default is not UNSET:
369                    cls._set_default(section, setting, default)
370                kwargs[name] = cls._parser.get(section, setting)
371                return func(*args, **kwargs)
372
373            return inner
374        return wrapper
375
376    @classmethod
377    def _set_default(cls, section: str, setting: str, value: VT) -> None:
378        if cls._parser.get(section, setting, fallback=UNSET) is UNSET:
379            cls._set(section, setting, value)
380
381    @classmethod
382    def default(cls, section: str, setting: str, value: VT) -> Callable[[Callable[P, F]], Callable[P, F]]:
383        """Set a default config value if none are set yet using this descriptor."""
384        def wrapper(func: Callable[P, F]) -> Callable[P, F]:
385            @wraps(func)
386            def inner(*args: P.args, **kwargs: P.kwargs) -> F:
387                cls._set_default(section, setting, value)
388                return func(*args, **kwargs)
389
390            return inner
391        return wrapper
392
393    @abstractmethod
394    def on_file_change(self, origin: Literal["get", "set"], old: VT | UNSET, new: VT) -> None:
395        """Triggered when the config file changes.
396
397        This needs to be implemented before it's usable.
398        This will be called **before** setting the value from the config file.
399        This will be called **after** getting (but before validating it's type) the value from config file.
400        The `origin` parameter indicates whether the change was triggered by a `get` or `set` operation.
401        """

37class ConfigContainerMeta(type):
38    """Metaclass for Config to "force" __set__ to be called on class variables."""
39
40    def __setattr__(cls, key: str, value: object) -> None:
41        """Set the value of the attribute on the class."""
42        attr = cls.__dict__.get(key)
43        if isinstance(attr, Config):
44            attr.__set__(cls, value)
45        else:
46            super().__setattr__(key, value)

14class ConfigPathConflictError(ValueError):
15    """Raised when a configuration path conflicts with an existing scalar value.
16
17    This occurs when attempting to treat a scalar value as a section (dict).
18    For example, if "Parent.Value" is a scalar, attempting to set "Parent.Value.Child"
19    would cause this error.
20    """

655class Date(BaseDataType[date]):
656    """A config value that is a date."""
657
658    @overload
659    def __init__(self, default: date = UNSET) -> None: ...
660    @overload
661    def __init__(self, **kwargs: Unpack[_DateKwargs]) -> None: ...
662
663    def __init__(self, default: date = UNSET, **kwargs: Unpack[_DateKwargs]) -> None:
664        """Initialize the date data type. Defaults to current date if not provided."""
665        if default is UNSET:
666            default = date(**kwargs)
667        super().__init__(default)
668
669    def convert(self, value: str) -> date:
670        """Convert a string value to a date."""
671        return date.fromisoformat(value)
672
673    def __str__(self) -> str:  # noqa: D105
674        return self.value.isoformat()

625class DateTime(BaseDataType[datetime]):
626    """A config value that is a datetime."""
627
628    @overload
629    def __init__(self, default: datetime = UNSET) -> None: ...
630    @overload
631    def __init__(self, **kwargs: Unpack[_DateTimeKwargs]) -> None: ...
632
633    def __init__(self, default: datetime = UNSET, **kwargs: Unpack[_DateTimeKwargs]) -> None:
634        """Initialize the datetime data type. Defaults to current datetime (datetime.now) if not provided."""
635        if default is UNSET:
636            try:
637                default = datetime(**kwargs)  # noqa: DTZ001 Tzinfo is (optionally) passed using kwargs
638            except TypeError:
639                default = datetime.now(tz=UTC)
640        super().__init__(default)
641
642    def convert(self, value: str) -> datetime:
643        """Convert a string value to a datetime."""
644        return datetime.fromisoformat(value)
645
646    def __str__(self) -> str:
647        """Return the string representation of the stored value."""
648        return self.value.isoformat()