circup 2.2.4__py3-none-any.whl → 2.2.5__py3-none-any.whl

circup/lazy_metadata.py

@@ -0,0 +1,113 @@
+# SPDX-FileCopyrightText: 2025 George Waters
+#
+# SPDX-License-Identifier: MIT
+"""
+Class that acts similar to a dictionary, but defers the loading of expensive
+data until that data is accessed.
+"""
+from typing import Any, Callable
+
+
+class LazyMetadata:
+    """
+    Dictionary like class that stores module metadata. Expensive to load
+    metadata won't be loaded until it is accessed.
+    """
+
+    def __init__(
+        self,
+        deferred_load: Callable[[], dict[str, Any]],
+        initial_data: dict[str, Any] | None = None,
+    ):
+        """
+        Initialize a LazyMetadata object by providing a callable and initial
+        data.
+
+        :param deferred_load: A callable that returns a dictionary of metadata.
+        This is not invoked until a key is accessed that is not available in
+        :py:attr:`initial_data`.
+        :param initial_data: A dictionary containing the initial metadata.
+        """
+        self._deferred_load = deferred_load
+        self.initial_data = initial_data.copy() if initial_data is not None else {}
+        self._deferred_data: dict[str, Any] | None = None
+
+    @property
+    def deferred_data(self) -> dict[str, Any]:
+        """
+        Lazy load the metadata from :py:attr:`_deferred_load`.
+
+        :return: The "expensive" metadata that was loaded from
+        :py:attr:`_deferred_load`.
+        """
+        if self._deferred_data is None:
+            self._deferred_data = self._deferred_load()
+        return self._deferred_data
+
+    def __getitem__(self, key: str) -> Any:
+        """
+        Get items via keyed index lookup, like a dictionary.
+
+        Keys are first looked for in :py:attr:`initial_data`, if the key isn't
+        found it is then looked for in :py:attr:`deferred_data`.
+
+        :param key: Key to a metadata value.
+        :return: Metadata value for the given key.
+        :raises KeyError: If the key cannot be found.
+        """
+        if key in self.initial_data:  # pylint: disable=no-else-return
+            return self.initial_data[key]
+        elif key in self.deferred_data:
+            return self.deferred_data[key]
+        raise KeyError(key)
+
+    def __setitem__(self, key: str, item: Any) -> None:
+        """
+        Sets the item under the given key.
+
+        The item is set in the :py:attr:`initial_data` dictionary.
+
+        :param key: Key to a metadata value.
+        :param item: Metadata value
+        """
+        self.initial_data[key] = item
+
+    def __contains__(self, key: str):
+        """
+        Whether or not a key is present.
+
+        This checks both :py:attr:`initial_data` and :py:attr:`deferred_data`
+        for the key. *Note* this will cause :py:attr:`deferred_data` to load
+        the deferred data if it is not already.
+        """
+        return key in self.initial_data or key in self.deferred_data
+
+    def get(self, key: str, default: Any = None):
+        """
+        Get items via keyed index lookup, like a dictionary.
+
+        Also like a dictionary, this method doesn't error if the key is not
+        found. :param default: is returned if the key is not found.
+
+        :param key: Key to a metadata value.
+        :param default: Default value to return when the key doesn't exist.
+        :return: Metadata value for the given key.
+        """
+        if key in self:
+            return self[key]
+        return default
+
+    def __repr__(self) -> str:
+        """
+        Helps with log files.
+
+        :return: A repr of a dictionary containing the metadata's values.
+        """
+        return repr(
+            {
+                "initial_data": self.initial_data,
+                "deferred_data": self._deferred_data
+                if self._deferred_data is not None
+                else "<Not Loaded>",
+            }
+        )

circup/shared.py

@@ -14,6 +14,8 @@ import importlib.resources
 import appdirs
 import requests
 
+from circup.lazy_metadata import LazyMetadata
+
 #: Version identifier for a bad MPY file format
 BAD_FILE_FORMAT = "Invalid"
 
