confkit

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

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

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

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)

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

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

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