Merge pull request #79 from tekktrik/dev/detect-command

Add detect command

circfirm/cli/detect.py

@@ -0,0 +1,38 @@
+# SPDX-FileCopyrightText: 2024 Alec Delaney, for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+
+"""CLI functionality for the detect subcommand.
+
+Author(s): Alec Delaney
+"""
+
+
+import click
+
+import circfirm.backend.device
+
+
+@click.group()
+def cli() -> None:
+    """Detect connected CircuitPython boards."""
+
+
+@cli.command(name="circuitpy")
+def detect_circuitpy() -> None:
+    """Detect a connected board in CIRCUITPY or equivalent mode."""
+    circuitpy = circfirm.backend.device.find_circuitpy()
+    if not circuitpy:
+        click.echo("No board connected in CIRCUITPY or equivalent mode")
+        return
+    click.echo(circuitpy)
+
+
+@cli.command(name="bootloader")
+def detect_bootloader() -> None:
+    """Detect a connected board in bootloader mode."""
+    bootloader = circfirm.backend.device.find_bootloader()
+    if not bootloader:
+        click.echo("No board connected in bootloader mode")
+        return
+    click.echo(bootloader)

docs/commands/detect.rst

@@ -0,0 +1,30 @@
+..
+    SPDX-FileCopyrightText: 2024 Alec Delaney, for Adafruit Industries
+    SPDX-License-Identifier: MIT
+
+Detecting Connected Boards
+==========================
+
+You can detect connected CircuitPython boards using ``circfirm detect``.
+
+See ``circfirm detect --help`` and ``circfirm detect [command] --help`` for more information on commands.
+
+Detecting a CIRCUITPY Board
+---------------------------
+
+You can detect a connected CircuitPython board in CIRCUITPY or equivalent mode using ``circfirm detect circuitpy``.
+
+.. code-block:: shell
+
+    # Detect a connected board in CIRCUITPY (or equivalent) mode
+    circfirm detect circuitpy
+
+Detecting a Bootloader Board
+----------------------------
+
+You can detect a connected CircuitPython board in bootloader mode using ``circfirm detect bootloader``.
+
+.. code-block:: shell
+
+    # Detect a connected board in bootloader mode
+    circfirm detect bootloader

docs/index.rst

@@ -19,6 +19,7 @@
 
    commands/update
    commands/install
+   commands/detect
    commands/current
    commands/cache
    commands/query

tests/cli/test_cli_detect.py

@@ -0,0 +1,56 @@
+# SPDX-FileCopyrightText: 2024 Alec Delaney, for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+
+"""Tests the CLI functionality for detect command.
+
+Author(s): Alec Delaney
+"""
+
+import pathlib
+
+from click.testing import CliRunner
+
+import tests.helpers
+from circfirm.cli import cli
+
+RUNNER = CliRunner()
+
+
+@tests.helpers.as_circuitpy
+def test_detect_circuitpy_found() -> None:
+    """Tests the ability of the detect circuitpy command to find a connected board."""
+    result = RUNNER.invoke(cli, ["detect", "circuitpy"])
+    assert result.exit_code == 0
+    circuitpy = pathlib.Path(result.output.strip())
+    assert circuitpy.exists()
+    mount = pathlib.Path(tests.helpers.get_mount())
+    assert circuitpy == mount
+
+
+@tests.helpers.as_not_present
+def test_detect_circuitpy_not_found() -> None:
+    """Tests the detect circuitpy command without a connected board."""
+    result = RUNNER.invoke(cli, ["detect", "circuitpy"])
+    assert result.output == "No board connected in CIRCUITPY or equivalent mode\n"
+
+
+@tests.helpers.as_bootloader
+def test_detect_bootloader_found() -> None:
+    """Tests the ability of the detect bootloader command to find a connected board."""
+    import time
+
+    time.sleep(2)
+    result = RUNNER.invoke(cli, ["detect", "bootloader"])
+    assert result.exit_code == 0
+    bootloader = pathlib.Path(result.output.strip())
+    assert bootloader.exists()
+    mount = pathlib.Path(tests.helpers.get_mount())
+    assert bootloader == mount
+
+
+@tests.helpers.as_not_present
+def test_detect_bootloader_not_found() -> None:
+    """Tests the detect bootloader command without a connected board."""
+    result = RUNNER.invoke(cli, ["detect", "bootloader"])
+    assert result.output == "No board connected in bootloader mode\n"