Merge pull request #807 from tiran/cli-entry-points

feat: load CLI commands from entry points

Author: mergify[bot]

docs/customization.md

@@ -445,3 +445,30 @@ def post_bootstrap(
         f"{req.name}: running post bootstrap hook for {sdist_filename} and {wheel_filename}"
     )
 ```
+
+## Custom CLI (command line interface) commands
+
+Fromager's CLI can be extended with additional commands with entry point
+group `fromager.cli`. The entry point value must return a valid `click`
+command or command group. The name must match the command name.
+
+```yaml
+# pyproject.toml
+[project.entry-points."fromager.cli"]
+mycommand = "mypackage.module:mycommand"
+```
+
+```python
+# mypackage/module.py
+import click
+from fromager import context
+
+@click.command()
+@click.argument("example")
+@click.pass_obj
+def mycommand(
+    wkctx: context.WorkContext,
+    example: str,
+) -> None:
+    ...
+```

pyproject.toml

@@ -101,6 +101,27 @@ resolve_source = "fromager.sources:default_resolve_source"
 build_sdist = "fromager.sources:default_build_sdist"
 build_wheel = "fromager.wheels:default_build_wheel"
 
+[project.entry-points."fromager.cli"]
+bootstrap = "fromager.commands.bootstrap:bootstrap"
+bootstrap-parallel = "fromager.commands.bootstrap:bootstrap_parallel"
+build = "fromager.commands.build:build"
+build-sequence = "fromager.commands.build:build_sequence"
+build-parallel = "fromager.commands.build:build_parallel"
+build-order = "fromager.commands.build_order:build_order"
+find-updates = "fromager.commands.find_updates:find_updates"
+graph = "fromager.commands.graph:graph"
+lint = "fromager.commands.lint:lint"
+list-overrides = "fromager.commands.list_overrides:list_overrides"
+list-versions = "fromager.commands.list_versions:list_versions"
+migrate-config = "fromager.commands.migrate_config:migrate_config"
+minimize = "fromager.commands.minimize:minimize"
+stats = "fromager.commands.stats:stats"
+step = "fromager.commands.step:step"
+canonicalize = "fromager.commands.canonicalize:canonicalize"
+download-sequence = "fromager.commands.download_sequence:download_sequence"
+wheel-server = "fromager.commands.server:wheel_server"
+lint-requirements = "fromager.commands.lint_requirements:lint_requirements"
+
 [tool.coverage.run]
 branch = true
 parallel = true

src/fromager/commands/__init__.py

@@ -1,41 +1,41 @@
-from . import (
-    bootstrap,
-    build,
-    build_order,
-    canonicalize,
-    download_sequence,
-    find_updates,
-    graph,
-    lint,
-    lint_requirements,
-    list_overrides,
-    list_versions,
-    migrate_config,
-    minimize,
-    server,
-    stats,
-    step,
-)
-
-commands = [
-    bootstrap.bootstrap,
-    bootstrap.bootstrap_parallel,
-    build.build,
-    build.build_sequence,
-    build.build_parallel,
-    build_order.build_order,
-    find_updates.find_updates,
-    graph.graph,
-    lint.lint,
-    list_overrides.list_overrides,
-    list_versions.list_versions,
-    migrate_config.migrate_config,
-    minimize.minimize,
-    stats.stats,
-    step.step,
-    canonicalize.canonicalize,
-    download_sequence.download_sequence,
-    server.wheel_server,
-    migrate_config.migrate_config,
-    lint_requirements.lint_requirements,
-]
+import importlib.metadata
+
+import click
+
+
+def _load_commands() -> list[click.Command]:
+    """Load commands from fromager.cli entry points"""
+    commands: list[click.Command] = []
+    seen: dict[str, str] = {}
+
+    for ep in importlib.metadata.entry_points(group="fromager.cli"):
+        try:
+            command: click.Command | object = ep.load()
+        except Exception as e:
+            raise RuntimeError(
+                f"Unable to load 'fromager.cli' entry point {ep.value!r}"
+            ) from e
+
+        # target must be a click command
+        if not isinstance(command, click.Command):
+            raise RuntimeError(f"{ep.value!r} is not a click.Command: {command}")
+
+        # command name and entry point name have to match
+        if command.name != ep.name:
+            raise ValueError(
+                f"Command name {command.name!r} does not match entry "
+                f"point name {ep.name!r} for {ep.value!r}"
+            )
+
+        # third party commands can conflict
+        if command.name in seen:
+            raise ValueError(
+                f"Conflict: {ep.value!r} and {seen[ep.name]!r} define {ep.name!r}"
+            )
+        commands.append(command)
+        seen[ep.name] = ep.value
+
+    return commands
+
+
+commands = _load_commands()

tests/test_cli.py

@@ -3,6 +3,7 @@
 from click.testing import CliRunner
 
 from fromager.__main__ import main as fromager
+from fromager.commands import commands
 
 
 def test_migrate_config(
@@ -39,3 +40,31 @@ def test_fromager_version(cli_runner: CliRunner) -> None:
     result = cli_runner.invoke(fromager, ["--version"])
     assert result.exit_code == 0
     assert result.stdout.startswith("fromager, version")
+
+
+KNOWN_COMMANDS: set[str] = {
+    "bootstrap",
+    "bootstrap-parallel",
+    "build",
+    "build-order",
+    "build-parallel",
+    "build-sequence",
+    "canonicalize",
+    "download-sequence",
+    "find-updates",
+    "graph",
+    "lint",
+    "lint-requirements",
+    "list-overrides",
+    "list-versions",
+    "migrate-config",
+    "minimize",
+    "stats",
+    "step",
+    "wheel-server",
+}
+
+
+def test_registered_eps() -> None:
+    registered = {c.name for c in commands}
+    assert registered == KNOWN_COMMANDS