circup 2.2.6__py3-none-any.whl → 2.4.0__py3-none-any.whl

circup/backends.py

@@ -197,7 +197,9 @@ class Backend:
             # Create the library directory first.
             self.create_directory(device_path, library_path)
             if local_path is None:
-                if pyext:
+                # Fallback to the source version (py) if the bundle doesn't have
+                # a compiled version (mpy)
+                if pyext or bundle.platform is None:
                     # Use Python source for module.
                     self.install_module_py(metadata)
                 else:
@@ -648,9 +650,7 @@ class WebBackend(Backend):
         if not module_name:
             # Must be a directory based module.
             module_name = os.path.basename(os.path.dirname(metadata["path"]))
-        major_version = self.get_circuitpython_version()[0].split(".")[0]
-        bundle_platform = "{}mpy".format(major_version)
-        bundle_path = os.path.join(bundle.lib_dir(bundle_platform), module_name)
+        bundle_path = os.path.join(bundle.lib_dir(), module_name)
         if os.path.isdir(bundle_path):
 
             self.install_dir_http(bundle_path)
@@ -920,9 +920,7 @@ class DiskBackend(Backend):
             # Must be a directory based module.
             module_name = os.path.basename(os.path.dirname(metadata["path"]))
 
-        major_version = self.get_circuitpython_version()[0].split(".")[0]
-        bundle_platform = "{}mpy".format(major_version)
-        bundle_path = os.path.join(bundle.lib_dir(bundle_platform), module_name)
+        bundle_path = os.path.join(bundle.lib_dir(), module_name)
         if os.path.isdir(bundle_path):
             target_path = os.path.join(self.library_path, module_name)
             # Copy the directory.

circup/bundle.py

@@ -10,22 +10,26 @@ import sys
 import click
 import requests
 
+from semver import VersionInfo
+
 from circup.shared import (
     DATA_DIR,
     PLATFORMS,
     REQUESTS_TIMEOUT,
-    tags_data_load,
     get_latest_release_from_url,
 )
 
 from circup.logging import logger
 
 
-class Bundle:
+class Bundle:  # pylint: disable=too-many-instance-attributes
     """
     All the links and file names for a bundle
     """
 
+    #: Avoid requests to the internet
+    offline = False
+
     def __init__(self, repo):
         """
         Initialise a Bundle created from its github info.
@@ -46,29 +50,42 @@ class Bundle:
         # tag
         self._current = None
         self._latest = None
+        self.pinned_tag = None
+        self._available = []
+        #
+        self.platform = None
 
-    def lib_dir(self, platform):
+    def lib_dir(self, source=False):
         """
-        This bundle's lib directory for the platform.
+        This bundle's lib directory for the bundle's source or compiled version.
 
-        :param str platform: The platform identifier (py/6mpy/...).
-        :return: The path to the lib directory for the platform.
+        :param bool source: Whether to return the path to the source lib
+        directory or to :py:attr:`self.platform`'s lib directory. If `source` is
+        `False` but :py:attr:`self.platform` is None, the source lib directory
+        will be returned instead.
+        :return: The path to the lib directory.
         """
         tag = self.current_tag
+        platform = "py" if source or not self.platform else self.platform
         return os.path.join(
             self.dir.format(platform=platform),
             self.basename.format(platform=PLATFORMS[platform], tag=tag),
             "lib",
         )
 
-    def examples_dir(self, platform):
+    def examples_dir(self, source=False):
         """
-        This bundle's examples directory for the platform.
+        This bundle's examples directory for the bundle's source or compiled
+        version.
 
-        :param str platform: The platform identifier (py/6mpy/...).
-        :return: The path to the examples directory for the platform.
+        :param bool source: Whether to return the path to the source examples
+        directory or to :py:attr:`self.platform`'s examples directory. If
+        `source` is `False` but :py:attr:`self.platform` is None, the source
+        examples directory will be returned instead.
+        :return: The path to the examples directory.
         """
         tag = self.current_tag
+        platform = "py" if source or not self.platform else self.platform
         return os.path.join(
             self.dir.format(platform=platform),
             self.basename.format(platform=PLATFORMS[platform], tag=tag),
@@ -99,21 +116,34 @@ class Bundle:
     @property
     def current_tag(self):
         """
-        Lazy load current cached tag from the BUNDLE_DATA json file.
+        The current tag for the project. If the tag hasn't been explicitly set
+        this will be the pinned tag, if one is set and it is available. If there
+        is no pinned tag, this will be the latest available tag that is locally
+        available.
 
-        :return: The current cached tag value for the project.
+        :return: The current tag value for the project.
         """
         if self._current is None:
-            self._current = tags_data_load(logger).get(self.key, "0")
+            if self.pinned_tag:
+                self._current = (
+                    self.pinned_tag if self.pinned_tag in self._available else None
+                )
+            else:
+                self._current = (
+                    # This represents the latest version locally available
+                    self._available[-1]
+                    if len(self._available) > 0
+                    else None
+                )
+
         return self._current
 
     @current_tag.setter
     def current_tag(self, tag):
         """
-        Set the current cached tag (after updating).
+        Set the current tag (after updating).
 
         :param str tag: The new value for the current tag.
-        :return: The current cached tag value for the project.
         """
         self._current = tag
 
@@ -125,31 +155,109 @@ class Bundle:
         :return: The most recent tag value for the project.
         """
         if self._latest is None:
-            self._latest = get_latest_release_from_url(
-                self.url + "/releases/latest", logger
-            )
+            if self.offline:
+                self._latest = self._available[-1] if len(self._available) > 0 else None
+            else:
+                self._latest = get_latest_release_from_url(
+                    self.url + "/releases/latest", logger
+                )
         return self._latest
 
