circup 2.0.4__tar.gz → 2.1.1__tar.gz

{circup-2.0.4 → circup-2.1.1}/CONTRIBUTING.rst

@@ -25,7 +25,7 @@ Developer Setup
 
 .. note::
 
-    Please try to use Python 3.9+ while developing CircUp. This is so we can
+    Please try to use Python 3.9+ while developing Circup. This is so we can
     use the
     `Black code formatter <https://black.readthedocs.io/en/stable/index.html>`_
     and so that we're supporting versions which still receive security updates.
@@ -100,7 +100,7 @@ subsequently used to facilitate the various commands the tool makes available.
 
 These commands are defined at the very end of the ``circup.py`` code.
 
-Unit tests can be found in the ``tests`` directory. CircUp uses
+Unit tests can be found in the ``tests`` directory. Circup uses
 `pytest <http://www.pytest.org/en/latest/>`_ style testing conventions. Test
 functions should include a comment to describe its *intention*. We currently
 have 100% unit test coverage for all the core functionality (excluding
@@ -124,7 +124,7 @@ available options to help you work with the code base.
 Before submitting a PR, please remember to ``pre-commit run --all-files``.
 But if  you forget the CI process in Github will run it for you. ;-)
 
-CircUp uses the `Click <https://click.palletsprojects.com/en/7.x/>`_ module to
+Circup uses the `Click <https://click.palletsprojects.com>`_ module to
 run command-line interaction. The
 `AppDirs <https://pypi.org/project/appdirs/>`_ module is used to determine
 where to store user-specific assets created by the tool in such a way that

