circup 2.3.0__py3-none-any.whl → 3.0.0__py3-none-any.whl

circup/backends.py

@@ -139,7 +139,7 @@ class Backend:
             if name in device_modules:
                 if not upgrade:
                     # skip already installed modules if no -upgrade flag
-                    click.echo("'{}' is already installed.".format(name))
+                    click.echo(f"'{name}' is already installed.")
                     return
 
                 # uninstall the module before installing
@@ -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:
@@ -205,9 +207,9 @@ class Backend:
                     self.install_module_mpy(bundle, metadata)
             else:
                 self.copy_file(metadata["path"], "lib")
-            click.echo("Installed '{}'.".format(name))
+            click.echo(f"Installed '{name}'.")
         else:
-            click.echo("Unknown module named, '{}'.".format(name))
+            click.echo(f"Unknown module named, '{name}'.")
 
     # def libraries_from_imports(self, code_py, mod_names):
     #     """
@@ -303,7 +305,7 @@ class WebBackend(Backend):
             socket.getaddrinfo(host, 80, proto=socket.IPPROTO_TCP)
         except socket.gaierror as exc:
             raise RuntimeError(
-                "Invalid host: {}.".format(host) + " You should remove the 'http://'"
+                f"Invalid host: {host}." + " You should remove the 'http://'"
                 if "http://" in host or "https://" in host
                 else "Could not find or connect to specified device"
             ) from exc
@@ -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)
@@ -659,7 +659,7 @@ class WebBackend(Backend):
             self.install_file_http(bundle_path)
 
         else:
-            raise IOError("Cannot find compiled version of module.")
+            raise OSError("Cannot find compiled version of module.")
 
     # pylint: enable=too-many-locals,too-many-branches
     def install_module_py(self, metadata, location=None):
@@ -862,7 +862,6 @@ class DiskBackend(Backend):
             try:
                 with open(
                     os.path.join(self.device_location, "boot_out.txt"),
-                    "r",
                     encoding="utf-8",
                 ) as boot:
                     boot_out_contents = boot.read()
@@ -920,9 +919,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.
@@ -936,7 +933,7 @@ class DiskBackend(Backend):
             # Copy file.
             shutil.copyfile(bundle_path, target_path)
         else:
-            raise IOError("Cannot find compiled version of module.")
+            raise OSError("Cannot find compiled version of module.")
 
     # pylint: enable=too-many-locals,too-many-branches
     def install_module_py(self, metadata, location=None):

circup/bundle.py

@@ -10,6 +10,8 @@ import sys
 import click
 import requests
 
+from semver import VersionInfo
+
 from circup.shared import (
     DATA_DIR,
     PLATFORMS,
@@ -20,11 +22,14 @@ from circup.shared import (
 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.
@@ -47,29 +52,40 @@ class Bundle:
         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),
@@ -93,7 +109,7 @@ class Bundle:
             "requirements.txt" if not toml_file else "pyproject.toml",
         )
         if os.path.isfile(found_file):
-            with open(found_file, "r", encoding="utf-8") as read_this:
+            with open(found_file, encoding="utf-8") as read_this:
                 return read_this.read()
         return None
 
@@ -101,18 +117,25 @@ class Bundle:
     def current_tag(self):
         """
         The current tag for the project. If the tag hasn't been explicitly set
-        this will be the pinned tag, if one is set. If there is no pinned tag,
-        this will be the latest available tag that is locally available.
+        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 tag value for the project.
         """
         if self._current is None:
-            self._current = self.pinned_tag or (
-                # This represents the latest version locally available
-                self._available[-1]
-                if len(self._available) > 0
-                else None
-            )
+            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
@@ -132,9 +155,12 @@ 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
@@ -155,7 +181,15 @@ class Bundle:
         """
         if isinstance(tags, str):
             tags = [tags]
-        self._available = sorted(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:
         """
@@ -171,34 +205,59 @@ class Bundle:
             # The tag is already stored for some reason, lets not add it again
             return
 