@@ -51,7 +53,7 @@ NOT_MCU_LIBRARIES = [
 BOARDLESS_COMMANDS = ["show", "bundle-add", "bundle-remove", "bundle-show"]
 
 
-def _get_modules_file(path, logger):
+def _get_modules_file(path, logger):  # pylint: disable=too-many-locals
     """
     Get a dictionary containing metadata about all the Python modules found in
     the referenced file system path.
@@ -71,8 +73,10 @@ def _get_modules_file(path, logger):
     ]
     single_file_mods = single_file_py_mods + single_file_mpy_mods
     for sfm in [f for f in single_file_mods if not os.path.basename(f).startswith(".")]:
-        metadata = extract_metadata(sfm, logger)
-        metadata["path"] = sfm
+        default_metadata = {"path": sfm, "mpy": sfm.endswith(".mpy")}
+        metadata = LazyMetadata(
+            lambda sfm=sfm: extract_metadata(sfm, logger), default_metadata
+        )
         result[os.path.basename(sfm).replace(".py", "").replace(".mpy", "")] = metadata
     for package_path in package_dir_mods:
         name = os.path.basename(os.path.dirname(package_path))
@@ -81,19 +85,27 @@ def _get_modules_file(path, logger):
         all_files = py_files + mpy_files
         # put __init__ first if any, assumed to have the version number
         all_files.sort()
+
+        def get_metadata(all_files=all_files):  # capture all_files
+            selected_metadata = {}
+            # explore all the submodules to detect bad ones
+            for source in [
+                f for f in all_files if not os.path.basename(f).startswith(".")
+            ]:
+                metadata = extract_metadata(source, logger)
+                if "__version__" in metadata:
+                    # don't replace metadata if already found
+                    if "__version__" not in selected_metadata:
+                        selected_metadata = metadata
+                    # break now if any of the submodules has a bad format
+                    if metadata["__version__"] == BAD_FILE_FORMAT:
+                        break
+            return selected_metadata
+
         # default value
-        result[name] = {"path": package_path, "mpy": bool(mpy_files)}
-        # explore all the submodules to detect bad ones
-        for source in [f for f in all_files if not os.path.basename(f).startswith(".")]:
-            metadata = extract_metadata(source, logger)
-            if "__version__" in metadata:
-                # don't replace metadata if already found
-                if "__version__" not in result[name]:
-                    metadata["path"] = package_path
-                    result[name] = metadata
-                # break now if any of the submodules has a bad format
-                if metadata["__version__"] == BAD_FILE_FORMAT:
-                    break
+        default_metadata = {"path": package_path, "mpy": bool(mpy_files)}
+        metadata = LazyMetadata(get_metadata, default_metadata)
+        result[name] = metadata
     return result
 
 

{circup-2.2.4.dist-info → circup-2.2.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: circup
-Version: 2.2.4
+Version: 2.2.5
 Summary: A tool to manage/update libraries on CircuitPython devices.
 Author-email: Adafruit Industries <circuitpython@adafruit.com>
 License: MIT License

{circup-2.2.4.dist-info → circup-2.2.5.dist-info}/RECORD

@@ -3,18 +3,19 @@ circup/backends.py,sha256=g9Q9xCGZidwsEDL2Ga2cm50YYB54IiqlKUPcxj-pWZA,40008
 circup/bundle.py,sha256=FEP4F470aJtwmm8jgTM3DgR3dj5SVwbX1tbyIRKVHn8,5327
 circup/command_utils.py,sha256=FNEhTYbbCT9UzKv4NG5lhbWHlObSEl4DQ7iDd8O0-cs,30581
 circup/commands.py,sha256=jrgJDmqx4U1K--_OnZoOt1d9n1QRNnInK_nBeWrThMw,28542
+circup/lazy_metadata.py,sha256=69VidxGGWE13QwAAtMCPNTXTsQ2q5dJvMtclw4YaqEY,3764
 circup/logging.py,sha256=hu4v8ljkXo8ru-cqs0W3PU-xEVvTO_qqMKDJM18OXbQ,1115
 circup/module.py,sha256=33_kdy5BZn6COyIjAFZMpw00rTtPiryQZWFXQkMF8FY,7435
-circup/shared.py,sha256=IBW3v0rry1wLr8yR8_xHfe0QC5SFGzv6bdnPv96vZaM,8944
+circup/shared.py,sha256=rribEZdoeyZRHxLiezyrDH0vb8DIP4bGOfMpRJm9M9w,9405
 circup/config/bundle_config.json,sha256=zzpmfy0jD7TxpOOw2P_gqIISuMBG0enb_f3_VneQ5mI,135
 circup/config/bundle_config.json.license,sha256=OOHNqDsViGFhmG9z8J0o98hYmub1CkYKiZB96Php6KE,80
 circup/wwshell/README.rst,sha256=M_jFP0hwOcngF0RdosdeqmVOISNcPzyjTW3duzIu9A8,3617
 circup/wwshell/README.rst.license,sha256=GhA0SoZGP7CReDam-JJk_UtIQIpQaZWQFzR26YSuMm4,107
 circup/wwshell/__init__.py,sha256=CAPZiYrouWboyPx4KiWLBG_vf_n0MmArGqaFyTXGKWk,398
 circup/wwshell/commands.py,sha256=-I5l7XeoDmvWWuZg5wHdt9qe__SBQ1EGmKwCDTBMeus,7454
-circup-2.2.4.dist-info/licenses/LICENSE,sha256=bVlIMmSL_pqLCqae4hzixy9pYXD808IbgsMoQXTNLBk,1076
-circup-2.2.4.dist-info/METADATA,sha256=DmXRgPwq1G5-zZoilQRa6vtK1eP3clouiQy4LOt0teA,13617
-circup-2.2.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-circup-2.2.4.dist-info/entry_points.txt,sha256=FjTmwYD_ApgLRGifUrr_Ui1voW6fEzodQc3DKNzoAPc,69
-circup-2.2.4.dist-info/top_level.txt,sha256=Qx6E0eZgSBE10ciNKsLZx8-TTy_9fEVZh7NLmn24KcU,7
-circup-2.2.4.dist-info/RECORD,,
+circup-2.2.5.dist-info/licenses/LICENSE,sha256=bVlIMmSL_pqLCqae4hzixy9pYXD808IbgsMoQXTNLBk,1076
+circup-2.2.5.dist-info/METADATA,sha256=c-lndR68LWDH1jMrnUFp4Lhscjx5pFAtvyWm-i9Z5aA,13617
+circup-2.2.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+circup-2.2.5.dist-info/entry_points.txt,sha256=FjTmwYD_ApgLRGifUrr_Ui1voW6fEzodQc3DKNzoAPc,69
+circup-2.2.5.dist-info/top_level.txt,sha256=Qx6E0eZgSBE10ciNKsLZx8-TTy_9fEVZh7NLmn24KcU,7
+circup-2.2.5.dist-info/RECORD,,