|
| 1 | +# SPDX-FileCopyrightText: 2025 George Waters |
| 2 | +# |
| 3 | +# SPDX-License-Identifier: MIT |
| 4 | +""" |
| 5 | +Class that acts similar to a dictionary, but defers the loading of expensive |
| 6 | +data until that data is accessed. |
| 7 | +""" |
| 8 | +from typing import Any, Callable |
| 9 | + |
| 10 | + |
| 11 | +class LazyMetadata: |
| 12 | + """ |
| 13 | + Dictionary like class that stores module metadata. Expensive to load |
| 14 | + metadata won't be loaded until it is accessed. |
| 15 | + """ |
| 16 | + |
| 17 | + def __init__( |
| 18 | + self, |
| 19 | + deferred_load: Callable[[], dict[str, Any]], |
| 20 | + initial_data: dict[str, Any] | None = None, |
| 21 | + ): |
| 22 | + """ |
| 23 | + Initialize a LazyMetadata object by providing a callable and initial |
| 24 | + data. |
| 25 | +
|
| 26 | + :param deferred_load: A callable that returns a dictionary of metadata. |
| 27 | + This is not invoked until a key is accessed that is not available in |
| 28 | + :py:attr:`initial_data`. |
| 29 | + :param initial_data: A dictionary containing the initial metadata. |
| 30 | + """ |
| 31 | + self._deferred_load = deferred_load |
| 32 | + self.initial_data = initial_data.copy() if initial_data is not None else {} |
| 33 | + self._deferred_data: dict[str, Any] | None = None |
| 34 | + |
| 35 | + @property |
| 36 | + def deferred_data(self) -> dict[str, Any]: |
| 37 | + """ |
| 38 | + Lazy load the metadata from :py:attr:`_deferred_load`. |
| 39 | +
|
| 40 | + :return: The "expensive" metadata that was loaded from |
| 41 | + :py:attr:`_deferred_load`. |
| 42 | + """ |
| 43 | + if self._deferred_data is None: |
| 44 | + self._deferred_data = self._deferred_load() |
| 45 | + return self._deferred_data |
| 46 | + |
| 47 | + def __getitem__(self, key: str) -> Any: |
| 48 | + """ |
| 49 | + Get items via keyed index lookup, like a dictionary. |
| 50 | +
|
| 51 | + Keys are first looked for in :py:attr:`initial_data`, if the key isn't |
| 52 | + found it is then looked for in :py:attr:`deferred_data`. |
| 53 | +
|
| 54 | + :param key: Key to a metadata value. |
| 55 | + :return: Metadata value for the given key. |
| 56 | + :raises KeyError: If the key cannot be found. |
| 57 | + """ |
| 58 | + if key in self.initial_data: # pylint: disable=no-else-return |
| 59 | + return self.initial_data[key] |
| 60 | + elif key in self.deferred_data: |
| 61 | + return self.deferred_data[key] |
| 62 | + raise KeyError(key) |
| 63 | + |
| 64 | + def __setitem__(self, key: str, item: Any) -> None: |
| 65 | + """ |
| 66 | + Sets the item under the given key. |
| 67 | +
|
| 68 | + The item is set in the :py:attr:`initial_data` dictionary. |
| 69 | +
|
| 70 | + :param key: Key to a metadata value. |
| 71 | + :param item: Metadata value |
| 72 | + """ |
| 73 | + self.initial_data[key] = item |
| 74 | + |
| 75 | + def __contains__(self, key: str): |
| 76 | + """ |
| 77 | + Whether or not a key is present. |
| 78 | +
|
| 79 | + This checks both :py:attr:`initial_data` and :py:attr:`deferred_data` |
| 80 | + for the key. *Note* this will cause :py:attr:`deferred_data` to load |
| 81 | + the deferred data if it is not already. |
| 82 | + """ |
| 83 | + return key in self.initial_data or key in self.deferred_data |
| 84 | + |
| 85 | + def get(self, key: str, default: Any = None): |
| 86 | + """ |
| 87 | + Get items via keyed index lookup, like a dictionary. |
| 88 | +
|
| 89 | + Also like a dictionary, this method doesn't error if the key is not |
| 90 | + found. :param default: is returned if the key is not found. |
| 91 | +
|
| 92 | + :param key: Key to a metadata value. |
| 93 | + :param default: Default value to return when the key doesn't exist. |
| 94 | + :return: Metadata value for the given key. |
| 95 | + """ |
| 96 | + if key in self: |
| 97 | + return self[key] |
| 98 | + return default |
| 99 | + |
| 100 | + def __repr__(self) -> str: |
| 101 | + """ |
| 102 | + Helps with log files. |
| 103 | +
|
| 104 | + :return: A repr of a dictionary containing the metadata's values. |
| 105 | + """ |
| 106 | + return repr( |
| 107 | + { |
| 108 | + "initial_data": self.initial_data, |
| 109 | + "deferred_data": self._deferred_data |
| 110 | + if self._deferred_data is not None |
| 111 | + else "<Not Loaded>", |
| 112 | + } |
| 113 | + ) |
0 commit comments