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)

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

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

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()