+    @property
+    def available_tags(self):
+        """
+        The locally available tags to use for the project.
+
+        :return: All tags available for the project.
+        """
+        return tuple(self._available)
+
+    @available_tags.setter
+    def available_tags(self, tags):
+        """
+        Set the available tags.
+
+        :param str|list tags: The new value for the locally available tags.
+        """
+        if isinstance(tags, str):
+            tags = [tags]
+
+        try:
+            tags = sorted(tags, key=self.parse_version)
+        except ValueError as ex:
+            logger.warning(
+                "Bundle '%s' has invalid tags, cannot order by version.", self.key
+            )
+            logger.warning(ex)
+        self._available = tags
+
+    def add_tag(self, tag: str) -> None:
+        """
+        Add a tag to the list of available tags.
+
+        This will add the tag if it isn't already present in the list of
+        available tags. The tag will be added so that the list is sorted in an
+        increasing order. This ensures that that last tag is always the latest.
+
+        :param str tag: The tag to add to the list of available tags.
+        """
+        if tag in self._available:
+            # The tag is already stored for some reason, lets not add it again
+            return
+
+        try:
+            version_tag = self.parse_version(tag)
+
+            for rev_i, available_tag in enumerate(reversed(self._available)):
+                available_version_tag = self.parse_version(available_tag)
+                if version_tag > available_version_tag:
+                    i = len(self._available) - rev_i
+                    self._available.insert(i, tag)
+                    break
+            else:
+                self._available.insert(0, tag)
+        except ValueError as ex:
+            logger.warning(
+                "Bundle tag '%s' is not a valid tag, cannot order by version.", tag
+            )
+            logger.warning(ex)
+            self._available.append(tag)
+
     def validate(self):
         """
-        Test the existence of the expected URLs (not their content)
+        Test the existence of the expected URL (not the content)
         """
         tag = self.latest_tag
         if not tag or tag == "releases":
             if "--verbose" in sys.argv:
                 click.secho(f'  Invalid tag "{tag}"', fg="red")
             return False
-        for platform in PLATFORMS.values():
-            url = self.url_format.format(platform=platform, tag=tag)
-            r = requests.get(url, stream=True, timeout=REQUESTS_TIMEOUT)
-            # pylint: disable=no-member
-            if r.status_code != requests.codes.ok:
-                if "--verbose" in sys.argv:
-                    click.secho(f"  Unable to find {os.path.split(url)[1]}", fg="red")
-                return False
-            # pylint: enable=no-member
+        url = self.url_format.format(platform="py", tag=tag)
+        r = requests.get(url, stream=True, timeout=REQUESTS_TIMEOUT)
+        # pylint: disable=no-member
+        if r.status_code != requests.codes.ok:
+            if "--verbose" in sys.argv:
+                click.secho(f"  Unable to find {os.path.split(url)[1]}", fg="red")
+            return False
+        # pylint: enable=no-member
         return True
 
+    @staticmethod
+    def parse_version(tag: str) -> VersionInfo:
+        """
+        Parse a tag to get a VersionInfo object.
+
+        `VersionInfo` objects are useful for ordering the tags from oldest to
+        newest in :py:attr:`self.available_tags`. The tags are stripped of a
+        leading 'v' (if one is present) and minor and patch components are
+        optional. This is to allow more flexibility with how a bundle is
+        versioned.
+
+        :param str tag: The tag to parse.
+        :return: A `VersionInfo` object parsed from the tag.
+        """
+        return VersionInfo.parse(tag.removeprefix("v"), optional_minor_and_patch=True)
+
     def __repr__(self):
         """
         Helps with log files.
@@ -166,5 +274,7 @@ class Bundle:
                 "url_format": self.url_format,
                 "current": self._current,
                 "latest": self._latest,
+                "pinned": self.pinned_tag,
+                "available": self._available,
             }
         )

circup/command_utils.py

@@ -12,10 +12,10 @@ import os
 
 from subprocess import check_output
 import sys
-import shutil
 import zipfile
 import json
 import re
+from pathlib import Path
 import toml
 import requests
 import click
@@ -23,13 +23,13 @@ import click
 from circup.shared import (
     PLATFORMS,
     REQUESTS_TIMEOUT,
+    SUPPORTED_PLATFORMS,
     _get_modules_file,
     BUNDLE_CONFIG_OVERWRITE,
     BUNDLE_CONFIG_FILE,
     BUNDLE_CONFIG_LOCAL,
     BUNDLE_DATA,
     NOT_MCU_LIBRARIES,
-    tags_data_load,
 )
 from circup.logging import logger
 from circup.module import Module
@@ -106,7 +106,7 @@ def completion_for_install(ctx, param, incomplete):
     with the ``circup install`` command.
     """
     # pylint: disable=unused-argument
-    available_modules = get_bundle_versions(get_bundles_list(), avoid_download=True)
+    available_modules = get_bundle_versions(get_bundles_list(None), avoid_download=True)
     module_names = {m.replace(".py", "") for m in available_modules}
     if incomplete:
         module_names = [name for name in module_names if name.startswith(incomplete)]
@@ -121,7 +121,9 @@ def completion_for_example(ctx, param, incomplete):
     """
 
     # pylint: disable=unused-argument, consider-iterating-dictionary
-    available_examples = get_bundle_examples(get_bundles_list(), avoid_download=True)
+    available_examples = get_bundle_examples(
+        get_bundles_list(None), avoid_download=True
+    )
     matching_examples = []
     for term in incomplete:
         _examples = [
@@ -134,41 +136,143 @@ def completion_for_example(ctx, param, incomplete):
     return sorted(matching_examples)
 
 
-def ensure_latest_bundle(bundle):
+def ensure_bundle_tag(bundle, tag):
     """
-    Ensure that there's a copy of the latest library bundle available so circup
-    can check the metadata contained therein.
+    Ensure that there's a copy of the library bundle with the version referenced
+    by the tag.
 
     :param Bundle bundle: the target Bundle object.