-        for rev_i, available_tag in enumerate(reversed(self._available)):
-            if int(tag) > int(available_tag):
-                i = len(self._available) - rev_i
-                self._available.insert(i, tag)
-                break
-        else:
-            self._available.insert(0, tag)
+        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.

circup/command_utils.py

@@ -23,6 +23,7 @@ import click
 from circup.shared import (
     PLATFORMS,
     REQUESTS_TIMEOUT,
+    SUPPORTED_PLATFORMS,
     _get_modules_file,
     BUNDLE_CONFIG_OVERWRITE,
     BUNDLE_CONFIG_FILE,
@@ -145,29 +146,71 @@ def ensure_bundle_tag(bundle, tag):
 
     :return: If the bundle is available.
     """
-    do_update = False
+    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:
-        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))
+        # 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 do_update:
-        logger.info("New version available (%s).", tag)
+    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)
-            tags_data_save_tags(bundle.key, bundle.available_tags)
+            get_bundle(bundle, tag, "py")
         except requests.exceptions.HTTPError as ex:
             click.secho(
-                f"There was a problem downloading the {bundle.key} bundle.", fg="red"
+                f"There was a problem downloading the 'py' platform for the '{bundle.key}' bundle.",
+                fg="red",
             )
             logger.exception(ex)
-            return False
-    else:
-        logger.info("Current bundle version available (%s).", tag)
-    return True
+            return False  # Bundle isn't available
+        bundle.add_tag(tag)
+        tags_data_save_tags(bundle.key, bundle.available_tags)
+
+    if do_update_compiled:
+        try:
+            get_bundle(bundle, tag, bundle.platform)
+        except requests.exceptions.HTTPError as ex:
+            click.secho(
+                (
+                    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):
@@ -286,7 +329,7 @@ def find_device():
         old_mode = ctypes.windll.kernel32.SetErrorMode(1)
         try:
             for disk in "ABCDEFGHIJKLMNOPQRSTUVWXYZ":
-                path = "{}:\\".format(disk)
+                path = f"{disk}:\\"
                 if os.path.exists(path) and get_volume_name(path) == "CIRCUITPY":
                     device_dir = path
                     # Report only the FIRST device found.
@@ -295,7 +338,7 @@ def find_device():
             ctypes.windll.kernel32.SetErrorMode(old_mode)
     else:
         # No support for unknown operating systems.
-        raise NotImplementedError('OS "{}" not supported.'.format(os.name))
+        raise NotImplementedError(f'OS "{os.name}" not supported.')
     logger.info("Found device: %s", device_dir)
     return device_dir
 
@@ -349,45 +392,44 @@ def find_modules(backend, bundles_list):
         # If it's not possible to get the device and bundle metadata, bail out
         # with a friendly message and indication of what's gone wrong.
         logger.exception(ex)
-        click.echo("There was a problem: {}".format(ex))
+        click.echo(f"There was a problem: {ex}")
         sys.exit(1)
     # 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 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)
-        with zipfile.ZipFile(temp_zip, "r") as zfile:
-            zfile.extractall(temp_dir)
-    bundle.add_tag(tag)
-    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")
 
 
@@ -407,12 +449,12 @@ 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")):
+            if not avoid_download or not os.path.isdir(bundle.lib_dir(source=True)):
                 ensure_bundle(bundle)
-            path = bundle.examples_dir("py")
+            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:
+                with open(meta_saved, encoding="utf-8") as f:
                     bundle_examples = json.load(f)
                 all_the_examples.update(bundle_examples)
                 bundle_examples.clear()
@@ -455,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")):
+        if not avoid_download or not os.path.isdir(bundle.lib_dir(source=True)):
             ensure_bundle(bundle)
-        path = bundle.lib_dir("py")
+        path = bundle.lib_dir(source=True)
         path_modules = _get_modules_file(path, logger)
         for name, module in path_modules.items():
             module["bundle"] = bundle
@@ -504,12 +546,14 @@ def get_bundles_local_dict():
         return dict()
 
 
-def get_bundles_list(bundle_tags):
+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()
@@ -524,6 +568,7 @@ def get_bundles_list(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)
@@ -884,7 +929,7 @@ def libraries_from_auto_file(backend, auto_file, mod_names):
     # pass a local file with "./" or "../"
     is_relative = auto_file.split(os.sep)[0] in [os.path.curdir, os.path.pardir]
     if os.path.isabs(auto_file) or is_relative:
-        with open(auto_file, "r", encoding="UTF8") as fp:
+        with open(auto_file, encoding="UTF8") as fp:
             auto_file_content = fp.read()
     else:
         auto_file_content = backend.get_file_content(auto_file)
@@ -994,3 +1039,12 @@ def parse_cli_bundle_tags(bundle_tags_cli):
         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,
@@ -38,6 +42,7 @@ from circup.command_utils import (
     get_dependencies,
     get_bundles_local_dict,
     parse_cli_bundle_tags,
+    pretty_supported_cpy_versions,
     save_local_bundles,
     get_bundles_dict,
     completion_for_example,
@@ -68,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,
@@ -95,6 +110,13 @@ from circup.command_utils import (
     "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",
@@ -107,10 +129,12 @@ def main(  # pylint: disable=too-many-locals
     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.
@@ -121,6 +145,7 @@ def main(  # pylint: disable=too-many-locals
     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")
@@ -171,26 +196,28 @@ def main(  # pylint: disable=too-many-locals
         verbose_handler.setLevel(logging.INFO)
         verbose_handler.setFormatter(log_formatter)
         logger.addHandler(verbose_handler)
-        click.echo("Logging to {}\n".format(LOGFILE))
+        click.echo(f"Logging to {LOGFILE}\n")
     else:
         ctx.obj["verbose"] = False
 
     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")
@@ -201,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(f"Get it here: {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()
@@ -237,7 +291,7 @@ def freeze(ctx, requirement):  # pragma: no cover
     if modules:
         output = []
         for module in modules:
-            output.append("{}=={}".format(module.name, module.device_version))
+            output.append(f"{module.name}=={module.device_version}")
         for module in output:
             click.echo(module)
             logger.info(module)
@@ -282,7 +336,10 @@ def list_cli(ctx):  # pragma: no cover
     modules = [
         m.row
         for m in find_modules(
-            ctx.obj["backend"], get_bundles_list(ctx.obj["BUNDLE_TAGS"])
+            ctx.obj["backend"],
+            get_bundles_list(
+                ctx.obj["BUNDLE_TAGS"], ctx.obj["DEVICE_PLATFORM_VERSION"]
+            ),
         )
         if m.outofdate
     ]
@@ -293,7 +350,7 @@ def list_cli(ctx):  # pragma: no cover
         for row in data:
             for i, word in enumerate(row):
                 col_width[i] = max(len(word) + 2, col_width[i])
-        dashes = tuple(("-" * (width - 1) for width in col_width))
+        dashes = tuple("-" * (width - 1) for width in col_width)
         data.insert(1, dashes)
         click.echo(
             "The following modules are out of date or probably need an update.\n"
@@ -359,12 +416,15 @@ def install(
 
     # pylint: disable=too-many-branches
     # TODO: Ensure there's enough space on the device
-    available_modules = get_bundle_versions(get_bundles_list(ctx.obj["BUNDLE_TAGS"]))
+    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
     if requirement:
-        with open(requirement, "r", encoding="utf-8") as rfile:
+        with open(requirement, encoding="utf-8") as rfile:
             requirements_txt = rfile.read()
         requested_installs = libraries_from_requirements(requirements_txt)
     elif auto or auto_file:
@@ -392,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:
@@ -525,9 +585,7 @@ def show(ctx, match):  # pragma: no cover
         module_names = [m for m in module_names if match in m]
     click.echo("\n".join(module_names))
 
-    click.echo(
-        "{} shown of {} packages.".format(len(module_names), len(available_modules))
-    )
+    click.echo(f"{len(module_names)} shown of {len(available_modules)} packages.")
 
 
 @main.command()
@@ -551,9 +609,9 @@ def uninstall(ctx, module):  # pragma: no cover
             metadata = mod_names[name]
             module_path = metadata["path"]
             ctx.obj["backend"].uninstall(device_path, module_path)
-            click.echo("Uninstalled '{}'.".format(name))
+            click.echo(f"Uninstalled '{name}'.")
         else:
-            click.echo("Module '{}' not found on device.".format(name))
+            click.echo(f"Module '{name}' not found on device.")
         continue
 
 
@@ -581,7 +639,9 @@ def update(ctx, update_all):  # pragma: no cover
     """
     logger.info("Update")
     # Grab current modules.
-    bundles_list = get_bundles_list(ctx.obj["BUNDLE_TAGS"])
+    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]
 
