feat: multi-file get/rm, progress bar for put, env var prefix, binascii fallback

- PR #111: fall back from ubinascii to binascii in the MicroPython-side
  get command, for forward compatibility with firmware that removes ubinascii
- PR #109: add auto_envvar_prefix='AMPY' to the Click group so any future
  option automatically gets an AMPY_* env var without explicit envvar= params
- PR #107: get now accepts multiple remote files via nargs=-1 and saves them
  to a local directory with --output/-o; rm now accepts multiple files
- PR #93: put shows a click progress bar by default; suppress with --no-progress.
  Progress callback added to files.Files.put() for library users

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: curiouswala

ampy/cli.py

@@ -21,6 +21,7 @@
 # SOFTWARE.
 from __future__ import print_function
 import os
+import pathlib
 import platform
 import posixpath
 import re
@@ -70,7 +71,7 @@ def windows_full_port_name(portname):
         return "\\\\.\\{0}".format(portname)
 
 
-@click.group(cls=AmypGroup)
+@click.group(cls=AmypGroup, context_settings={"auto_envvar_prefix": "AMPY"})
 @click.option(
     "--port",
     "-p",
@@ -115,35 +116,54 @@ def cli(port, baud, delay):
 
 
 @cli.command()
-@click.argument("remote_file")
-@click.argument("local_file", type=click.File("wb"), required=False)
-def get(remote_file, local_file):
+@click.argument("remote_files", nargs=-1, required=True)
+@click.option(
+    "--output",
+    "-o",
+    type=click.Path(),
+    default=None,
+    help="Local file or directory to save to. Defaults to printing to stdout.",
+)
+def get(remote_files, output):
     """
     Retrieve a file from the board.
 
     Get will download a file from the board and print its contents or save it
     locally.  You must pass at least one argument which is the path to the file
-    to download from the board.  If you don't specify a second argument then
-    the file contents will be printed to standard output.  However if you pass
-    a file name as the second argument then the contents of the downloaded file
-    will be saved to that file (overwriting anything inside it!).
+    to download from the board.  If you don't specify --output then the file
+    contents will be printed to standard output.  If you pass --output with a
+    file path the downloaded contents will be saved there.  When downloading
+    multiple files, --output must point to an existing local directory.
 
     For example to retrieve the boot.py and print it out run:
 
       ampy --port /board/serial/port get boot.py
 
     Or to get main.py and save it as main.py locally run:
 
-      ampy --port /board/serial/port get main.py main.py
+      ampy --port /board/serial/port get main.py --output main.py
+
+    Or to download multiple files into a local directory:
+
+      ampy --port /board/serial/port get boot.py main.py --output ./local_dir/
     """
-    # Get the file contents.
     board_files = files.Files(_board)
-    contents = board_files.get(remote_file)
-    # Print the file out if no local file was provided, otherwise save it.
-    if local_file is None:
-        print(contents.decode("utf-8"))
+    if len(remote_files) > 1:
+        if output is None or not pathlib.Path(output).is_dir():
+            raise click.UsageError(
+                "A local directory (--output) must be provided when downloading multiple files."
+            )
+        dest_dir = pathlib.Path(output)
+        for remote_file in remote_files:
+            contents = board_files.get(remote_file)
+            dest = dest_dir / pathlib.PurePosixPath(remote_file).name
+            dest.write_bytes(contents)
     else:
-        local_file.write(contents)
+        contents = board_files.get(remote_files[0])
+        if output is None:
+            print(contents.decode("utf-8"))
+        else:
+            pathlib.Path(output).write_bytes(contents)
 
 
 @cli.command()
@@ -228,7 +248,13 @@ def ls(directory, long_format, recursive):
 @cli.command()
 @click.argument("local", type=click.Path(exists=True))
 @click.argument("remote", required=False)
-def put(local, remote):
+@click.option(
+    "--no-progress",
+    is_flag=True,
+    default=False,
+    help="Disable progress bar during file upload.",
+)
+def put(local, remote, no_progress):
     """Put a file or folder and its contents on the board.
 
     Put will upload a local file or folder  to the board.  If the file already
@@ -281,36 +307,58 @@ def put(local, remote):
                 pass
             # Loop through all the files and put them on the board too.
             for filename in child_files:
-                with open(os.path.join(parent, filename), "rb") as infile:
-                    remote_filename = posixpath.join(remote_parent, filename)
-                    board_files.put(remote_filename, infile.read())
-
+                local_path = os.path.join(parent, filename)
+                remote_filename = posixpath.join(remote_parent, filename)
+                with open(local_path, "rb") as infile:
+                    data = infile.read()
+                if no_progress:
+                    board_files.put(remote_filename, data)
+                else:
+                    label = remote_filename
+                    with click.progressbar(
+                        length=len(data), label=label, width=0
+                    ) as bar:
+                        def _cb(written, total, bar=bar, prev=[0]):
+                            bar.update(written - prev[0])
+                            prev[0] = written
+                        board_files.put(remote_filename, data, progress_callback=_cb)
 
     else:
         # File copy, open the file and copy its contents to the board.
-        # Put the file on the board.
         with open(local, "rb") as infile:
-            board_files = files.Files(_board)
-            board_files.put(remote, infile.read())
+            data = infile.read()
+        board_files = files.Files(_board)
+        if no_progress:
+            board_files.put(remote, data)
+        else:
+            with click.progressbar(length=len(data), label=remote, width=0) as bar:
+                def _cb(written, total, bar=bar, prev=[0]):
+                    bar.update(written - prev[0])
+                    prev[0] = written
+                board_files.put(remote, data, progress_callback=_cb)
 
 
 @cli.command()
-@click.argument("remote_file")
-def rm(remote_file):
+@click.argument("remote_files", nargs=-1, required=True)
+def rm(remote_files):
     """Remove a file from the board.
 
-    Remove the specified file from the board's filesystem.  Must specify one
-    argument which is the path to the file to delete.  Note that this can't
-    delete directories which have files inside them, but can delete empty
+    Remove the specified file(s) from the board's filesystem.  Must specify at
+    least one argument which is the path to the file to delete.  Note that this
+    can't delete directories which have files inside them, but can delete empty
     directories.
 
     For example to delete main.py from the root of a board run:
 
       ampy --port /board/serial/port rm main.py
+
+    Or to delete multiple files at once:
+
+      ampy --port /board/serial/port rm main.py boot.py
     """
-    # Delete the provided file/directory on the board.
     board_files = files.Files(_board)
-    board_files.rm(remote_file)
+    for remote_file in remote_files:
+        board_files.rm(remote_file)
 
 
 @cli.command()

ampy/files.py

@@ -60,7 +60,10 @@ def get(self, filename):
         # expects string data.
         command = """
             import sys
-            import ubinascii
+            try:
+                import ubinascii
+            except ImportError:
+                import binascii as ubinascii
             with open('{0}', 'rb') as infile:
                 while True:
                     result = infile.read({1})
@@ -213,8 +216,11 @@ def mkdir(self, directory, exists_okay=False):
                 raise ex
         self._pyboard.exit_raw_repl()
 
-    def put(self, filename, data):
+    def put(self, filename, data, progress_callback=None):
         """Create or update the specified file with the provided data.
+
+        progress_callback, if provided, is called with (bytes_written, total_bytes)
+        after each chunk is written.
         """
         # Open the file for writing on the board and write chunks of data.
         self._pyboard.enter_raw_repl()
@@ -228,6 +234,8 @@ def put(self, filename, data):
             if not chunk.startswith("b"):
                 chunk = "b" + chunk
             self._pyboard.exec_("f.write({0})".format(chunk))
+            if progress_callback:
+                progress_callback(min(i + BUFFER_SIZE, size), size)
         self._pyboard.exec_("f.close()")
         self._pyboard.exit_raw_repl()