circup 2.3.0__tar.gz → 3.0.0__tar.gz

{circup-2.3.0/circup.egg-info → circup-3.0.0}/PKG-INFO

@@ -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-2.3.0 → circup-3.0.0}/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-2.3.0 → circup-3.0.0}/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-2.3.0 → circup-3.0.0}/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)