@@ -591,7 +651,7 @@ def update(ctx, update_all):  # pragma: no cover
 
     # Process out of date modules
     updated_modules = []
-    click.echo("Found {} module[s] needing update.".format(len(modules_to_update)))
+    click.echo(f"Found {len(modules_to_update)} module[s] needing update.")
     if not update_all:
         click.echo("Please indicate which module[s] you wish to update:\n")
     for module in modules_to_update:
@@ -630,22 +690,20 @@ def update(ctx, update_all):  # pragma: no cover
                 update_flag = click.confirm("Do you want to update?")
             elif module.major_update:
                 update_flag = click.confirm(
-                    (
-                        "'{}' is a Major Version update and may contain breaking "
-                        "changes. Do you want to update?".format(module.name)
-                    )
+                    "'{}' is a Major Version update and may contain breaking "
+                    "changes. Do you want to update?".format(module.name)
                 )
             else:
-                update_flag = click.confirm("Update '{}'?".format(module.name))
+                update_flag = click.confirm(f"Update '{module.name}'?")
         if update_flag:
             # pylint: disable=broad-except
             try:
                 ctx.obj["backend"].update(module)
                 updated_modules.append(module.name)
-                click.echo("Updated {}".format(module.name))
+                click.echo(f"Updated {module.name}")
             except Exception as ex:
                 logger.exception(ex)