{circup-2.0.4/circup.egg-info → circup-2.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: circup
-Version: 2.0.4
+Version: 2.1.1
 Summary: A tool to manage/update libraries on CircuitPython devices.
 Author-email: Adafruit Industries <circuitpython@adafruit.com>
 License: MIT License
@@ -59,7 +59,7 @@ Requires-Dist: pytest-faulthandler; extra == "optional"
 Requires-Dist: pytest-random-order; extra == "optional"
 
 
-CircUp
+Circup
 ======
 
 .. image:: https://readthedocs.org/projects/circup/badge/?version=latest
@@ -88,7 +88,7 @@ A tool to manage and update libraries (modules) on a CircuitPython device.
 Installation
 ------------
 
-Circup requires Python 3.5 or higher.
+Circup requires Python 3.9 or higher.
 
 In a `virtualenv <https://virtualenv.pypa.io/en/latest/>`_,
 ``pip install circup`` should do the trick. This is the simplest way to make it
@@ -99,7 +99,7 @@ If you have no idea what a virtualenv is, try the following command,
 
 .. note::
 
-    If you use the ``pip3`` command to install CircUp you must make sure that
+    If you use the ``pip3`` command to install Circup you must make sure that
     your path contains the directory into which the script will be installed.
     To discover this path,
 
@@ -136,7 +136,7 @@ Usage
 -----
 
 If you need more detailed help using Circup see the Learn Guide article
-`"Use CircUp to easily keep your CircuitPython libraries up to date" <https://learn.adafruit.com/keep-your-circuitpython-libraries-on-devices-up-to-date-with-circup/>`_.
+`"Use Circup to easily keep your CircuitPython libraries up to date" <https://learn.adafruit.com/keep-your-circuitpython-libraries-on-devices-up-to-date-with-circup/>`_.
 
 First, plug in a device running CircuiPython. This should appear as a mounted
 storage device called ``CIRCUITPY``.
@@ -290,7 +290,7 @@ The ``--version`` flag will tell you the current version of the
 ``circup`` command itself::
 
     $ circup --version
-    CircUp, A CircuitPython module updater. Version 0.0.1
+    Circup, A CircuitPython module updater. Version 0.0.1
 
 
 To use circup via the `Web Workflow <https://learn.adafruit.com/getting-started-with-web-workflow-using-the-code-editor>`_. on devices that support it. Use the ``--host`` and ``--password`` arguments before your circup command.::
@@ -323,6 +323,7 @@ For Bash, add this to ~/.bashrc::
 
 For Zsh, add this to ~/.zshrc::
 
+    autoload -U compinit; compinit
     eval "$(_CIRCUP_COMPLETE=zsh_source circup)"
 
 For Fish, add this to ~/.config/fish/completions/foo-bar.fish::

{circup-2.0.4 → circup-2.1.1}/README.rst

@@ -1,5 +1,5 @@
 
-CircUp
+Circup
 ======
 
 .. image:: https://readthedocs.org/projects/circup/badge/?version=latest
@@ -28,7 +28,7 @@ A tool to manage and update libraries (modules) on a CircuitPython device.
 Installation
 ------------
 
-Circup requires Python 3.5 or higher.
+Circup requires Python 3.9 or higher.
 
 In a `virtualenv <https://virtualenv.pypa.io/en/latest/>`_,
 ``pip install circup`` should do the trick. This is the simplest way to make it
@@ -39,7 +39,7 @@ If you have no idea what a virtualenv is, try the following command,
 
 .. note::
 
-    If you use the ``pip3`` command to install CircUp you must make sure that
+    If you use the ``pip3`` command to install Circup you must make sure that
     your path contains the directory into which the script will be installed.
     To discover this path,
 
@@ -76,7 +76,7 @@ Usage
 -----
 
 If you need more detailed help using Circup see the Learn Guide article
-`"Use CircUp to easily keep your CircuitPython libraries up to date" <https://learn.adafruit.com/keep-your-circuitpython-libraries-on-devices-up-to-date-with-circup/>`_.
+`"Use Circup to easily keep your CircuitPython libraries up to date" <https://learn.adafruit.com/keep-your-circuitpython-libraries-on-devices-up-to-date-with-circup/>`_.
 
 First, plug in a device running CircuiPython. This should appear as a mounted
 storage device called ``CIRCUITPY``.
@@ -230,7 +230,7 @@ The ``--version`` flag will tell you the current version of the
 ``circup`` command itself::
 
     $ circup --version
-    CircUp, A CircuitPython module updater. Version 0.0.1
+    Circup, A CircuitPython module updater. Version 0.0.1
 
 
 To use circup via the `Web Workflow <https://learn.adafruit.com/getting-started-with-web-workflow-using-the-code-editor>`_. on devices that support it. Use the ``--host`` and ``--password`` arguments before your circup command.::
@@ -263,6 +263,7 @@ For Bash, add this to ~/.bashrc::
 
 For Zsh, add this to ~/.zshrc::
 
+    autoload -U compinit; compinit
     eval "$(_CIRCUP_COMPLETE=zsh_source circup)"
 
 For Fish, add this to ~/.config/fish/completions/foo-bar.fish::

{circup-2.0.4 → circup-2.1.1}/circup/__init__.py

@@ -2,7 +2,7 @@
 #
 # SPDX-License-Identifier: MIT
 """
-CircUp -- a utility to manage and update libraries on a CircuitPython device.
+Circup -- a utility to manage and update libraries on a CircuitPython device.
 """
 
 

{circup-2.0.4 → circup-2.1.1}/circup/backends.py

@@ -73,7 +73,7 @@ class Backend:
         """
         return self.get_modules(os.path.join(self.device_location, self.LIB_DIR_PATH))
 
-    def _create_library_directory(self, device_path, library_path):
+    def create_directory(self, device_path, directory):
         """
         To be overridden by subclass
         """
@@ -97,6 +97,12 @@ class Backend:
         """
         raise NotImplementedError
 
+    def upload_file(self, target_file, location_to_paste):
+        """Paste a copy of the specified file at the location given
+        To be overridden by subclass
+        """
+        raise NotImplementedError
+
     # pylint: disable=too-many-locals,too-many-branches,too-many-arguments,too-many-nested-blocks,too-many-statements
     def install_module(
         self, device_path, device_modules, name, pyext, mod_names, upgrade=False
@@ -189,7 +195,7 @@ class Backend:
                 return
 
             # Create the library directory first.
-            self._create_library_directory(device_path, library_path)
+            self.create_directory(device_path, library_path)
             if local_path is None:
                 if pyext:
                     # Use Python source for module.
@@ -281,7 +287,9 @@ class WebBackend(Backend):
     ):
         super().__init__(logger)
         if password is None:
-            raise ValueError("--host needs --password")
+            raise ValueError(
+                "Must pass --password or set CIRCUP_WEBWORKFLOW_PASSWORD environment variable"
+            )
 
         # pylint: disable=no-member
         # verify hostname/address
@@ -306,6 +314,7 @@ class WebBackend(Backend):
         self.library_path = self.device_location + "/" + self.LIB_DIR_PATH
         self.timeout = timeout
         self.version_override = version_override
+        self.FS_URL = urljoin(self.device_location, self.FS_PATH)
 
     def __repr__(self):
         return f"<WebBackend @{self.device_location}>"
@@ -546,10 +555,9 @@ class WebBackend(Backend):
             metadata["path"] = sfm_url
             result[sfm[:idx]] = metadata
 
-    def _create_library_directory(self, device_path, library_path):
-        url = urlparse(device_path)
-        auth = HTTPBasicAuth("", url.password)
-        with self.session.put(library_path, auth=auth, timeout=self.timeout) as r:
+    def create_directory(self, device_path, directory):
+        auth = HTTPBasicAuth("", self.password)
+        with self.session.put(directory, auth=auth, timeout=self.timeout) as r:
             if r.status_code == 409:
                 _writeable_error()
             r.raise_for_status()
@@ -560,11 +568,56 @@ class WebBackend(Backend):
                 self.device_location,
                 "/".join(("fs", location_to_paste, target_file, "")),
             )