+    :param tag: the target bundle's tag (version).
+
+    :return: If the bundle is available.
     """
-    logger.info("Checking library updates for %s.", bundle.key)
-    tag = bundle.latest_tag
-    do_update = False
-    if tag == bundle.current_tag:
-        for platform in PLATFORMS:
-            # missing directories (new platform added on an existing install
-            # or side effect of pytest or network errors)
-            do_update = do_update or not os.path.isdir(bundle.lib_dir(platform))
+    if tag is None:
+        logger.warning("Bundle version requested is 'None'.")
+        return False
+
+    do_update_source = False
+    do_update_compiled = False
+    if tag in bundle.available_tags:
+        # missing directories (new platform added on an existing install
+        # or side effect of pytest or network errors)
+        # Check for the source
+        do_update_source = not os.path.isdir(bundle.lib_dir(source=True))
+        do_update_compiled = bundle.platform is not None and not os.path.isdir(
+            bundle.lib_dir(source=False)
+        )
     else:
-        do_update = True
+        do_update_source = True
+        do_update_compiled = bundle.platform is not None
+
+    if not (do_update_source or do_update_compiled):
+        logger.info("Current bundle version available (%s).", tag)
+        return True
+
+    if Bundle.offline:
+        if do_update_source:  # pylint: disable=no-else-return
+            logger.info(
+                "Bundle version not available but skipping update in offline mode."
+            )
+            return False
+        else:
+            logger.info(
+                "Bundle platform not available. Falling back to source (.py) files in offline mode."
+            )
+            bundle.platform = None
+            return True
+
+    logger.info("New version available (%s).", tag)
+    if do_update_source:
+        try:
+            get_bundle(bundle, tag, "py")
+        except requests.exceptions.HTTPError as ex:
+            click.secho(
+                f"There was a problem downloading the 'py' platform for the '{bundle.key}' bundle.",
+                fg="red",
+            )
+            logger.exception(ex)
+            return False  # Bundle isn't available
+        bundle.add_tag(tag)
+        tags_data_save_tags(bundle.key, bundle.available_tags)
 
-    if do_update:
-        logger.info("New version available (%s).", tag)
+    if do_update_compiled:
         try:
-            get_bundle(bundle, tag)
-            tags_data_save_tag(bundle.key, tag)
+            get_bundle(bundle, tag, bundle.platform)
         except requests.exceptions.HTTPError as ex:
-            # See #20 for reason for this
             click.secho(
                 (
-                    "There was a problem downloading that platform bundle. "
-                    "Skipping and using existing download if available."
+                    f"There was a problem downloading the '{bundle.platform}' platform for the "
+                    f"'{bundle.key}' bundle.\nFalling back to source (.py) files."
                 ),
                 fg="red",
             )
             logger.exception(ex)
+            bundle.platform = None  # Compiled isn't available, source is good
+    bundle.current_tag = tag
+
+    return True  # bundle is available
+
+
+def ensure_latest_bundle(bundle):
+    """
+    Ensure that there's a copy of the latest library bundle available so circup
+    can check the metadata contained therein.
+
+    :param Bundle bundle: the target Bundle object.
+    """
+    logger.info("Checking library updates for %s.", bundle.key)
+    tag = bundle.latest_tag
+    is_available = ensure_bundle_tag(bundle, tag)
+    if is_available:
+        click.echo(f"Using latest bundle for {bundle.key} ({tag}).")
     else:
-        logger.info("Current bundle up to date %s.", tag)
+        if bundle.current_tag is None:
+            # See issue #20 for reason for this
+            click.secho("Please try again in a moment.", fg="red")
+            sys.exit(1)
+        else:
+            # See PR #184 for reason for this
+            click.secho(
+                f"Skipping and using existing bundle for {bundle.key} ({bundle.current_tag}).",
+                fg="red",
+            )
+
+
+def ensure_pinned_bundle(bundle):
+    """
+    Ensure that there's a copy of the pinned library bundle available so circup
+    can check the metadata contained therein.
+
+    :param Bundle bundle: the target Bundle object.
+    """
+    logger.info("Checking library for %s.", bundle.key)
+    tag = bundle.pinned_tag
+    is_available = ensure_bundle_tag(bundle, tag)
+    if is_available:
+        click.echo(f"Using pinned bundle for {bundle.key} ({tag}).")
+    else:
+        click.secho(
+            (
+                "Check pinned version to make sure it is correct and check "
+                f"{bundle.url} to make sure the version ({tag}) exists."
+            ),
+            fg="red",
+        )
+        sys.exit(1)
+
+
+def ensure_bundle(bundle):
+    """
+    Ensure that there's a copy of either the pinned library bundle, or if no
+    version is pinned, the latest library bundle available so circup can check
+    the metadata contained therein.
+
+    :param Bundle bundle: the target Bundle object.
+    """
+    if bundle.pinned_tag is not None:
+        ensure_pinned_bundle(bundle)
+    else:
+        ensure_latest_bundle(bundle)
 
 
 def find_device():
@@ -293,41 +397,39 @@ def find_modules(backend, bundles_list):
     # pylint: enable=broad-except,too-many-locals
 
 
-def get_bundle(bundle, tag):
+def get_bundle(bundle, tag, platform):
     """
     Downloads and extracts the version of the bundle with the referenced tag.
     The resulting zip file is saved on the local filesystem.
 
     :param Bundle bundle: the target Bundle object.
     :param str tag: The GIT tag to use to download the bundle.