-                click.echo("Something went wrong, {} (check the logs)".format(str(ex)))
+                click.echo(f"Something went wrong, {str(ex)} (check the logs)")
             # pylint: enable=broad-except
 
     if not updated_modules:
@@ -728,6 +786,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:

circup/lazy_metadata.py

@@ -5,7 +5,8 @@
 Class that acts similar to a dictionary, but defers the loading of expensive
 data until that data is accessed.
 """
-from typing import Any, Callable
+from typing import Any
+from collections.abc import Callable
 
 
 class LazyMetadata:

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

@@ -22,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
@@ -131,7 +134,7 @@ def extract_metadata(path, logger):
     logger.info("%s", path)
     if path.endswith(".py"):
         result["mpy"] = False
-        with open(path, "r", encoding="utf-8") as source_file:
+        with open(path, encoding="utf-8") as source_file:
             content = source_file.read()
         #: The regex used to extract ``__version__`` and ``__repo__`` assignments.
         dunder_key_val = r"""(__\w+__)(?:\s*:\s*\w+)?\s*=\s*(?:['"]|\(\s)(.+)['"]"""

circup/wwshell/commands.py

@@ -115,7 +115,7 @@ def main(  # pylint: disable=too-many-locals
         verbose_handler.setLevel(logging.INFO)
         verbose_handler.setFormatter(log_formatter)
         logger.addHandler(verbose_handler)
-        click.echo("Logging to {}\n".format(LOGFILE))
+        click.echo(f"Logging to {LOGFILE}\n")
     else:
         ctx.obj["verbose"] = False
 
@@ -137,7 +137,7 @@ def main(  # pylint: disable=too-many-locals
         click.secho("Could not find a connected CircuitPython device.", fg="red")
         sys.exit(1)
     else:
-        click.echo("Found device at {}.".format(device_path))
+        click.echo(f"Found device at {device_path}.")
 
 
 @main.command("ls")

{circup-2.3.0.dist-info → circup-3.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: circup
-Version: 2.3.0
+Version: 3.0.0
 Summary: A tool to manage/update libraries on CircuitPython devices.
 Author-email: Adafruit Industries <circuitpython@adafruit.com>
 License: MIT License
@@ -42,7 +42,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Topic :: Education
 Classifier: Topic :: Software Development :: Embedded Systems
 Classifier: Topic :: System :: Software Distribution
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 Requires-Dist: appdirs

circup-3.0.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+circup/__init__.py,sha256=9A98U3DyA14tm-7_d88fGSlLfEKz9T_85t8kXkErqRg,662
+circup/backends.py,sha256=bm90_c3twTFZw0sDEXwytdV3LoJHUh9v01IDuzWKS5E,39812
+circup/bundle.py,sha256=IdRCuV8smHGKbGkh-GDVfJ_Txkhuu4IwvighUJezn8c,9437
+circup/command_utils.py,sha256=-3nK98EEg2d37y0tuZwAESPrq6sroPkMcoDqOfd40Xs,37087
+circup/commands.py,sha256=gPj6S2eUc6xlLcB8MPlWXZRJ5fe9CCcWqMi7qyKhR10,33885
+circup/lazy_metadata.py,sha256=GJXHkctUJyEzOCycmb7EPZT1GeES7rtX0w1tCtdtT6E,3791
+circup/logging.py,sha256=hu4v8ljkXo8ru-cqs0W3PU-xEVvTO_qqMKDJM18OXbQ,1115
+circup/module.py,sha256=ZrgZhBKuDWHfw9FzcXKjBYx-oybbDnH_IAdek3aSGwU,7131
+circup/shared.py,sha256=yaAL61iJPSA98eJfjyAuOnxVhOFYJXvVZ8yE6aDOUjk,8747
+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=duMirWQqUDup6EqkeAgwdjcdccTaiZYTLTYjId_RBto,7438
+circup-3.0.0.dist-info/licenses/LICENSE,sha256=bVlIMmSL_pqLCqae4hzixy9pYXD808IbgsMoQXTNLBk,1076
+circup-3.0.0.dist-info/METADATA,sha256=bkXUohS9dz58rQ861CBrtQwqppDlvfGKt_9vN_mt9nA,13618
+circup-3.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+circup-3.0.0.dist-info/entry_points.txt,sha256=FjTmwYD_ApgLRGifUrr_Ui1voW6fEzodQc3DKNzoAPc,69
+circup-3.0.0.dist-info/top_level.txt,sha256=Qx6E0eZgSBE10ciNKsLZx8-TTy_9fEVZh7NLmn24KcU,7
+circup-3.0.0.dist-info/RECORD,,

{circup-2.3.0.dist-info → circup-3.0.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.3.0.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=eQ_PxMaDD_XKfxXMXcpzSnhHjx5oJh1YXZq00o5smiM,7075
-circup/command_utils.py,sha256=_DfnRKinXflkPt-CGaIg_3nBZ6Q2J9yRFS9LXC73k3U,35180
-circup/commands.py,sha256=vZ4iui7IpLIkeaO_LQ5JzIqCPkfcUbrbUmICcLrl9aE,31494
-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=O3_iA1mIsoVPObTzv5tfPCqejJSZitTWb0RMYIEM87w,8635
-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.3.0.dist-info/licenses/LICENSE,sha256=bVlIMmSL_pqLCqae4hzixy9pYXD808IbgsMoQXTNLBk,1076
-circup-2.3.0.dist-info/METADATA,sha256=0PRlXlC9q3DFjK27uGkOPIj3tNYxbhi7ciaL8epvyKQ,13617
-circup-2.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-circup-2.3.0.dist-info/entry_points.txt,sha256=FjTmwYD_ApgLRGifUrr_Ui1voW6fEzodQc3DKNzoAPc,69
-circup-2.3.0.dist-info/top_level.txt,sha256=Qx6E0eZgSBE10ciNKsLZx8-TTy_9fEVZh7NLmn24KcU,7
-circup-2.3.0.dist-info/RECORD,,