1"""Define the base `Settings` class."""
  2from __future__ import annotations
  3
  4# stdlib
  5import json
  6import logging
  7import os
  8import sys
  9import types
 10from dataclasses import dataclass
 11from pathlib import Path
 12from typing import Any, Iterable
 13
 14# third party
 15import yaml
 16
 17# local
 18from pyspry.nested_dict import NestedDict
 19
 20__all__ = ["ModuleContainer", "Null", "Settings"]
 21
 22logger = logging.getLogger(__name__)
 23
 24
 25class NullMeta(type):
 26    """Classes using this ``metaclass`` return themselves for every operation / interaction."""
 27
 28    def _null_operator(cls, *__o: Any) -> NullMeta:
 29        return cls
 30
 31    __add__ = _null_operator
 32
 33    def __bool__(cls) -> bool:
 34        # noqa: D105  # docstring -> noise for this method
 35        return bool(None)
 36
 37    def __call__(cls, *args: Any, **kwargs: Any) -> NullMeta:
 38        # noqa: D102  # docstring -> noise for this method
 39        return cls
 40
 41    __div__ = _null_operator
 42
 43    def __eq__(cls, __o: object) -> bool:
 44        """Check ``cls`` for equivalence, as well as ``None``."""
 45        return __o is cls or __o is None
 46
 47    def __getattr__(cls, __name: str) -> NullMeta:
 48        """Unless `__name` starts with `_`, return the `NullMeta` class instance.
 49
 50        The check for a `_` prefix allows Python's internal mechanics (such as the `__dict__`
 51        or `__doc__` attributes) to function correctly.
 52        """
 53        if __name.startswith("_"):
 54            return super().__getattribute__(__name)  # type: ignore[no-any-return]
 55        return cls._null_operator(__name)
 56
 57    __getitem__ = _null_operator
 58    __mod__ = _null_operator
 59    __mul__ = _null_operator
 60    __or__ = _null_operator  # type: ignore[assignment]
 61    __radd__ = _null_operator
 62    __rmod__ = _null_operator
 63    __rmul__ = _null_operator
 64    __rsub__ = _null_operator
 65    __rtruediv__ = _null_operator
 66    __sub__ = _null_operator
 67    __truediv__ = _null_operator
 68
 69    def __new__(cls: type, name: str, bases: tuple[type], dct: dict[str, Any]) -> Any:
 70        """Create new `class` instances from this `metaclass`."""
 71        return super().__new__(cls, name, bases, dct)  # type: ignore[misc]
 72
 73    def __repr__(cls) -> str:
 74        # noqa: D105  # docstring -> noise for this method
 75        return "Null"
 76
 77
 78class Null(metaclass=NullMeta):
 79    """Define a class which returns itself for all interactions.
 80
 81    >>> Null == None, Null is None
 82    (True, False)
 83
 84    >>> for result in [
 85    ...     Null(),
 86    ...     Null[0],
 87    ...     Null["any-key"],
 88    ...     Null.any_attr,
 89    ...     Null().any_attr,
 90    ...     Null + 5,
 91    ...     Null - 5,
 92    ...     Null * 5,
 93    ...     Null / 5,
 94    ...     Null % 5,
 95    ...     5 + Null,
 96    ...     5 - Null,
 97    ...     5 * Null,
 98    ...     5 / Null,
 99    ...     5 % Null,
100    ... ]:
101    ...     assert result is Null, result
102
103    >>> str(Null)
104    'Null'
105
106    >>> bool(Null)
107    False
108
109    Null is always false-y:
110
111    >>> Null or "None"
112    'None'
113    """
114
115
116@dataclass
117class ModuleContainer:
118    """Pair the instance of a module with its name."""
119
120    name: str
121    """Absolute import path of the module, e.g. `pyspry.settings`."""
122
123    module: types.ModuleType | None
124    """The module pulled from `sys.modules`, or `None` if it hadn't already been imported."""
125
126
127class Settings(types.ModuleType):
128    """Store settings from environment variables and a config file.
129
130    # Usage
131
132    >>> settings = Settings.load(config_path, prefix="APP_NAME")
133    >>> settings.APP_NAME_EXAMPLE_PARAM
134    'a string!'
135
136    ## Environment Variables
137
138    Monkeypatch an environment variable for this test:
139
140    >>> getfixture("monkey_example_param")  # use an env var to override the above setting
141    {'APP_NAME_EXAMPLE_PARAM': 'monkeypatched!'}
142
143    Setting an environment variable (above) can override specific settings values:
144
145    >>> settings = Settings.load(config_path, prefix="APP_NAME")
146    >>> settings.APP_NAME_EXAMPLE_PARAM
147    'monkeypatched!'
148
149    ## JSON Values
150
151    Environment variables in JSON format are parsed:
152
153    >>> list(settings.APP_NAME_ATTR_A)
154    [1, 2, 3]
155
156    >>> getfixture("monkey_attr_a")    # override an environment variable
157    {'APP_NAME_ATTR_A': '[4, 5, 6]'}
158
159    >>> settings = Settings.load(config_path, prefix="APP_NAME")    # and reload the settings
160    >>> list(settings.APP_NAME_ATTR_A)
161    [4, 5, 6]
162
163    To list all settings, use the built-in `dir()` function:
164
165    >>> dir(settings)
166    ['ATTR_A', 'ATTR_A_0', 'ATTR_A_1', 'ATTR_A_2', 'ATTR_B', 'ATTR_B_K', 'EXAMPLE_PARAM']
167
168    """  # noqa: F821
169
170    __config: NestedDict
171    """Store the config file contents as a `NestedDict` object."""
172
173    prefix: str
174    """Only load settings whose names start with this prefix."""
175
176    module_container: ModuleContainer | type[Null] = Null
177    """This property is set by the `Settings.bootstrap()` method and removed by
178    `Settings.restore()`"""
179
180    def __init__(self, config: dict[str, Any], environ: dict[str, str], prefix: str) -> None:
181        """Deserialize all JSON-encoded environment variables during initialization.
182
183        Args:
184            config (builtins.dict[builtins.str, typing.Any]): the values loaded from a JSON/YAML
185                file
186            environ (builtins.dict[builtins.str, typing.Any]): override config settings with these
187                environment variables
188            prefix (builtins.str): insert / strip this prefix when needed
189
190        The `prefix` is automatically added when accessing attributes:
191
192        >>> settings = Settings({"APP_NAME_EXAMPLE_PARAM": 0}, {}, prefix="APP_NAME")
193        >>> settings.APP_NAME_EXAMPLE_PARAM == settings.EXAMPLE_PARAM == 0
194        True
195        """  # noqa: RST203
196        self.__config = NestedDict(config)
197        env: dict[str, Any] = {}
198        for key, value in environ.items():
199            try:
200                parsed = json.loads(value)
201            except json.JSONDecodeError:
202                # the value must just be a simple string
203                parsed = value
204
205            if isinstance(parsed, (dict, list)):
206                env[key] = NestedDict(parsed)
207            else:
208                env[key] = parsed
209
210        self.__config |= NestedDict(env)
211        self.prefix = prefix
212
213    def __contains__(self, obj: Any) -> bool:
214        """Check the merged `NestedDict` config for a setting with the given name.
215
216        Keys must be strings to avoid unexpected behavior.
217
218        >>> settings = Settings({20: "oops", "20": "okay"}, environ={}, prefix="")
219        >>> "20" in settings
220        True
221        >>> 20 in settings
222        False
223        """
224        if not isinstance(obj, str):
225            return False
226        return self.maybe_add_prefix(obj) in self.__config
227
228    def __dir__(self) -> Iterable[str]:
229        """Return a set of the names of all settings provided by this object."""
230        return {self.__config.maybe_strip(self.prefix, key) for key in self.__config.keys()}.union(
231            self.__config.maybe_strip(self.prefix, key) for key in self.__config
232        )
233
234    def __getattr__(self, name: str) -> Any:
235        """Prioritize retrieving values from environment variables, falling back to the file config.
236
237        Args:
238            name (str): the name of the setting to retrieve
239
240        Returns:
241            `Any`: the value of the setting
242        """
243        try:
244            return self.__getattr_override(name)
245        except (AttributeError, TypeError):
246            return self.__getattr_base(name)
247
248    def __getattr_base(self, name: str) -> Any:
249        try:
250            return super().__getattribute__(name)
251        except AttributeError:
252            pass
253
254        try:
255            return getattr(self.module_container.module, name)
256        except AttributeError:
257            pass
258
259        raise AttributeError(f"'{self.__class__.__name__}' object has no attribute '{name}'")
260
261    def __getattr_override(self, name: str) -> Any:
262        attr_name = self.maybe_add_prefix(name)
263
264        try:
265            attr_val = self.__config[attr_name]
266        except KeyError as e:
267            raise AttributeError(
268                f"'{self.__class__.__name__}' object has no attribute '{attr_name}'"
269            ) from e
270
271        return (
272            attr_val.serialize(strip_prefix=self.prefix)
273            if isinstance(attr_val, NestedDict)
274            else attr_val
275        )
276
277    def bootstrap(self, module_name: str) -> types.ModuleType | None:
278        """Store the named module object, replacing it with `self` to bootstrap the import mechanic.
279
280        This object will replace the named module in `sys.modules`.
281
282        Args:
283            module_name (builtins.str): the name of the module to replace
284
285        Returns:
286            typing.Optional[types.ModuleType]: the module object that was replaced, or `None` if the
287                module wasn't already in `sys.modules`
288        """
289        logger.info("replacing module '%s' with self", module_name)
290        try:
291            replaced_module = sys.modules[module_name]
292        except KeyError:
293            replaced_module = None
294        self.module_container = ModuleContainer(name=module_name, module=replaced_module)
295        sys.modules[module_name] = self
296        return replaced_module
297
298    @classmethod
299    def load(cls, file_path: Path | str, prefix: str | None = None) -> Settings:
300        """Load the specified configuration file and environment variables.
301
302        Args:
303            file_path (pathlib.Path | builtins.str): the path to the config file to load
304            prefix (typing.Optional[builtins.str]): if provided, parse all env variables containing
305                this prefix
306
307        Returns:
308            pyspry.base.Settings: the `Settings` object loaded from file with environment variable
309                overrides
310        """  # noqa: RST301
311        with Path(file_path).open("r", encoding="UTF-8") as f:
312            config_data = {
313                str(key): value
314                for key, value in yaml.safe_load(f).items()
315                if not prefix or str(key).startswith(f"{prefix}{NestedDict.sep}")
316            }
317
318        if prefix:
319            environ = {
320                key: value
321                for key, value in os.environ.items()
322                if key.startswith(f"{prefix}{NestedDict.sep}")
323            }
324        else:
325            environ = {}
326
327        return cls(config_data, environ, prefix or "")
328
329    def maybe_add_prefix(self, name: str) -> str:
330        """If the given name is missing the prefix configured for these settings, insert it.
331
332        Args:
333            name (builtins.str): the attribute / key name to massage
334
335        Returns:
336            builtins.str: the name with the prefix inserted `iff` the prefix was missing
337        """
338        if not name.startswith(self.prefix):
339            return f"{self.prefix}{self.__config.sep}{name}"
340        return name
341
342    def restore(self) -> types.ModuleType | None:
343        """Remove `self` from `sys.modules` and restore the module that was bootstrapped.
344
345        When a module is bootstrapped, it is replaced by a `Settings` object:
346
347        >>> type(sys.modules["pyspry.settings"])
348        <class 'pyspry.base.Settings'>
349
350        Calling this method reverts the bootstrapping:
351
352        >>> mod = settings.restore()
353        >>> type(sys.modules["pyspry.settings"])
354        <class 'module'>
355
356        >>> mod is sys.modules["pyspry.settings"]
357        True
358        """  # noqa: F821
359        if self.module_container is Null:
360            return None
361
362        module_container: ModuleContainer = self.module_container  # type: ignore[assignment]
363
364        module_name, module = module_container.name, module_container.module
365        self.module_container = Null
366
367        logger.info("restoring '%s' and removing self from `sys.modules`", module_name)
368
369        if not module:
370            del sys.modules[module_name]
371        else:
372            sys.modules[module_name] = module
373
374        return module
375
376
377logger.debug("successfully imported %s", __name__)