circup 2.2.3__tar.gz → 2.2.5__tar.gz

{circup-2.2.3 → circup-2.2.5}/.gitignore

@@ -115,6 +115,9 @@ venv.bak/
 # VSCode
 .vscode/
 
+# Zed
+.zed/
+
 .DS_STORE
 
 # emacs

{circup-2.2.3/circup.egg-info → circup-2.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: circup
-Version: 2.2.3
+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.3 → circup-2.2.5}/circup/command_utils.py

@@ -841,3 +841,15 @@ def sorted_by_directory_then_alpha(list_of_files):
         sorted_full_list.append(files[cur_name])
 
     return sorted_full_list
+
+
+def is_virtual_env_active():
+    """
+    Check if a virtual environment is currently active.
+
+    We don't check the more commonly recommended way of checking if
+    sys.prefix != sys.base_prefix as this will always be true if running circup
+    from a pipx install. This way ensures the user manually activated a
+    virtual environment, regardless how circup is installed.
+    """
+    return "VIRTUAL_ENV" in os.environ

{circup-2.2.3 → circup-2.2.5}/circup/commands.py

@@ -41,6 +41,7 @@ from circup.command_utils import (
     get_bundles_dict,
     completion_for_example,
     get_bundle_examples,
+    is_virtual_env_active,
 )
 
 
@@ -354,6 +355,7 @@ def install(
     device_modules = ctx.obj["backend"].get_device_versions()
     if to_install is not None:
         to_install = sorted(to_install)
+        is_global_install_ok = None
         click.echo(f"Ready to install: {to_install}\n")
         for library in to_install:
             ctx.obj["backend"].install_module(
@@ -366,6 +368,26 @@ def install(
             )
 
             if stubs:
+                # Check we are in a virtual environment
+                if not is_virtual_env_active():
+                    if is_global_install_ok is None:
+                        click.secho(
+                            (
+                                "No virtual environment detected.\n"
+                                "It is recommended to run circup inside a virtual environment "
+                                "when installing stubs. Without a virtual environment, the stubs "
+                                "will be installed to the global python."
+                            ),
+                            fg="yellow",
+                        )
+                        is_global_install_ok = click.confirm(
+                            click.style(
+                                "Would you still like to install stubs (to the global python)?",
+                                fg="yellow",
+                            )
+                        )
+                    if not is_global_install_ok:
+                        continue
                 library_stubs = "adafruit-circuitpython-{}".format(
                     library.replace("adafruit_", "")
                 )

circup-2.2.5/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-2.2.3 → circup-2.2.5}/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.3 → circup-2.2.5/circup.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: circup
-Version: 2.2.3
+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.3 → circup-2.2.5}/circup.egg-info/SOURCES.txt

@@ -27,6 +27,7 @@ circup/backends.py
 circup/bundle.py
 circup/command_utils.py
 circup/commands.py
+circup/lazy_metadata.py
 circup/logging.py
 circup/module.py
 circup/shared.py