-            self._create_library_directory(self.device_location, create_directory_url)
+            self.create_directory(self.device_location, create_directory_url)
             self.install_dir_http(target_file)
         else:
             self.install_file_http(target_file)
 
+    def upload_file(self, target_file, location_to_paste):
+        """
+        copy a file from the host PC to the microcontroller
+        :param target_file: file on the host PC to copy
+        :param location_to_paste: Location on the microcontroller to paste it.
+        :return:
+        """
+        if os.path.isdir(target_file):
+            create_directory_url = urljoin(
+                self.device_location,
+                "/".join(("fs", location_to_paste, target_file, "")),
+            )
+            self.create_directory(self.device_location, create_directory_url)
+            self.install_dir_http(target_file, location_to_paste)
+        else:
+            self.install_file_http(target_file, location_to_paste)
+
+    def download_file(self, target_file, location_to_paste):
+        """
+        Download a file from the MCU device to the local host PC
+        :param target_file: The file on the MCU to download
+        :param location_to_paste: The location on the host PC to put the downloaded copy.
+        :return:
+        """
+        auth = HTTPBasicAuth("", self.password)
+        with self.session.get(
+            self.FS_URL + target_file, timeout=self.timeout, auth=auth
+        ) as r:
+            if r.status_code == 404:
+                click.secho(f"{target_file} was not found on the device", "red")
+
+            file_name = target_file.split("/")[-1]
+            if location_to_paste is None:
+                with open(file_name, "wb") as f:
+                    f.write(r.content)
+
+                click.echo(f"Downloaded File: {file_name}")
+            else:
+                with open(os.path.join(location_to_paste, file_name), "wb") as f:
+                    f.write(r.content)
+
+                click.echo(
+                    f"Downloaded File: {os.path.join(location_to_paste, file_name)}"
+                )
+
     def install_module_mpy(self, bundle, metadata):
         """
         :param bundle library bundle.
@@ -668,11 +721,7 @@ class WebBackend(Backend):
         """
         retuns the full path on the device to a given file name.
         """
-        return urljoin(
-            urljoin(self.device_location, "fs/", allow_fragments=False),
-            filename,
-            allow_fragments=False,
-        )
+        return "/".join((self.device_location, "fs", filename))
 
     def is_device_present(self):
         """
@@ -743,6 +792,19 @@ class WebBackend(Backend):
                 return r.json()["free"] * r.json()["block_size"]  # bytes
             sys.exit(1)
 
+    def list_dir(self, dirpath):
+        """
+        Returns the list of files located in the given dirpath.
+        """
+        auth = HTTPBasicAuth("", self.password)
+        with self.session.get(
+            urljoin(self.device_location, f"fs/{dirpath if dirpath else ''}"),
+            auth=auth,
+            headers={"Accept": "application/json"},
+            timeout=self.timeout,
+        ) as r:
+            return r.json()["files"]
+
 
 class DiskBackend(Backend):
     """
@@ -821,9 +883,9 @@ class DiskBackend(Backend):
         """
         return _get_modules_file(device_lib_path, self.logger)
 
-    def _create_library_directory(self, device_path, library_path):
-        if not os.path.exists(library_path):  # pragma: no cover
-            os.makedirs(library_path)
+    def create_directory(self, device_path, directory):
+        if not os.path.exists(directory):  # pragma: no cover
+            os.makedirs(directory)
 
     def copy_file(self, target_file, location_to_paste):
         target_filename = target_file.split(os.path.sep)[-1]
@@ -838,6 +900,9 @@ class DiskBackend(Backend):
                 os.path.join(self.device_location, location_to_paste, target_filename),
             )
 
+    def upload_file(self, target_file, location_to_paste):
+        self.copy_file(target_file, location_to_paste)
+
     def install_module_mpy(self, bundle, metadata):
         """
         :param bundle library bundle.
@@ -885,7 +950,10 @@ class DiskBackend(Backend):
             # Copy the directory.
             shutil.copytree(source_path, target_path)
         else:
-            target = os.path.basename(source_path)
+            if "target_name" in metadata:
+                target = metadata["target_name"]
+            else:
+                target = os.path.basename(source_path)
             target_path = os.path.join(location, target)
             # Copy file.
             shutil.copyfile(source_path, target_path)

{circup-2.0.4 → circup-2.1.1}/circup/command_utils.py

@@ -100,6 +100,7 @@ def completion_for_example(ctx, param, incomplete):
     Returns the list of available modules for the command line tab-completion
     with the ``circup example`` command.
     """
