circup 2.0.1__py3-none-any.whl

circup/config/bundle_config.json

@@ -0,0 +1,5 @@
+{
+    "adafruit": "adafruit/Adafruit_CircuitPython_Bundle",
+    "circuitpython_community": "adafruit/CircuitPython_Community_Bundle",
+    "circuitpython_org": "circuitpython/CircuitPython_Org_Bundle"
+}

circup/config/bundle_config.json.license

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2021 Patrick Walters
+#
+# SPDX-License-Identifier: MIT

circup/logging.py

@@ -0,0 +1,33 @@
+# SPDX-FileCopyrightText: 2019 Nicholas Tollervey, 2024 Tim Cocks, written for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+"""
+Logging utilities and configuration used by circup
+"""
+import os
+import logging
+from logging.handlers import RotatingFileHandler
+import appdirs
+
+from circup.shared import DATA_DIR
+
+#: The directory containing the utility's log file.
+LOG_DIR = appdirs.user_log_dir(appname="circup", appauthor="adafruit")
+#: The location of the log file for the utility.
+LOGFILE = os.path.join(LOG_DIR, "circup.log")
+
+# Ensure DATA_DIR / LOG_DIR related directories and files exist.
+if not os.path.exists(DATA_DIR):  # pragma: no cover
+    os.makedirs(DATA_DIR)
+if not os.path.exists(LOG_DIR):  # pragma: no cover
+    os.makedirs(LOG_DIR)
+
+# Setup logging.
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.INFO)
+logfile_handler = RotatingFileHandler(LOGFILE, maxBytes=10_000_000, backupCount=0)
+log_formatter = logging.Formatter(
+    "%(asctime)s %(levelname)s: %(message)s", datefmt="%m/%d/%Y %H:%M:%S"
+)
+logfile_handler.setFormatter(log_formatter)
+logger.addHandler(logfile_handler)

circup/module.py

@@ -0,0 +1,209 @@
+# SPDX-FileCopyrightText: 2019 Nicholas Tollervey, 2024 Tim Cocks, written for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+"""
+Class that represents a specific CircuitPython module on a device or in a Bundle.
+"""
+import os
+from urllib.parse import urljoin, urlparse
+from semver import VersionInfo
+
+from circup.shared import BAD_FILE_FORMAT
+from circup.backends import WebBackend
+from circup.logging import logger
+
+
+class Module:
+    """
+    Represents a CircuitPython module.
+    """
+
+    # pylint: disable=too-many-arguments
+
+    def __init__(
+        self,
+        name,
+        backend,
+        repo,
+        device_version,
+        bundle_version,
+        mpy,
+        bundle,
+        compatibility,
+    ):
+        """
+        The ``self.file`` and ``self.name`` attributes are constructed from
+        the ``path`` value. If the path is to a directory based module, the
+        resulting self.file value will be None, and the name will be the
+        basename of the directory path.
+
+        :param str name: The file name of the module.
+        :param Backend backend: The backend that the module is on.
+        :param str repo: The URL of the Git repository for this module.
+        :param str device_version: The semver value for the version on device.
+        :param str bundle_version: The semver value for the version in bundle.
+        :param bool mpy: Flag to indicate if the module is byte-code compiled.
+        :param Bundle bundle: Bundle object where the module is located.
+        :param (str,str) compatibility: Min and max versions of CP compatible with the mpy.
+        """
+        self.name = name
+        self.backend = backend
+        self.path = (
+            urljoin(backend.library_path, name, allow_fragments=False)
+            if isinstance(backend, WebBackend)
+            else os.path.join(backend.library_path, name)
+        )
+
+        url = urlparse(self.path, allow_fragments=False)
+
+        if (
+            url.path.endswith("/")
+            if isinstance(backend, WebBackend)
+            else self.path.endswith(os.sep)
+        ):
+            self.file = None
+            self.name = self.path.split(
+                "/" if isinstance(backend, WebBackend) else os.sep
+            )[-2]
+        else:
+            self.file = os.path.basename(url.path)
+            self.name = (
+                os.path.basename(url.path).replace(".py", "").replace(".mpy", "")
+            )
+
+        self.repo = repo
+        self.device_version = device_version
+        self.bundle_version = bundle_version
+        self.mpy = mpy
+        self.min_version = compatibility[0]
+        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)
+        if self.file:
+            self.bundle_path = os.path.join(search_path, self.file)
+        else:
+            self.bundle_path = os.path.join(search_path, self.name)
+        logger.info(self)
+
+    # pylint: enable=too-many-arguments
+
+    @property
+    def outofdate(self):
+        """
+        Returns a boolean to indicate if this module is out of date.
+        Treat mismatched MPY versions as out of date.
+
+        :return: Truthy indication if the module is out of date.
+        """
+        if self.mpy_mismatch:
+            return True
+        if self.device_version and self.bundle_version:
+            try:
+                return VersionInfo.parse(self.device_version) < VersionInfo.parse(
+                    self.bundle_version
+                )
+            except ValueError as ex:
+                logger.warning("Module '%s' has incorrect semver value.", self.name)
+                logger.warning(ex)
+        return True  # Assume out of date to try to update.
+
+    @property
+    def bad_format(self):
+        """A boolean indicating that the mpy file format could not be identified"""
+        return self.mpy and self.device_version == BAD_FILE_FORMAT
+
+    @property
+    def mpy_mismatch(self):
+        """
+        Returns a boolean to indicate if this module's MPY version is compatible
+        with the board's current version of Circuitpython. A min or max version
+        that evals to False means no limit.
+
+        :return: Boolean indicating if the MPY versions don't match.
+        """
+        if not self.mpy:
+            return False
+        try:
+            cpv = VersionInfo.parse(self.backend.get_circuitpython_version()[0])
+        except ValueError as ex:
+            logger.warning("CircuitPython has incorrect semver value.")
+            logger.warning(ex)
+        try:
+            if self.min_version and cpv < VersionInfo.parse(self.min_version):
+                return True  # CP version too old
+            if self.max_version and cpv >= VersionInfo.parse(self.max_version):
+                return True  # MPY version too old
+        except (TypeError, ValueError) as ex:
+            logger.warning(
+                "Module '%s' has incorrect MPY compatibility information.", self.name
+            )
+            logger.warning(ex)
+        return False
+
+    @property
+    def major_update(self):
+        """
+        Returns a boolean to indicate if this is a major version update.
+
+        :return: Boolean indicating if this is a major version upgrade
+        """
+        try:
+            if (
+                VersionInfo.parse(self.device_version).major
+                == VersionInfo.parse(self.bundle_version).major
+            ):
+                return False
+        except (TypeError, ValueError) as ex:
+            logger.warning("Module '%s' has incorrect semver value.", self.name)
+            logger.warning(ex)
+        return True  # Assume Major Version udpate.
+
+    @property
+    def row(self):
+        """
+        Returns a tuple of items to display in a table row to show the module's
+        name, local version and remote version, and reason to update.
+
+        :return: A tuple containing the module's name, version on the connected
+                 device, version in the latest bundle and reason to update.
+        """
+        loc = self.device_version if self.device_version else "unknown"
+        rem = self.bundle_version if self.bundle_version else "unknown"
+        if self.mpy_mismatch:
+            update_reason = "MPY Format"
+        elif self.major_update:
+            update_reason = "Major Version"
+        else:
+            update_reason = "Minor Version"
+        return (self.name, loc, rem, update_reason)
+
+    def __repr__(self):
+        """
+        Helps with log files.
+
+        :return: A repr of a dictionary containing the module's metadata.
+        """
+        return repr(
+            {
+                "path": self.path,
+                "file": self.file,
+                "name": self.name,
+                "repo": self.repo,
+                "device_version": self.device_version,
+                "bundle_version": self.bundle_version,
+                "bundle_path": self.bundle_path,
+                "mpy": self.mpy,
+                "min_version": self.min_version,
+                "max_version": self.max_version,
+            }
+        )

circup/shared.py

@@ -0,0 +1,218 @@
+# SPDX-FileCopyrightText: 2019 Nicholas Tollervey, written for Adafruit Industries
+# SPDX-FileCopyrightText: 2023 Tim Cocks, written for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+"""
+Utilities that are shared and used by both click CLI command functions
+and Backend class functions.
+"""
+import glob
+import os
+import re
+import json
+import appdirs
+import pkg_resources
+import requests
+
+#: Version identifier for a bad MPY file format
+BAD_FILE_FORMAT = "Invalid"
+
+#: The location of data files used by circup (following OS conventions).
+DATA_DIR = appdirs.user_data_dir(appname="circup", appauthor="adafruit")
+
+#: Module formats list (and the other form used in github files)
+PLATFORMS = {"py": "py", "8mpy": "8.x-mpy", "9mpy": "9.x-mpy"}
+
+#: Timeout for requests calls like get()
+REQUESTS_TIMEOUT = 30
+
+#: The path to the JSON file containing the metadata about the bundles.
+BUNDLE_CONFIG_FILE = pkg_resources.resource_filename(
+    "circup", "config/bundle_config.json"
+)
+#: Overwrite the bundles list with this file (only done manually)
+BUNDLE_CONFIG_OVERWRITE = os.path.join(DATA_DIR, "bundle_config.json")
+#: The path to the JSON file containing the local list of bundles.
+BUNDLE_CONFIG_LOCAL = os.path.join(DATA_DIR, "bundle_config_local.json")
+#: The path to the JSON file containing the metadata about the bundles.
+BUNDLE_DATA = os.path.join(DATA_DIR, "circup.json")
+
+#:  The libraries (and blank lines) which don't go on devices
+NOT_MCU_LIBRARIES = [
+    "",
+    "adafruit-blinka",
+    "adafruit-blinka-bleio",
+    "adafruit-blinka-displayio",
+    "adafruit-circuitpython-typing",
+    "circuitpython_typing",
+    "pyserial",
+]
+
+#: Commands that do not require an attached board
+BOARDLESS_COMMANDS = ["show", "bundle-add", "bundle-remove", "bundle-show"]
+
+
+def _get_modules_file(path, logger):
+    """
+    Get a dictionary containing metadata about all the Python modules found in
+    the referenced file system path.
+
+    :param str path: The directory in which to find modules.
+    :return: A dictionary containing metadata about the found modules.
+    """
+    result = {}
+    if not path:
+        return result
+    single_file_py_mods = glob.glob(os.path.join(path, "*.py"))
+    single_file_mpy_mods = glob.glob(os.path.join(path, "*.mpy"))
+    package_dir_mods = [
+        d
+        for d in glob.glob(os.path.join(path, "*", ""))
+        if not os.path.basename(os.path.normpath(d)).startswith(".")
+    ]
+    single_file_mods = single_file_py_mods + single_file_mpy_mods
+    for sfm in [f for f in single_file_mods if not os.path.basename(f).startswith(".")]:
+        metadata = extract_metadata(sfm, logger)
+        metadata["path"] = sfm
+        result[os.path.basename(sfm).replace(".py", "").replace(".mpy", "")] = metadata
+    for package_path in package_dir_mods:
+        name = os.path.basename(os.path.dirname(package_path))
+        py_files = glob.glob(os.path.join(package_path, "**/*.py"), recursive=True)
+        mpy_files = glob.glob(os.path.join(package_path, "**/*.mpy"), recursive=True)
+        all_files = py_files + mpy_files
+        # default value
+        result[name] = {"path": package_path, "mpy": bool(mpy_files)}
+        # explore all the submodules to detect bad ones
+        for source in [f for f in all_files if not os.path.basename(f).startswith(".")]:
+            metadata = extract_metadata(source, logger)
+            if "__version__" in metadata:
+                metadata["path"] = package_path
+                result[name] = metadata
+                # break now if any of the submodules has a bad format
+                if metadata["__version__"] == BAD_FILE_FORMAT:
+                    break
+    return result
+
+
+def extract_metadata(path, logger):
+    # pylint: disable=too-many-locals,too-many-branches
+    """
+    Given a file path, return a dictionary containing metadata extracted from
+    dunder attributes found therein. Works with both .py and .mpy files.
+
+    For Python source files, such metadata assignments should be simple and
+    single-line. For example::
+
+        __version__ = "1.1.4"
+        __repo__ = "https://github.com/adafruit/SomeLibrary.git"
+
+    For byte compiled .mpy files, a brute force / backtrack approach is used
+    to find the __version__ number in the file -- see comments in the
+    code for the implementation details.
+
+    :param str path: The path to the file containing the metadata.
+    :return: The dunder based metadata found in the file, as a dictionary.
+    """
+    result = {}
+    logger.info("%s", path)
+    if path.endswith(".py"):
+        result["mpy"] = False
+        with open(path, "r", 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)(.+)['"]"""
+        for match in re.findall(dunder_key_val, content):
+            result[match[0]] = str(match[1])
+        if result:
+            logger.info("Extracted metadata: %s", result)
+    elif path.endswith(".mpy"):
+        find_by_regexp_match = False
+        result["mpy"] = True
+        with open(path, "rb") as mpy_file:
+            content = mpy_file.read()
+        # Track the MPY version number
+        mpy_version = content[0:2]
+        compatibility = None
+        loc = -1
+        # Find the start location of the __version__
+        if mpy_version == b"M\x03":
+            # One byte for the length of "__version__"
+            loc = content.find(b"__version__") - 1
+            compatibility = (None, "7.0.0-alpha.1")
+        elif mpy_version == b"C\x05":
+            # Two bytes for the length of "__version__" in mpy version 5
+            loc = content.find(b"__version__") - 2
+            compatibility = ("7.0.0-alpha.1", "8.99.99")
+        elif mpy_version == b"C\x06":
+            # Two bytes in mpy version 6
+            find_by_regexp_match = True
+            compatibility = ("9.0.0-alpha.1", None)
+        if find_by_regexp_match:
+            # Too hard to find the version positionally.
+            # Find the first thing that looks like an x.y.z version number.
+            match = re.search(rb"([\d]+\.[\d]+\.[\d]+)\x00", content)
+            if match:
+                result["__version__"] = match.group(1).decode("utf-8")
+        elif loc > -1:
+            # Backtrack until a byte value of the offset is reached.
+            offset = 1
+            while offset < loc:
+                val = int(content[loc - offset])
+                if mpy_version == b"C\x05":
+                    val = val // 2
+                if val == offset - 1:  # Off by one..!
+                    # Found version, extract the number given boundaries.
+                    start = loc - offset + 1  # No need for prepended length.
+                    end = loc  # Up to the start of the __version__.
+                    version = content[start:end]  # Slice the version number.
+                    # Create a string version as metadata in the result.
+                    result["__version__"] = version.decode("utf-8")
+                    break  # Nothing more to do.
+                offset += 1  # ...and again but backtrack by one.
+        if compatibility:
+            result["compatibility"] = compatibility
+        else:
+            # not a valid MPY file
+            result["__version__"] = BAD_FILE_FORMAT
+    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.
+
+    :param str url: URL to the latest release page on a git repository.
+    :return: The most recent tag value for the release.
+    """
+
+    logger.info("Requesting redirect information: %s", url)
+    response = requests.head(url, timeout=REQUESTS_TIMEOUT)
+    responseurl = response.url
+    if response.is_redirect:
+        responseurl = response.headers["Location"]
+    tag = responseurl.rsplit("/", 1)[-1]
+    logger.info("Tag: '%s'", tag)
+    return tag

circup-2.0.1.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Adafruit Industries
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.