circup 1.6.2__tar.gz → 1.8.0__tar.gz

{circup-1.6.2 → circup-1.8.0}/.gitignore

@@ -19,6 +19,7 @@ downloads/
 eggs/
 .eggs/
 lib/
+!tests/mock_device/lib/
 lib64/
 parts/
 sdist/
@@ -93,6 +94,7 @@ venv/
 ENV/
 env.bak/
 venv.bak/
+*_venv/
 
 # Spyder project settings
 .spyderproject

{circup-1.6.2/circup.egg-info → circup-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: circup
-Version: 1.6.2
+Version: 1.8.0
 Summary: A tool to manage/update libraries on CircuitPython devices.
 Home-page: https://github.com/adafruit/circup
 Author: Adafruit Industries
@@ -57,16 +57,16 @@ Requires-Dist: sphinx; extra == "dev"
 Requires-Dist: wheel; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Provides-Extra: all
-Requires-Dist: black; extra == "all"
-Requires-Dist: pytest-cov; extra == "all"
-Requires-Dist: pytest-random-order>=1.0.0; extra == "all"
-Requires-Dist: sphinx; extra == "all"
-Requires-Dist: coverage; extra == "all"
-Requires-Dist: twine; extra == "all"
 Requires-Dist: wheel; extra == "all"
 Requires-Dist: pytest-faulthandler; extra == "all"
-Requires-Dist: pytest; extra == "all"
+Requires-Dist: coverage; extra == "all"
 Requires-Dist: pylint; extra == "all"
+Requires-Dist: pytest; extra == "all"
+Requires-Dist: twine; extra == "all"
+Requires-Dist: sphinx; extra == "all"
+Requires-Dist: black; extra == "all"
+Requires-Dist: pytest-random-order>=1.0.0; extra == "all"
+Requires-Dist: pytest-cov; extra == "all"
 
 
 CircUp
@@ -165,6 +165,8 @@ To get help, just type the command::
       --host TEXT         Hostname or IP address of a device. Overrides automatic
                           path detection.
       --password TEXT     Password to use for authentication when --host is used.
+      --timeout INTEGER   Specify the timeout in seconds for any network
+                          operations.
       --board-id TEXT     Manual Board ID of the CircuitPython device. If provided
                           in combination with --cpy-version, it overrides the
                           detected board ID.
@@ -177,6 +179,7 @@ To get help, just type the command::
       bundle-add     Add bundles to the local bundles list, by "user/repo"...
       bundle-remove  Remove one or more bundles from the local bundles list.
       bundle-show    Show the list of bundles, default and local, with URL,...
+      example        Copy named example(s) from a bundle onto the device.
       freeze         Output details of all the modules found on the connected...
       install        Install a named module(s) onto the device.
       list           Lists all out of date modules found on the connected...

{circup-1.6.2 → circup-1.8.0}/README.rst

@@ -95,6 +95,8 @@ To get help, just type the command::
       --host TEXT         Hostname or IP address of a device. Overrides automatic
                           path detection.
       --password TEXT     Password to use for authentication when --host is used.
+      --timeout INTEGER   Specify the timeout in seconds for any network
+                          operations.
       --board-id TEXT     Manual Board ID of the CircuitPython device. If provided
                           in combination with --cpy-version, it overrides the
                           detected board ID.
@@ -107,6 +109,7 @@ To get help, just type the command::
       bundle-add     Add bundles to the local bundles list, by "user/repo"...
       bundle-remove  Remove one or more bundles from the local bundles list.
       bundle-show    Show the list of bundles, default and local, with URL,...
+      example        Copy named example(s) from a bundle onto the device.
       freeze         Output details of all the modules found on the connected...
       install        Install a named module(s) onto the device.
       list           Lists all out of date modules found on the connected...

circup-1.8.0/circup/__init__.py

@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: 2019 Nicholas Tollervey, written for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+"""
+CircUp -- a utility to manage and update libraries on a CircuitPython device.
+"""
+
+
+from circup.shared import DATA_DIR, BAD_FILE_FORMAT, extract_metadata, _get_modules_file
+from circup.backends import WebBackend, DiskBackend
+from circup.logging import logger
+
+
+# Useful constants.
+
+
+__version__ = "0.0.0-auto.0"
+__repo__ = "https://github.com/adafruit/circup.git"
+
+
+from circup.commands import *
+
+# Allows execution via `python -m circup ...`
+# pylint: disable=no-value-for-parameter
+if __name__ == "__main__":  # pragma: no cover
+    main()

{circup-1.6.2 → circup-1.8.0}/circup/backends.py

@@ -16,7 +16,6 @@ import requests
 from requests.adapters import HTTPAdapter
 from requests.auth import HTTPBasicAuth
 
-
 from circup.shared import DATA_DIR, BAD_FILE_FORMAT, extract_metadata, _get_modules_file
 
 #: The location to store a local copy of code.py for use with --auto and
@@ -79,13 +78,13 @@ class Backend:
         """
         raise NotImplementedError
 
-    def _install_module_py(self, metadata):
+    def install_module_py(self, metadata, location=None):
         """
         To be overridden by subclass
         """
         raise NotImplementedError
 
-    def _install_module_mpy(self, bundle, metadata):
+    def install_module_mpy(self, bundle, metadata):
         """
         To be overridden by subclass
         """
@@ -93,7 +92,7 @@ class Backend:
 
     # pylint: disable=too-many-locals,too-many-branches,too-many-arguments,too-many-nested-blocks
     def install_module(
-        self, device_path, device_modules, name, pyext, mod_names
+        self, device_path, device_modules, name, pyext, mod_names, upgrade=False
     ):  # pragma: no cover
         """
         Finds a connected device and installs a given module name if it
@@ -108,14 +107,27 @@ class Backend:
                         source or from a pre-compiled module
         :param mod_names: Dictionary of metadata from modules that can be generated
                            with get_bundle_versions()
+        :param bool upgrade: Upgrade the specified modules if they're already installed.
         """
         if not name:
             click.echo("No module name(s) provided.")
         elif name in mod_names:
             # Grab device modules to check if module already installed
             if name in device_modules:
-                click.echo("'{}' is already installed.".format(name))
-                return
+                if not upgrade:
+                    # skip already installed modules if no -upgrade flag
+                    click.echo("'{}' is already installed.".format(name))
+                    return
+
+                # uninstall the module before installing
+                name = name.lower()
+                _mod_names = {}
+                for module_item, _metadata in device_modules.items():
+                    _mod_names[module_item.replace(".py", "").lower()] = _metadata
+                if name in _mod_names:
+                    _metadata = _mod_names[name]
+                    module_path = _metadata["path"]
+                    self.uninstall(device_path, module_path)
 
             library_path = (
                 os.path.join(device_path, self.LIB_DIR_PATH)
@@ -159,10 +171,10 @@ class Backend:
 
             if pyext:
                 # Use Python source for module.
-                self._install_module_py(metadata)
+                self.install_module_py(metadata)
             else:
                 # Use pre-compiled mpy modules.
-                self._install_module_mpy(bundle, metadata)
+                self.install_module_mpy(bundle, metadata)
             click.echo("Installed '{}'.".format(name))
         else:
             click.echo("Unknown module named, '{}'.".format(name))
@@ -219,6 +231,12 @@ class Backend:
             board_id = ""
         return circuit_python, board_id
 
+    def file_exists(self, filepath):
+        """
+        To be overriden by subclass
+        """
+        raise NotImplementedError
+
 
 def _writeable_error():
     click.secho(
@@ -250,7 +268,8 @@ class WebBackend(Backend):
                 else "Could not find or connect to specified device"
             ) from exc
 
-        self.LIB_DIR_PATH = "fs/lib/"
+        self.FS_PATH = "fs/"
+        self.LIB_DIR_PATH = f"{self.FS_PATH}lib/"
         self.host = host
         self.password = password
         self.device_location = f"http://:{self.password}@{self.host}"
@@ -260,14 +279,20 @@ class WebBackend(Backend):
         self.library_path = self.device_location + "/" + self.LIB_DIR_PATH
         self.timeout = timeout
 
-    def install_file_http(self, source):
+    def install_file_http(self, source, location=None):
         """
         Install file to device using web workflow.
         :param source source file.
+        :param location the location on the device to copy the source
+          directory in to. If omitted is CIRCUITPY/lib/ used.
         """
         file_name = source.split(os.path.sep)
         file_name = file_name[-2] if file_name[-1] == "" else file_name[-1]
-        target = self.device_location + "/" + self.LIB_DIR_PATH + file_name
+
+        if location is None:
+            target = self.device_location + "/" + self.LIB_DIR_PATH + file_name
+        else:
+            target = self.device_location + "/" + self.FS_PATH + location + file_name
 
         auth = HTTPBasicAuth("", self.password)
 
@@ -277,14 +302,19 @@ class WebBackend(Backend):
                 _writeable_error()
             r.raise_for_status()
 
-    def install_dir_http(self, source):
+    def install_dir_http(self, source, location=None):
         """
         Install directory to device using web workflow.
         :param source source directory.
+        :param location the location on the device to copy the source
+          directory in to. If omitted is CIRCUITPY/lib/ used.
         """
         mod_name = source.split(os.path.sep)
         mod_name = mod_name[-2] if mod_name[-1] == "" else mod_name[-1]
-        target = self.device_location + "/" + self.LIB_DIR_PATH + mod_name
+        if location is None:
+            target = self.device_location + "/" + self.LIB_DIR_PATH + mod_name
+        else:
+            target = self.device_location + "/" + self.FS_PATH + location + mod_name
         target = target + "/" if target[:-1] != "/" else target
         url = urlparse(target)
         auth = HTTPBasicAuth("", url.password)
@@ -490,7 +520,7 @@ class WebBackend(Backend):
                 _writeable_error()
             r.raise_for_status()
 
-    def _install_module_mpy(self, bundle, metadata):
+    def install_module_mpy(self, bundle, metadata):
         """
         :param bundle library bundle.
         :param library_path library path
@@ -514,7 +544,7 @@ class WebBackend(Backend):
             raise IOError("Cannot find compiled version of module.")
 
     # pylint: enable=too-many-locals,too-many-branches
-    def _install_module_py(self, metadata):
+    def install_module_py(self, metadata, location=None):
         """
         :param library_path library path
         :param metadata dictionary.
@@ -522,10 +552,10 @@ class WebBackend(Backend):
 
         source_path = metadata["path"]  # Path to Python source version.
         if os.path.isdir(source_path):
-            self.install_dir_http(source_path)
+            self.install_dir_http(source_path, location=location)
 
         else:
-            self.install_file_http(source_path)
+            self.install_file_http(source_path, location=location)
 
     def get_auto_file_path(self, auto_file_path):
         """
@@ -560,6 +590,18 @@ class WebBackend(Backend):
         """
         self._update_http(module)
 
+    def file_exists(self, filepath):
+        """
+        return True if the file exists, otherwise False.
+        """
+        auth = HTTPBasicAuth("", self.password)
+        resp = requests.get(
+            self.get_file_path(filepath), auth=auth, timeout=self.timeout
+        )
+        if resp.status_code == 200:
+            return True
+        return False
+
     def _update_http(self, module):
         """
         Update the module using web workflow.
@@ -733,10 +775,9 @@ class DiskBackend(Backend):
         if not os.path.exists(library_path):  # pragma: no cover
             os.makedirs(library_path)
 
-    def _install_module_mpy(self, bundle, metadata):
+    def install_module_mpy(self, bundle, metadata):
         """
         :param bundle library bundle.
-        :param library_path library path
         :param metadata dictionary.
         """
         module_name = os.path.basename(metadata["path"]).replace(".py", ".mpy")
@@ -763,21 +804,26 @@ class DiskBackend(Backend):
             raise IOError("Cannot find compiled version of module.")
 
     # pylint: enable=too-many-locals,too-many-branches
-    def _install_module_py(self, metadata):
+    def install_module_py(self, metadata, location=None):
         """
-        :param library_path library path
         :param metadata dictionary.
+        :param location the location on the device to copy the py module to.
+          If omitted is CIRCUITPY/lib/ used.
         """
+        if location is None:
+            location = self.library_path
+        else:
+            location = os.path.join(self.device_location, location)
 
         source_path = metadata["path"]  # Path to Python source version.
         if os.path.isdir(source_path):
             target = os.path.basename(os.path.dirname(source_path))
-            target_path = os.path.join(self.library_path, target)
+            target_path = os.path.join(location, target)
             # Copy the directory.
             shutil.copytree(source_path, target_path)
         else:
             target = os.path.basename(source_path)
-            target_path = os.path.join(self.library_path, target)
+            target_path = os.path.join(location, target)
             # Copy file.
             shutil.copyfile(source_path, target_path)
 
@@ -825,6 +871,12 @@ class DiskBackend(Backend):
             os.remove(module.path)
             shutil.copyfile(module.bundle_path, module.path)
 
+    def file_exists(self, filepath):
+        """
+        return True if the file exists, otherwise False.
+        """
+        return os.path.exists(os.path.join(self.device_location, filepath))
+
     def get_file_path(self, filename):
         """
         returns the full path on the device to a given file name.

circup-1.8.0/circup/bundle.py

@@ -0,0 +1,170 @@
+# SPDX-FileCopyrightText: 2019 Nicholas Tollervey, 2024 Tim Cocks, written for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+"""
+Class that represents a specific release of a Bundle.
+"""
+import os
+import sys
+
+import click
+import requests
+
+from circup.shared import (
+    DATA_DIR,
+    PLATFORMS,
+    REQUESTS_TIMEOUT,
+    tags_data_load,
+    get_latest_release_from_url,
+)
+
+from circup.logging import logger
+
+
+class Bundle:
+    """
+    All the links and file names for a bundle
+    """
+
+    def __init__(self, repo):
+        """
+        Initialise a Bundle created from its github info.
+        Construct all the strings in one place.
+
+        :param str repo: Repository string for github: "user/repository"
+        """
+        vendor, bundle_id = repo.split("/")
+        bundle_id = bundle_id.lower().replace("_", "-")
+        self.key = repo
+        #
+        self.url = "https://github.com/" + repo
+        self.basename = bundle_id + "-{platform}-{tag}"
+        self.urlzip = self.basename + ".zip"
+        self.dir = os.path.join(DATA_DIR, vendor, bundle_id + "-{platform}")
+        self.zip = os.path.join(DATA_DIR, bundle_id + "-{platform}.zip")
+        self.url_format = self.url + "/releases/download/{tag}/" + self.urlzip
+        # tag
+        self._current = None
+        self._latest = None
+
+    def lib_dir(self, platform):
+        """
+        This bundle's lib directory for the platform.
+
+        :param str platform: The platform identifier (py/6mpy/...).
+        :return: The path to the lib directory for the platform.
+        """
+        tag = self.current_tag
+        return os.path.join(
+            self.dir.format(platform=platform),
+            self.basename.format(platform=PLATFORMS[platform], tag=tag),
+            "lib",
+        )
+
+    def examples_dir(self, platform):
+        """
+        This bundle's examples directory for the platform.
+
+        :param str platform: The platform identifier (py/6mpy/...).
+        :return: The path to the examples directory for the platform.
+        """
+        tag = self.current_tag
+        return os.path.join(
+            self.dir.format(platform=platform),
+            self.basename.format(platform=PLATFORMS[platform], tag=tag),
+            "examples",
+        )
+
+    def requirements_for(self, library_name, toml_file=False):
+        """
+        The requirements file for this library.
+
+        :param str library_name: The name of the library.
+        :return: The path to the requirements.txt file.
+        """
+        platform = "py"
+        tag = self.current_tag
+        found_file = os.path.join(
+            self.dir.format(platform=platform),
+            self.basename.format(platform=PLATFORMS[platform], tag=tag),
+            "requirements",
+            library_name,
+            "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:
+                return read_this.read()
+        return None
+
+    @property
+    def current_tag(self):
+        """
+        Lazy load current cached tag from the BUNDLE_DATA json file.
+
+        :return: The current cached tag value for the project.
+        """
+        if self._current is None:
+            self._current = tags_data_load(logger).get(self.key, "0")
+        return self._current
+
+    @current_tag.setter
+    def current_tag(self, tag):
+        """
+        Set the current cached 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
+
+    @property
+    def latest_tag(self):
+        """
+        Lazy find the value of the latest tag for the 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
+            )
+        return self._latest
+
+    def validate(self):
+        """
+        Test the existence of the expected URLs (not their 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
+        return True
+
+    def __repr__(self):
+        """
+        Helps with log files.
+
+        :return: A repr of a dictionary containing the Bundles's metadata.
+        """
+        return repr(
+            {
+                "key": self.key,
+                "url": self.url,
+                "urlzip": self.urlzip,
+                "dir": self.dir,
+                "zip": self.zip,
+                "url_format": self.url_format,
+                "current": self._current,
+                "latest": self._latest,
+            }
+        )