+    :param str platform: The platform string (i.e. '10mpy').
     """
-    click.echo(f"Downloading latest bundles for {bundle.key} ({tag}).")
-    for platform, github_string in PLATFORMS.items():
-        # Report the platform: "8.x-mpy", etc.
-        click.echo(f"{github_string}:")
-        url = bundle.url_format.format(platform=github_string, tag=tag)
-        logger.info("Downloading bundle: %s", url)
-        r = requests.get(url, stream=True, timeout=REQUESTS_TIMEOUT)
-        # pylint: disable=no-member
-        if r.status_code != requests.codes.ok:
-            logger.warning("Unable to connect to %s", url)
-            r.raise_for_status()
-        # pylint: enable=no-member
-        total_size = int(r.headers.get("Content-Length"))
-        temp_zip = bundle.zip.format(platform=platform)
-        with click.progressbar(
-            r.iter_content(1024), label="Extracting:", length=total_size
-        ) as pbar, open(temp_zip, "wb") as zip_fp:
-            for chunk in pbar:
-                zip_fp.write(chunk)
-                pbar.update(len(chunk))
-        logger.info("Saved to %s", temp_zip)
-        temp_dir = bundle.dir.format(platform=platform)
-        if os.path.isdir(temp_dir):
-            shutil.rmtree(temp_dir)
-        with zipfile.ZipFile(temp_zip, "r") as zfile:
-            zfile.extractall(temp_dir)
-    bundle.current_tag = tag
+    click.echo(f"Downloading '{platform}' bundle for {bundle.key} ({tag}).")
+    github_string = PLATFORMS[platform]
+    # Report the platform: "8.x-mpy", etc.
+    click.echo(f"{github_string}:")
+    url = bundle.url_format.format(platform=github_string, tag=tag)
+    logger.info("Downloading bundle: %s", url)
+    r = requests.get(url, stream=True, timeout=REQUESTS_TIMEOUT)
+    # pylint: disable=no-member
+    if r.status_code != requests.codes.ok:
+        logger.warning("Unable to connect to %s", url)
+        r.raise_for_status()
+    # pylint: enable=no-member
+    total_size = int(r.headers.get("Content-Length"))
+    temp_zip = bundle.zip.format(platform=platform)
+    with click.progressbar(
+        r.iter_content(1024), label="Extracting:", length=total_size
+    ) as pbar, open(temp_zip, "wb") as zip_fp:
+        for chunk in pbar:
+            zip_fp.write(chunk)
+            pbar.update(len(chunk))
+    logger.info("Saved to %s", temp_zip)
+    temp_dir = bundle.dir.format(platform=platform)
+    with zipfile.ZipFile(temp_zip, "r") as zfile:
+        zfile.extractall(temp_dir)
     click.echo("\nOK\n")
 
 
@@ -347,9 +449,9 @@ def get_bundle_examples(bundles_list, avoid_download=False):
 
     try:
         for bundle in bundles_list:
-            if not avoid_download or not os.path.isdir(bundle.lib_dir("py")):
-                ensure_latest_bundle(bundle)
-            path = bundle.examples_dir("py")
+            if not avoid_download or not os.path.isdir(bundle.lib_dir(source=True)):
+                ensure_bundle(bundle)
+            path = bundle.examples_dir(source=True)
             meta_saved = os.path.join(path, "../bundle_examples.json")
             if os.path.exists(meta_saved):
                 with open(meta_saved, "r", encoding="utf-8") as f:
@@ -383,9 +485,10 @@ def get_bundle_examples(bundles_list, avoid_download=False):
 
 def get_bundle_versions(bundles_list, avoid_download=False):
     """
-    Returns a dictionary of metadata from modules in the latest known release
-    of the library bundle. Uses the Python version (rather than the compiled
-    version) of the library modules.
+    Returns a dictionary of metadata from modules in either the pinned release
+    if one is present in 'pyproject.toml', or the latest known release of the
+    library bundle. Uses the Python version (rather than the compiled version)
+    of the library modules.
 
     :param List[Bundle] bundles_list: List of supported bundles as Bundle objects.
     :param bool avoid_download: if True, download the bundle only if missing.
@@ -394,9 +497,9 @@ def get_bundle_versions(bundles_list, avoid_download=False):
     """
     all_the_modules = dict()
     for bundle in bundles_list:
-        if not avoid_download or not os.path.isdir(bundle.lib_dir("py")):
-            ensure_latest_bundle(bundle)
-        path = bundle.lib_dir("py")
+        if not avoid_download or not os.path.isdir(bundle.lib_dir(source=True)):
+            ensure_bundle(bundle)
+        path = bundle.lib_dir(source=True)
         path_modules = _get_modules_file(path, logger)
         for name, module in path_modules.items():
             module["bundle"] = bundle
@@ -443,14 +546,32 @@ def get_bundles_local_dict():
         return dict()
 
 
-def get_bundles_list():
+def get_bundles_list(bundle_tags, platform_version=None):
     """
     Retrieve the list of bundles from the config dictionary.
 
+    :param Dict[str,str]|None bundle_tags: Pinned bundle tags. These override
+    any tags found in the pyproject.toml.
+    :param str platform_version: The platform version needed for the current
+    device.
     :return: List of supported bundles as Bundle objects.
     """
     bundle_config = get_bundles_dict()
+    tags = tags_data_load()
+    pyproject = find_pyproject()
+    pinned_tags = (
+        pyproject_bundle_versions(pyproject) if pyproject is not None else None
+    )
+
+    if bundle_tags is not None:
+        pinned_tags = bundle_tags if pinned_tags is None else pinned_tags | bundle_tags
+
     bundles_list = [Bundle(bundle_config[b]) for b in bundle_config]
+    for bundle in bundles_list:
+        bundle.platform = platform_version
+        bundle.available_tags = tags.get(bundle.key, [])
+        if pinned_tags is not None:
+            bundle.pinned_tag = pinned_tags.get(bundle.key)
     logger.info("Using bundles: %s", ", ".join(b.key for b in bundles_list))
     return bundles_list
 
@@ -613,15 +734,38 @@ def save_local_bundles(bundles_data):
             os.unlink(BUNDLE_CONFIG_LOCAL)
 
 
-def tags_data_save_tag(key, tag):
+def tags_data_load():
+    """
+    Load the list of the version tags of the bundles on disk.
+
+    :return: a dict() of tags indexed by Bundle identifiers/keys.
     """
-    Add or change the saved tag value for a bundle.
+    tags_data = None
+    try:
+        with open(BUNDLE_DATA, encoding="utf-8") as data:
+            try:
+                tags_data = json.load(data)
+            except json.decoder.JSONDecodeError as ex:
+                # Sometimes (why?) the JSON file becomes corrupt. In which case
+                # log it and carry on as if setting up for first time.
+                logger.error("Could not parse %s", BUNDLE_DATA)
+                logger.exception(ex)
+    except FileNotFoundError:
+        pass
+    if not isinstance(tags_data, dict):
+        tags_data = {}
+    return tags_data
+
+
+def tags_data_save_tags(key, tags):
+    """
+    Add or change the saved available tags value for a bundle.
 
     :param str key: The bundle's identifier/key.