+
     # pylint: disable=unused-argument, consider-iterating-dictionary
     available_examples = get_bundle_examples(get_bundles_list(), avoid_download=True)
 
@@ -319,14 +320,22 @@ def get_bundle_examples(bundles_list, avoid_download=False):
     :return: A dictionary of metadata about the examples available in the
              library bundle.
     """
-    # pylint: disable=too-many-nested-blocks
+    # pylint: disable=too-many-nested-blocks,too-many-locals
     all_the_examples = dict()
+    bundle_examples = dict()
 
     try:
         for bundle in bundles_list:
             if not avoid_download or not os.path.isdir(bundle.lib_dir("py")):
                 ensure_latest_bundle(bundle)
             path = bundle.examples_dir("py")
+            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:
+                    bundle_examples = json.load(f)
+                all_the_examples.update(bundle_examples)
+                bundle_examples.clear()
+                continue
             path_examples = _get_modules_file(path, logger)
             for lib_name, lib_metadata in path_examples.items():
                 for _dir_level in os.walk(lib_metadata["path"]):
@@ -337,8 +346,13 @@ def get_bundle_examples(bundles_list, avoid_download=False):
                         if _dirs[-1] == "":
                             _dirs.pop(-1)
                         slug = f"{os.path.sep}".join(_dirs + [_file.replace(".py", "")])
+                        bundle_examples[slug] = os.path.join(_dir_level[0], _file)
                         all_the_examples[slug] = os.path.join(_dir_level[0], _file)
 
+            with open(meta_saved, "w", encoding="utf-8") as f:
+                json.dump(bundle_examples, f)
+            bundle_examples.clear()
+
     except NotADirectoryError:
         # Bundle does not have new style examples directory
         # so we cannot include its examples.
@@ -625,3 +639,29 @@ def get_device_path(host, port, password, path):
     else:
         device_path = find_device()
     return device_path
+
+
+def sorted_by_directory_then_alpha(list_of_files):
+    """
+    Sort the list of files into alphabetical seperated
+    with directories grouped together before files.
+    """
+    dirs = {}
+    files = {}
+
+    for cur_file in list_of_files:
+        if cur_file["directory"]:
+            dirs[cur_file["name"]] = cur_file
+        else:
+            files[cur_file["name"]] = cur_file
+
+    sorted_dir_names = sorted(dirs.keys())
+    sorted_file_names = sorted(files.keys())
+
+    sorted_full_list = []
+    for cur_name in sorted_dir_names:
+        sorted_full_list.append(dirs[cur_name])
+    for cur_name in sorted_file_names:
+        sorted_full_list.append(files[cur_name])
+
+    return sorted_full_list

{circup-2.0.4 → circup-2.1.1}/circup/commands.py

@@ -84,7 +84,7 @@ from circup.command_utils import (
     "with --board-id, it overrides the detected CPy version.",
 )
 @click.version_option(
-    prog_name="CircUp",
+    prog_name="Circup",
     message="%(prog)s, A CircuitPython module updater. Version %(version)s",
 )
 @click.pass_context
@@ -94,7 +94,7 @@ def main(  # pylint: disable=too-many-locals
     """
     A tool to manage and update libraries on a CircuitPython device.
     """
-    # pylint: disable=too-many-arguments,too-many-branches,too-many-statements,too-many-locals
+    # pylint: disable=too-many-arguments,too-many-branches,too-many-statements,too-many-locals, R0801
     ctx.ensure_object(dict)
     ctx.obj["TIMEOUT"] = timeout
 
@@ -178,8 +178,8 @@ def main(  # pylint: disable=too-many-locals
             else (cpy_version, board_id)
         )
         click.echo(
-            "Found device at {}, running CircuitPython {}.".format(
-                device_path, cpy_version
+            "Found device {} at {}, running CircuitPython {}.".format(
+                board_id, device_path, cpy_version
             )
         )
     try:
@@ -406,31 +406,53 @@ def install(
 
 @main.command()
 @click.option("--overwrite", is_flag=True, help="Overwrite the file if it exists.")
+@click.option("--list", "-ls", "op_list", is_flag=True, help="List available examples.")
+@click.option("--rename", is_flag=True, help="Install the example as code.py.")
 @click.argument(
-    "examples", required=True, nargs=-1, shell_complete=completion_for_example
+    "examples", required=False, nargs=-1, shell_complete=completion_for_example
 )
 @click.pass_context
-def example(ctx, examples, overwrite):
+def example(ctx, examples, op_list, rename, overwrite):
     """
     Copy named example(s) from a bundle onto the device. Multiple examples
     can be installed at once by providing more than one example name, each
     separated by a space.
     """
 
+    if op_list:
+        if examples:
+            click.echo("\n".join(completion_for_example(ctx, "", examples)))
+        else:
+            click.echo("Available example libraries:")
+            available_examples = get_bundle_examples(
+                get_bundles_list(), avoid_download=True
+            )
+            lib_names = {
+                str(key.split(os.path.sep)[0]): value
+                for key, value in available_examples.items()
+            }
+            click.echo("\n".join(sorted(lib_names.keys())))
+        return
+
     for example_arg in examples:
         available_examples = get_bundle_examples(
             get_bundles_list(), avoid_download=True
         )
         if example_arg in available_examples:
             filename = available_examples[example_arg].split(os.path.sep)[-1]
+            install_metadata = {"path": available_examples[example_arg]}
+
+            filename = available_examples[example_arg].split(os.path.sep)[-1]
+            if rename:
+                if os.path.isfile(available_examples[example_arg]):
+                    filename = "code.py"
+                    install_metadata["target_name"] = filename
 
             if overwrite or not ctx.obj["backend"].file_exists(filename):
                 click.echo(
                     f"{'Copying' if not overwrite else 'Overwriting'}: {filename}"
                 )
-                ctx.obj["backend"].install_module_py(
-                    {"path": available_examples[example_arg]}, location=""
-                )
+                ctx.obj["backend"].install_module_py(install_metadata, location="")
             else:
                 click.secho(
                     f"File: {filename} already exists. Use --overwrite if you wish to replace it.",

{circup-2.0.4 → circup-2.1.1}/circup/shared.py

@@ -79,14 +79,18 @@ def _get_modules_file(path, logger):
         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
+        # put __init__ first if any, assumed to have the version number
+        all_files.sort()
         # 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
+                # don't replace metadata if already found
+                if "__version__" not in result[name]:
+                    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

circup-2.1.1/circup/wwshell/README.rst

@@ -0,0 +1,105 @@
+
+wwshell
+=======
+
+.. image:: https://readthedocs.org/projects/circup/badge/?version=latest
+    :target: https://circuitpython.readthedocs.io/projects/circup/en/latest/
+    :alt: Documentation Status
+
+.. image:: https://img.shields.io/discord/327254708534116352.svg
+    :target: https://adafru.it/discord
+    :alt: Discord
+
+
+.. image:: https://github.com/adafruit/circup/workflows/Build%20CI/badge.svg
+    :target: https://github.com/adafruit/circup/actions
+    :alt: Build Status
+
+
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+    :target: https://github.com/psf/black
+    :alt: Code Style: Black
+
+
+A tool to manage files on a CircuitPython device via wireless workflows.
+Currently supports Web Workflow.
+
+.. contents::
+
+Installation
+------------
+
+wwshell is bundled along with Circup. When you install Circup you'll get wwshell automatically.
+
+Circup requires Python 3.5 or higher.
+
+In a `virtualenv <https://virtualenv.pypa.io/en/latest/>`_,
+``pip install circup`` should do the trick. This is the simplest way to make it
+work.
+
+If you have no idea what a virtualenv is, try the following command,
+``pip3 install --user circup``.
+
+.. note::
+
+    If you use the ``pip3`` command to install CircUp you must make sure that
+    your path contains the directory into which the script will be installed.
+    To discover this path,
+
+    * On Unix-like systems, type ``python3 -m site --user-base`` and append
+      ``bin`` to the resulting path.
+    * On Windows, type the same command, but append ``Scripts`` to the
+      resulting path.
+
+What does wwshell do?
+---------------------
+
+It lets you view, delete, upload, and download files from your Circuitpython device
+via wireless workflows. Similar to ampy, but operates over wireless workflow rather
+than USB serial.
+
+Usage
+-----
+
+To use web workflow you need to enable it by putting WIFI credentials and a web workflow
+password into your settings.toml file. `See here <https://learn.adafruit.com/getting-started-with-web-workflow-using-the-code-editor/device-setup>`_,
+
+To get help, just type the command::
+
+    $ wwshell
+    Usage: wwshell [OPTIONS] COMMAND [ARGS]...
+
+      A tool to manage files CircuitPython device over web workflow.
+
+    Options:
+      --verbose          Comprehensive logging is sent to stdout.
+      --path DIRECTORY   Path to CircuitPython directory. Overrides automatic path
+                         detection.
+      --host TEXT        Hostname or IP address of a device. Overrides automatic
+                         path detection.
+      --password TEXT    Password to use for authentication when --host is used.
+                         You can optionally set an environment variable
+                         CIRCUP_WEBWORKFLOW_PASSWORD instead of passing this
+                         argument. If both exist the CLI arg takes precedent.
+      --timeout INTEGER  Specify the timeout in seconds for any network
+                         operations.
+      --version          Show the version and exit.
+      --help             Show this message and exit.
+
+    Commands:
+      get  Download a copy of a file or directory from the device to the...
+      ls   Lists the contents of a directory.
+      put  Upload a copy of a file or directory from the local computer to...
+      rm   Delete a file on the device.
+
+
+.. note::
+
+    If you find a bug, or you want to suggest an enhancement or new feature
+    feel free to create an issue or submit a pull request here:
+
+    https://github.com/adafruit/circup
+
+
+Discussion of this tool happens on the Adafruit CircuitPython
+`Discord channel <https://discord.gg/rqrKDjU>`_.

circup-2.1.1/circup/wwshell/README.rst.license

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2024 Tim Cocks, written for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT

circup-2.1.1/circup/wwshell/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: 2024 Tim Cocks, written for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+"""
+wwshell is a CLI utility for managing files on CircuitPython devices via wireless workflows.
+It currently supports Web Workflow.
+"""
+from .commands import main
+
+
+# Allows execution via `python -m circup ...`
+# pylint: disable=no-value-for-parameter
+if __name__ == "__main__":
+    main()

circup-2.1.1/circup/wwshell/commands.py

@@ -0,0 +1,231 @@
+# SPDX-FileCopyrightText: 2019 Nicholas Tollervey, 2024 Tim Cocks, written for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+"""
+# ----------- CLI command definitions  ----------- #
+
+The following functions have IO side effects (for instance they emit to
+stdout). Ergo, these are not checked with unit tests. Most of the
+functionality they provide is provided by the functions from util_functions.py,
+and the respective Backends which *are* tested. Most of the logic of the following
+functions is to prepare things for presentation to / interaction with the user.
+"""
+import os
+import time
+import sys
+import logging
+import update_checker
+import click
+import requests
+
+
+from circup.backends import WebBackend
+from circup.logging import logger, log_formatter, LOGFILE
+from circup.shared import BOARDLESS_COMMANDS
+
+from circup.command_utils import (
+    get_device_path,
+    get_circup_version,
+    sorted_by_directory_then_alpha,
+)
+
+
+@click.group()
+@click.option(
+    "--verbose", is_flag=True, help="Comprehensive logging is sent to stdout."
+)
+@click.option(
+    "--path",
+    type=click.Path(exists=True, file_okay=False),
+    help="Path to CircuitPython directory. Overrides automatic path detection.",
+)
+@click.option(
+    "--host",
+    help="Hostname or IP address of a device. Overrides automatic path detection.",
+    default="circuitpython.local",
+)
+@click.option(
+    "--port",
+    help="HTTP port that the web workflow is listening on.",
+    default=80,
+)
+@click.option(
+    "--password",
+    help="Password to use for authentication when --host is used."
+    " 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(
+    "--timeout",
+    default=30,
+    help="Specify the timeout in seconds for any network operations.",
+)
+@click.version_option(
+    prog_name="CircFile",
+    message="%(prog)s, A CircuitPython web workflow file managemenr. Version %(version)s",
+)
+@click.pass_context
+def main(  # pylint: disable=too-many-locals
+    ctx,
+    verbose,
+    path,
+    host,
+    port,
+    password,
+    timeout,
+):  # pragma: no cover
+    """
+    A tool to manage files CircuitPython device over web workflow.
+    """
+    # pylint: disable=too-many-arguments,too-many-branches,too-many-statements,too-many-locals, R0801
+    ctx.ensure_object(dict)
+    ctx.obj["TIMEOUT"] = timeout
+
+    if password is None:
+        password = os.getenv("CIRCUP_WEBWORKFLOW_PASSWORD")
+
+    device_path = get_device_path(host, port, password, path)
+
+    using_webworkflow = "host" in ctx.params.keys() and ctx.params["host"] is not None
+    if using_webworkflow:
+        if host == "circuitpython.local":
+            click.echo("Checking versions.json on circuitpython.local to find hostname")
+            versions_resp = requests.get(
+                "http://circuitpython.local/cp/version.json", timeout=timeout
+            )
+            host = f'{versions_resp.json()["hostname"]}.local'
+            click.echo(f"Using hostname: {host}")
+            device_path = device_path.replace("circuitpython.local", host)
+        try:
+            ctx.obj["backend"] = WebBackend(
+                host=host, port=port, password=password, logger=logger, timeout=timeout
+            )
+        except ValueError as e:
+            click.secho(e, fg="red")
+            time.sleep(0.3)
+            sys.exit(1)
+        except RuntimeError as e:
+            click.secho(e, fg="red")
+            sys.exit(1)
+
+    if verbose:
+        # Configure additional logging to stdout.
+        ctx.obj["verbose"] = True
+        verbose_handler = logging.StreamHandler(sys.stdout)
+        verbose_handler.setLevel(logging.INFO)
+        verbose_handler.setFormatter(log_formatter)
+        logger.addHandler(verbose_handler)
+        click.echo("Logging to {}\n".format(LOGFILE))
+    else:
+        ctx.obj["verbose"] = False
+
+    logger.info("### Started Circfile ###")
+
+    # If a newer version of circfile is available, print a message.
+    logger.info("Checking for a newer version of circfile")
+    version = get_circup_version()
+    if version:
+        update_checker.update_check("circfile", 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
+
+    if device_path is None or not ctx.obj["backend"].is_device_present():
+        click.secho("Could not find a connected CircuitPython device.", fg="red")
+        sys.exit(1)
+    else:
+        click.echo("Found device at {}.".format(device_path))
+
+
+@main.command("ls")
+@click.argument("file", required=True, nargs=1, default="/")
+@click.pass_context
+def ls_cli(ctx, file):  # pragma: no cover
+    """
+    Lists the contents of a directory. Defaults to root directory
+    if not supplied.
+    """
+    logger.info("ls")
+    if not file.endswith("/"):
+        file += "/"
+    click.echo(f"running: ls {file}")
+
+    files = ctx.obj["backend"].list_dir(file)
+    click.echo("Size\tName")
+    for cur_file in sorted_by_directory_then_alpha(files):
+        click.echo(
+            f"{cur_file['file_size']}\t{cur_file['name']}{'/' if cur_file['directory'] else ''}"
+        )
+
+
+@main.command("put")
+@click.argument("file", required=True, nargs=1)
+@click.argument("location", required=False, nargs=1, default="")
+@click.option("--overwrite", is_flag=True, help="Overwrite the file if it exists.")
+@click.pass_context
+def put_cli(ctx, file, location, overwrite):
+    """
+    Upload a copy of a file or directory from the local computer
+    to the device
+    """
+    click.echo(f"Attempting PUT: {file} at {location} overwrite? {overwrite}")
+    if not ctx.obj["backend"].file_exists(f"{location}{file}"):
+        ctx.obj["backend"].upload_file(file, location)
+        click.echo(f"Successfully PUT {location}{file}")
+    else:
+        if overwrite:
+            click.secho(
+                f"{location}{file} already exists. Overwriting it.", fg="yellow"
+            )
+            ctx.obj["backend"].upload_file(file, location)
+            click.echo(f"Successfully PUT {location}{file}")
+        else:
+            click.secho(
+                f"{location}{file} already exists. Pass --overwrite if you wish to replace it.",
+                fg="red",
+            )
+
+
+# pylint: enable=too-many-arguments,too-many-locals
+
+
+@main.command("get")
+@click.argument("file", required=True, nargs=1)
+@click.argument("location", required=False, nargs=1)
+@click.pass_context
+def get_cli(ctx, file, location):  # pragma: no cover
+    """
+    Download a copy of a file or directory from the device to the local computer.
+    """
+
+    click.echo(f"running: get {file} {location}")
+    ctx.obj["backend"].download_file(file, location)
+
+
+@main.command("rm")
+@click.argument("file", nargs=1)
+@click.pass_context
+def rm_cli(ctx, file):  # pragma: no cover
+    """
+    Delete a file on the device.
+    """
+    click.echo(f"running: rm {file}")
+    ctx.obj["backend"].uninstall(
+        ctx.obj["backend"].device_location, ctx.obj["backend"].get_file_path(file)
+    )
+
+
+@main.command("mkdir")
+@click.argument("directory", nargs=1)
+@click.pass_context
+def mkdir_cli(ctx, directory):  # pragma: no cover
+    """
+    Create
+    """
+    click.echo(f"running: mkdir {directory}")
+    ctx.obj["backend"].create_directory(
+        ctx.obj["backend"].device_location, ctx.obj["backend"].get_file_path(directory)
+    )

{circup-2.0.4 → circup-2.1.1/circup.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: circup
-Version: 2.0.4
+Version: 2.1.1
 Summary: A tool to manage/update libraries on CircuitPython devices.
 Author-email: Adafruit Industries <circuitpython@adafruit.com>
 License: MIT License
@@ -59,7 +59,7 @@ Requires-Dist: pytest-faulthandler; extra == "optional"
 Requires-Dist: pytest-random-order; extra == "optional"
 
 
-CircUp
+Circup
 ======
 
 .. image:: https://readthedocs.org/projects/circup/badge/?version=latest
@@ -88,7 +88,7 @@ A tool to manage and update libraries (modules) on a CircuitPython device.
 Installation
 ------------
 
-Circup requires Python 3.5 or higher.
+Circup requires Python 3.9 or higher.
 
 In a `virtualenv <https://virtualenv.pypa.io/en/latest/>`_,
 ``pip install circup`` should do the trick. This is the simplest way to make it
@@ -99,7 +99,7 @@ If you have no idea what a virtualenv is, try the following command,
 
 .. note::
 
-    If you use the ``pip3`` command to install CircUp you must make sure that
+    If you use the ``pip3`` command to install Circup you must make sure that
     your path contains the directory into which the script will be installed.
     To discover this path,
 
@@ -136,7 +136,7 @@ Usage
 -----
 
 If you need more detailed help using Circup see the Learn Guide article
-`"Use CircUp to easily keep your CircuitPython libraries up to date" <https://learn.adafruit.com/keep-your-circuitpython-libraries-on-devices-up-to-date-with-circup/>`_.
+`"Use Circup to easily keep your CircuitPython libraries up to date" <https://learn.adafruit.com/keep-your-circuitpython-libraries-on-devices-up-to-date-with-circup/>`_.
 
 First, plug in a device running CircuiPython. This should appear as a mounted
 storage device called ``CIRCUITPY``.
@@ -290,7 +290,7 @@ The ``--version`` flag will tell you the current version of the
 ``circup`` command itself::
 
     $ circup --version
-    CircUp, A CircuitPython module updater. Version 0.0.1
+    Circup, A CircuitPython module updater. Version 0.0.1
 
 
 To use circup via the `Web Workflow <https://learn.adafruit.com/getting-started-with-web-workflow-using-the-code-editor>`_. on devices that support it. Use the ``--host`` and ``--password`` arguments before your circup command.::
@@ -323,6 +323,7 @@ For Bash, add this to ~/.bashrc::
 
 For Zsh, add this to ~/.zshrc::
 
+    autoload -U compinit; compinit
     eval "$(_CIRCUP_COMPLETE=zsh_source circup)"
 
 For Fish, add this to ~/.config/fish/completions/foo-bar.fish::

{circup-2.0.4 → circup-2.1.1}/circup.egg-info/SOURCES.txt

@@ -38,6 +38,10 @@ circup.egg-info/requires.txt
 circup.egg-info/top_level.txt
 circup/config/bundle_config.json
 circup/config/bundle_config.json.license
+circup/wwshell/README.rst
+circup/wwshell/README.rst.license
+circup/wwshell/__init__.py
+circup/wwshell/commands.py
 docs/conf.py
 docs/index.rst
 docs/index.rst.license

{circup-2.0.4 → circup-2.1.1}/circup.egg-info/entry_points.txt

@@ -1,2 +1,3 @@
 [console_scripts]
 circup = circup:main
+wwshell = circup.wwshell:main

{circup-2.0.4 → circup-2.1.1}/docs/conf.py

@@ -109,7 +109,6 @@ if not on_rtd:  # only import and set the theme if we're building docs locally
         import sphinx_rtd_theme
 
         html_theme = "sphinx_rtd_theme"
-        html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), "."]
     except:
         html_theme = "default"
         html_theme_path = ["."]

{circup-2.0.4 → circup-2.1.1}/docs/index.rst

@@ -1,10 +1,12 @@
-.. CircUp documentation master file, created by
+.. Circup documentation master file, created by
    sphinx-quickstart on Mon Sep  2 10:58:36 2019.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
 .. include:: ../README.rst
 
+.. include:: ../circup/wwshell/README.rst
+
 .. include:: ../CONTRIBUTING.rst
 
 API

{circup-2.0.4 → circup-2.1.1}/pyproject.toml

@@ -42,6 +42,7 @@ optional-dependencies = {optional = {file = ["optional_requirements.txt"]}}
 
 [project.scripts]
 circup = "circup:main"
+wwshell = "circup.wwshell:main"
 
 [project.urls]
 homepage = "https://github.com/adafruit/circup"