-    :param str tag: The new tag for the bundle.
+    :param List[str] tags: The new tags for the bundle.
     """
-    tags_data = tags_data_load(logger)
-    tags_data[key] = tag
+    tags_data = tags_data_load()
+    tags_data[key] = tags
     with open(BUNDLE_DATA, "w", encoding="utf-8") as data:
         json.dump(tags_data, data)
 
@@ -855,3 +999,52 @@ def is_virtual_env_active():
     virtual environment, regardless how circup is installed.
     """
     return "VIRTUAL_ENV" in os.environ
+
+
+def find_pyproject():
+    """
+    Look for a pyproject.toml in the current directory or its parent directories.
+
+    :return: The path to the pyproject.toml for the project, or None if it
+        couldn't be found.
+    """
+    logger.info("Looking for pyproject.toml file.")
+    cwd = Path.cwd()
+    candidates = [cwd, cwd.parent]
+
+    for path in candidates:
+        pyproject_file = path / "pyproject.toml"
+
+        if pyproject_file.exists():
+            logger.info("Found pyproject.toml at '%s'", str(pyproject_file))
+            return pyproject_file
+
+    logger.info("No pyproject.toml file found.")
+    return None
+
+
+def pyproject_bundle_versions(pyproject_file):
+    """
+    Check for specified bundle versions.
+    """
+    pyproject_toml_data = toml.load(pyproject_file)
+    return pyproject_toml_data.get("tool", {}).get("circup", {}).get("bundle-versions")
+
+
+def parse_cli_bundle_tags(bundle_tags_cli):
+    """Parse bundle tags that were provided from the command line."""
+    bundle_tags = {}
+    for bundle_tag_item in bundle_tags_cli:
+        item = bundle_tag_item.split("=")
+        if len(item) == 2:
+            bundle_tags[item[0].strip()] = item[1].strip()
+    return bundle_tags if len(bundle_tags) > 0 else None
+
+
+def pretty_supported_cpy_versions():
+    """Return a user friendly string of the supported CircuitPython versions."""
+    supported_cpy = [
+        PLATFORMS[platform].split("-", maxsplit=1)[0]
+        for platform in SUPPORTED_PLATFORMS
+    ]
+    return ", ".join(supported_cpy)

circup/commands.py

@@ -24,7 +24,11 @@ import requests
 
 from circup.backends import WebBackend, DiskBackend
 from circup.logging import logger, log_formatter, LOGFILE
-from circup.shared import BOARDLESS_COMMANDS, get_latest_release_from_url
+from circup.shared import (
+    BOARDLESS_COMMANDS,
+    SUPPORTED_PLATFORMS,
+    get_latest_release_from_url,
+)
 from circup.bundle import Bundle
 from circup.command_utils import (
     get_device_path,
@@ -37,6 +41,8 @@ from circup.command_utils import (
     libraries_from_auto_file,
     get_dependencies,
     get_bundles_local_dict,
+    parse_cli_bundle_tags,
+    pretty_supported_cpy_versions,
     save_local_bundles,
     get_bundles_dict,
     completion_for_example,
@@ -67,6 +73,16 @@ from circup.command_utils import (
     " You can optionally set an environment variable CIRCUP_WEBWORKFLOW_PASSWORD"
     " instead of passing this argument. If both exist the CLI arg takes precedent.",
 )
+@click.option(
+    "--offline",
+    is_flag=True,
+    help="Prevents Circup from accessing the internet for any reason. "
+    "Without this flag, Circup will fail with an error if it needs to access "
+    "the network and the network is not available. With this flag, Circup "
+    "will attempt to proceed without the network if possible. Circup will "
+    "only use bundles downloaded locally even if there might be newer "
+    "versions available.",
+)
 @click.option(
     "--timeout",
     default=30,
@@ -84,13 +100,41 @@ from circup.command_utils import (
     help="Manual CircuitPython version. If provided in combination "
     "with --board-id, it overrides the detected CPy version.",
 )
+@click.option(
+    "bundle_versions",
+    "--bundle-version",
+    multiple=True,
+    help="Specify the version to use for a bundle. Include the bundle name and "
+    "the version separated by '=', similar to the format of requirements.txt. "
+    "This option can be used multiple times for different bundles. Bundle "
+    "version values provided here will override any pinned values from the "
+    "pyproject.toml.",
+)
+@click.option(
+    "--allow-unsupported",
+    is_flag=True,
+    help="Allow using a device with a version of CircuitPython that is no longer "
+    "supported. Using an unsupported version of CircuitPython is generally not "
+    "recommended because libraries may not work with it.",
+)
 @click.version_option(
     prog_name="Circup",
     message="%(prog)s, A CircuitPython module updater. Version %(version)s",
 )
 @click.pass_context
 def main(  # pylint: disable=too-many-locals
-    ctx, verbose, path, host, port, password, timeout, board_id, cpy_version
+    ctx,
+    verbose,
+    path,
+    host,
+    port,
+    password,
+    offline,
+    timeout,
+    board_id,
+    cpy_version,
+    bundle_versions,
+    allow_unsupported,
 ):  # pragma: no cover
     """
     A tool to manage and update libraries on a CircuitPython device.
@@ -98,6 +142,10 @@ def main(  # pylint: disable=too-many-locals
     # pylint: disable=too-many-arguments,too-many-branches,too-many-statements,too-many-locals, R0801
     ctx.ensure_object(dict)
     ctx.obj["TIMEOUT"] = timeout
+    ctx.obj["BUNDLE_TAGS"] = (
+        parse_cli_bundle_tags(bundle_versions) if len(bundle_versions) > 0 else None
+    )
+    Bundle.offline = offline
 
     if password is None:
         password = os.getenv("CIRCUP_WEBWORKFLOW_PASSWORD")
@@ -154,20 +202,22 @@ def main(  # pylint: disable=too-many-locals
 
     logger.info("### Started Circup ###")
 
-    # If a newer version of circup is available, print a message.
-    logger.info("Checking for a newer version of circup")
-    version = get_circup_version()
-    if version:
-        update_checker.update_check("circup", version)
+    if offline:
+        logger.info(
+            "'--offline' flag present, all update checks requiring the network will be skipped."
+        )
+    else:
+        # If a newer version of circup is available, print a message.
+        logger.info("Checking for a newer version of circup")
+        version = get_circup_version()
+        if version:
+            update_checker.update_check("circup", version)
 
     # stop early if the command is boardless
     if ctx.invoked_subcommand in BOARDLESS_COMMANDS or "--help" in sys.argv:
         return
 
     ctx.obj["DEVICE_PATH"] = device_path
-    latest_version = get_latest_release_from_url(
-        "https://github.com/adafruit/circuitpython/releases/latest", logger
-    )
 
     if device_path is None or not ctx.obj["backend"].is_device_present():
         click.secho("Could not find a connected CircuitPython device.", fg="red")
@@ -178,27 +228,54 @@ def main(  # pylint: disable=too-many-locals
             if board_id is None or cpy_version is None
             else (cpy_version, board_id)
         )
+        major_version = cpy_version.split(".")[0]
+        bundle_platform = "{}mpy".format(major_version)
+        ctx.obj["DEVICE_PLATFORM_VERSION"] = bundle_platform
         click.echo(
             "Found device {} at {}, running CircuitPython {}.".format(
                 board_id, device_path, cpy_version
             )
         )
-    try:
-        if VersionInfo.parse(cpy_version) < VersionInfo.parse(latest_version):
+
+    if not offline:
+        latest_version = get_latest_release_from_url(
+            "https://github.com/adafruit/circuitpython/releases/latest", logger
+        )
+        try:
+            if VersionInfo.parse(cpy_version) < VersionInfo.parse(latest_version):
+                click.secho(
+                    "A newer version of CircuitPython ({}) is available.".format(
+                        latest_version
+                    ),
+                    fg="green",
+                )
+                if board_id:
+                    url_download = f"https://circuitpython.org/board/{board_id}"
+                else:
+                    url_download = "https://circuitpython.org/downloads"
+                click.secho("Get it here: {}".format(url_download), fg="green")
+        except ValueError as ex:
+            logger.warning("CircuitPython has incorrect semver value.")
+            logger.warning(ex)
+
+    if not bundle_platform in SUPPORTED_PLATFORMS:
+        click.secho(
+            "The version of CircuitPython on the device is no longer supported.",
+            fg="yellow" if allow_unsupported else "red",
+        )
+        if allow_unsupported:
             click.secho(
-                "A newer version of CircuitPython ({}) is available.".format(
-                    latest_version
-                ),
-                fg="green",
+                "It is recommended to update to a supported version "
+                f"({pretty_supported_cpy_versions()}) to ensure compatability.",
+                fg="yellow",
             )
-            if board_id:
-                url_download = f"https://circuitpython.org/board/{board_id}"
-            else:
-                url_download = "https://circuitpython.org/downloads"
-            click.secho("Get it here: {}".format(url_download), fg="green")
-    except ValueError as ex:
-        logger.warning("CircuitPython has incorrect semver value.")
-        logger.warning(ex)
+        else:
+            click.echo(
+                f"If you would like to continue to use version {cpy_version} of CircuitPython, "
+                "pass the '--allow-unsupported' flag with this command. Otherwise, update to a "
+                f"supported version ({pretty_supported_cpy_versions()}) to ensure compatability.",
+            )
+            sys.exit(1)
 
 
 @main.command()
@@ -210,7 +287,7 @@ def freeze(ctx, requirement):  # pragma: no cover
     device. Option -r saves output to requirements.txt file
     """
     logger.info("Freeze")
-    modules = find_modules(ctx.obj["backend"], get_bundles_list())
+    modules = find_modules(ctx.obj["backend"], get_bundles_list(ctx.obj["BUNDLE_TAGS"]))
     if modules:
         output = []
         for module in modules:
@@ -258,7 +335,12 @@ def list_cli(ctx):  # pragma: no cover
 
     modules = [
         m.row
-        for m in find_modules(ctx.obj["backend"], get_bundles_list())
+        for m in find_modules(
+            ctx.obj["backend"],
+            get_bundles_list(
+                ctx.obj["BUNDLE_TAGS"], ctx.obj["DEVICE_PLATFORM_VERSION"]
+            ),
+        )
         if m.outofdate
     ]
     if modules:
@@ -334,7 +416,10 @@ def install(
 
     # pylint: disable=too-many-branches
     # TODO: Ensure there's enough space on the device
-    available_modules = get_bundle_versions(get_bundles_list())
+    platform_version = ctx.obj["DEVICE_PLATFORM_VERSION"] if not pyext else None
+    available_modules = get_bundle_versions(
+        get_bundles_list(ctx.obj["BUNDLE_TAGS"], platform_version)
+    )
     mod_names = {}
     for module, metadata in available_modules.items():
         mod_names[module.replace(".py", "").lower()] = metadata
@@ -367,7 +452,7 @@ def install(
                 upgrade,
             )
 
-            if stubs:
+            if stubs and not Bundle.offline:
                 # Check we are in a virtual environment
                 if not is_virtual_env_active():
                     if is_global_install_ok is None:
@@ -440,7 +525,7 @@ def example(ctx, examples, op_list, rename, overwrite):
         else:
             click.echo("Available example libraries:")
             available_examples = get_bundle_examples(
-                get_bundles_list(), avoid_download=True
+                get_bundles_list(ctx.obj["BUNDLE_TAGS"]), avoid_download=True
             )
             lib_names = {
                 str(key.split(os.path.sep)[0]): value
@@ -451,7 +536,7 @@ def example(ctx, examples, op_list, rename, overwrite):
 
     for example_arg in examples:
         available_examples = get_bundle_examples(
-            get_bundles_list(), avoid_download=True
+            get_bundles_list(ctx.obj["BUNDLE_TAGS"]), avoid_download=True
         )
         if example_arg in available_examples:
             filename = available_examples[example_arg].split(os.path.sep)[-1]
@@ -485,14 +570,15 @@ def example(ctx, examples, op_list, rename, overwrite):
 
 @main.command()
 @click.argument("match", required=False, nargs=1)
-def show(match):  # pragma: no cover
+@click.pass_context
+def show(ctx, match):  # pragma: no cover
     """
     Show a list of available modules in the bundle. These are modules which
     *could* be installed on the device.
 
     If MATCH is specified only matching modules will be listed.
     """
-    available_modules = get_bundle_versions(get_bundles_list())
+    available_modules = get_bundle_versions(get_bundles_list(ctx.obj["BUNDLE_TAGS"]))
     module_names = sorted([m.replace(".py", "") for m in available_modules])
     if match is not None:
         match = match.lower()
@@ -555,7 +641,9 @@ def update(ctx, update_all):  # pragma: no cover
     """
     logger.info("Update")
     # Grab current modules.
-    bundles_list = get_bundles_list()
+    bundles_list = get_bundles_list(
+        ctx.obj["BUNDLE_TAGS"], ctx.obj["DEVICE_PLATFORM_VERSION"]
+    )
     installed_modules = find_modules(ctx.obj["backend"], bundles_list)
     modules_to_update = [m for m in installed_modules if m.outofdate]
 
@@ -654,13 +742,14 @@ def update(ctx, update_all):  # pragma: no cover
 
 @main.command("bundle-show")
 @click.option("--modules", is_flag=True, help="List all the modules per bundle.")
-def bundle_show(modules):
+@click.pass_context
+def bundle_show(ctx, modules):
     """
-    Show the list of bundles, default and local, with URL, current version
-    and latest version retrieved from the web.
+    Show the list of bundles, default and local, with URL, current version,
+    available versions, and latest version retrieved from the web.
     """
     local_bundles = get_bundles_local_dict().values()
-    bundles = get_bundles_list()
+    bundles = get_bundles_list(ctx.obj["BUNDLE_TAGS"])
     available_modules = get_bundle_versions(bundles)
 
     for bundle in bundles:
@@ -669,7 +758,13 @@ def bundle_show(modules):
         else:
             click.secho(bundle.key, fg="green")
         click.echo("    " + bundle.url)
-        click.echo("    version = " + bundle.current_tag)
+        click.echo(
+            "    version = "
+            + bundle.current_tag
+            + (" (pinned)" if bundle.pinned_tag is not None else "")
+        )
+        click.echo("    available versions:")
+        click.echo("        " + "\n        ".join(bundle.available_tags))
         if modules:
             click.echo("Modules:")
             for name, mod in sorted(available_modules.items()):
@@ -695,6 +790,10 @@ def bundle_add(ctx, bundle):
         )
         return
 
+    if Bundle.offline:
+        click.secho("Cannot add new bundle when '--offline' flag is present.", fg="red")
+        return
+
     bundles_dict = get_bundles_local_dict()
     modified = False
     for bundle_repo in bundle:
@@ -739,7 +838,7 @@ def bundle_add(ctx, bundle):
         # save the bundles list
         save_local_bundles(bundles_dict)
         # update and get the new bundles for the first time
-        get_bundle_versions(get_bundles_list())
+        get_bundle_versions(get_bundles_list(ctx.obj["BUNDLE_TAGS"]))
 
 
 @main.command("bundle-remove")
@@ -788,3 +887,40 @@ def bundle_remove(bundle, reset):
                 )
     if modified:
         save_local_bundles(bundles_local_dict)
+
+
+@main.command()
+@click.pass_context
+def bundle_freeze(ctx):  # pragma: no cover
+    """
+    Output details of all the bundles for modules found on the connected
+    CIRCUITPYTHON device. Copying the output into pyproject.toml will pin the
+    bundles.
+    """
+    logger.info("Bundle Freeze")
+    device_modules = ctx.obj["backend"].get_device_versions()
+    if not device_modules:
+        click.echo("No modules found on the device.")
+        return
+
+    available_modules = get_bundle_versions(get_bundles_list(ctx.obj["BUNDLE_TAGS"]))
+    bundles_used = {}
+    for name in device_modules:
+        module = available_modules.get(name)
+        if module:
+            bundle = module["bundle"]
+            bundles_used[bundle.key] = bundle.current_tag
+
+    if bundles_used:
+        click.echo(
+            "Copy the following lines into your pyproject.toml to pin "
+            "the bundles used with modules on the device:\n"
+        )
+        output = ["[tool.circup.bundle-versions]"]
+        for bundle_name, version in bundles_used.items():
+            output.append(f'"{bundle_name}" = "{version}"')
+        for line in output:
+            click.echo(line)
+            logger.info(line)
+    else:
+        click.echo("No bundles used with the modules on the device.")

circup/module.py

@@ -79,16 +79,8 @@ class Module:
         self.max_version = compatibility[1]
         # Figure out the bundle path.
         self.bundle_path = None
-        if self.mpy:
-            # Byte compiled, now check CircuitPython version.
-
-            major_version = self.backend.get_circuitpython_version()[0].split(".")[0]
-            bundle_platform = "{}mpy".format(major_version)
-        else:
-            # Regular Python
-            bundle_platform = "py"
         # module path in the bundle
-        search_path = bundle.lib_dir(bundle_platform)
+        search_path = bundle.lib_dir(source=not self.mpy)
         if self.file:
             self.bundle_path = os.path.join(search_path, self.file)
         else:

circup/shared.py

@@ -9,7 +9,6 @@ and Backend class functions.
 import glob
 import os
 import re
-import json
 import importlib.resources
 import appdirs
 import requests
@@ -23,7 +22,10 @@ BAD_FILE_FORMAT = "Invalid"
 DATA_DIR = appdirs.user_data_dir(appname="circup", appauthor="adafruit")
 
 #: Module formats list (and the other form used in github files)
-PLATFORMS = {"py": "py", "9mpy": "9.x-mpy", "10mpy": "10.x-mpy"}
+PLATFORMS = {"py": "py", "8mpy": "8.x-mpy", "9mpy": "9.x-mpy", "10mpy": "10.x-mpy"}
+
+#: CircuitPython platforms that are currently supported.
+SUPPORTED_PLATFORMS = ["9mpy", "10mpy"]
 
 #: Timeout for requests calls like get()
 REQUESTS_TIMEOUT = 30
@@ -192,29 +194,6 @@ def extract_metadata(path, logger):
     return result
 
 
-def tags_data_load(logger):
-    """
-    Load the list of the version tags of the bundles on disk.
-
-    :return: a dict() of tags indexed by Bundle identifiers/keys.
-    """
-    tags_data = None
-    try:
-        with open(BUNDLE_DATA, encoding="utf-8") as data:
-            try:
-                tags_data = json.load(data)
-            except json.decoder.JSONDecodeError as ex:
-                # Sometimes (why?) the JSON file becomes corrupt. In which case
-                # log it and carry on as if setting up for first time.
-                logger.error("Could not parse %s", BUNDLE_DATA)
-                logger.exception(ex)
-    except FileNotFoundError:
-        pass
-    if not isinstance(tags_data, dict):
-        tags_data = {}
-    return tags_data
-
-
 def get_latest_release_from_url(url, logger):
     """
     Find the tag name of the latest release by using HTTP HEAD and decoding the redirect.

{circup-2.2.6.dist-info → circup-2.4.0.dist-info}/METADATA

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

circup-2.4.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+circup/__init__.py,sha256=9A98U3DyA14tm-7_d88fGSlLfEKz9T_85t8kXkErqRg,662
+circup/backends.py,sha256=aH76wEusVCf2IeOCWrypHd2_tBo286TxOBkgYGwXeOI,39869
+circup/bundle.py,sha256=qqDz0MjezKfSngldk8zNahNhPikuOZLAMwBUv7w75Mc,9442
+circup/command_utils.py,sha256=k18vZe0ecAKANoB9SoXh39S-DjE_cC8rpZpr3-gyQ1I,37121
+circup/commands.py,sha256=vAsmWyvTB3sjH4bdfGe9IQxPt3DC925mWdHNRDOeK00,34042
+circup/lazy_metadata.py,sha256=69VidxGGWE13QwAAtMCPNTXTsQ2q5dJvMtclw4YaqEY,3764
+circup/logging.py,sha256=hu4v8ljkXo8ru-cqs0W3PU-xEVvTO_qqMKDJM18OXbQ,1115
+circup/module.py,sha256=ZrgZhBKuDWHfw9FzcXKjBYx-oybbDnH_IAdek3aSGwU,7131
+circup/shared.py,sha256=d1imapk_esiuz6dMLe37Ck8lHW6W6L3djFpH8KBTAMk,8752
+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.4.0.dist-info/licenses/LICENSE,sha256=bVlIMmSL_pqLCqae4hzixy9pYXD808IbgsMoQXTNLBk,1076
+circup-2.4.0.dist-info/METADATA,sha256=iqTeOcWnEgpLE8jfAK8c05pqg8LRa1t74lnEnoHxuYM,13617
+circup-2.4.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+circup-2.4.0.dist-info/entry_points.txt,sha256=FjTmwYD_ApgLRGifUrr_Ui1voW6fEzodQc3DKNzoAPc,69
+circup-2.4.0.dist-info/top_level.txt,sha256=Qx6E0eZgSBE10ciNKsLZx8-TTy_9fEVZh7NLmn24KcU,7
+circup-2.4.0.dist-info/RECORD,,

{circup-2.2.6.dist-info → circup-2.4.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

circup-2.2.6.dist-info/RECORD

@@ -1,21 +0,0 @@
-circup/__init__.py,sha256=9A98U3DyA14tm-7_d88fGSlLfEKz9T_85t8kXkErqRg,662
-circup/backends.py,sha256=g9Q9xCGZidwsEDL2Ga2cm50YYB54IiqlKUPcxj-pWZA,40008
-circup/bundle.py,sha256=FEP4F470aJtwmm8jgTM3DgR3dj5SVwbX1tbyIRKVHn8,5327
-circup/command_utils.py,sha256=_bYFfsfXoy6ERyTSmqt-RTNuIJN9ilYolKGTF42ebyk,30676
-circup/commands.py,sha256=3clk6B6oF5noA31TnuCyzIHNxxFcsoxBCVBOoy-K8fo,29082
-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=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.6.dist-info/licenses/LICENSE,sha256=bVlIMmSL_pqLCqae4hzixy9pYXD808IbgsMoQXTNLBk,1076
-circup-2.2.6.dist-info/METADATA,sha256=bBGt9xAlnkAhdypwfT63GgbGSjfzee1JwHJ5FFC2Euw,13617
-circup-2.2.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-circup-2.2.6.dist-info/entry_points.txt,sha256=FjTmwYD_ApgLRGifUrr_Ui1voW6fEzodQc3DKNzoAPc,69
-circup-2.2.6.dist-info/top_level.txt,sha256=Qx6E0eZgSBE10ciNKsLZx8-TTy_9fEVZh7NLmn24KcU,7
-circup-2.2.6.dist-info/RECORD,,