migrate sphinxcontrib.h5p.utils

src/byteb4rb1e/utils/argparse/command.py

@@ -0,0 +1,54 @@
+"""Base command dataclass for composable CLI trees."""
+
+from __future__ import annotations
+
+from argparse import ArgumentParser
+from dataclasses import dataclass, fields
+from typing import Any, ClassVar, Dict, List, Optional, Type
+
+
+@dataclass
+class CLICommand:
+    """Base class for CLI commands.
+
+    Subclasses define their identity (name, help, description) as
+    dataclass fields.  These are passed as kwargs to
+    ``subparsers.add_parser()``.
+
+    Override ``add_arguments`` to register flags and positionals.
+    Override ``execute`` to implement the command's logic.
+
+    Nest subcommands by setting ``_subcommands`` as a class variable.
+    """
+
+    name: str = ""
+    help: str = ""
+    description: str = ""
+
+    _subcommands: ClassVar[List[Type[Command]]] = []
+
+    def add_arguments(self, parser: ArgumentParser) -> None:
+        """Add arguments to the parser.  Override in subclasses."""
+
+    def execute(self, args: Any) -> int:
+        """Run the command.  Override in subclasses.
+
+        Returns an exit code (0 = success).
+        """
+        return 0
+
+    def parser_kwargs(self) -> Dict[str, Any]:
+        """Return the dataclass fields as kwargs for add_parser.
+
+        Excludes ``name`` (used as the positional parser name) and
+        any empty-string fields so argparse defaults apply.
+        """
+        skip = {"name"}
+        kwargs = {}
+        for f in fields(self):
+            if f.name in skip or f.name.startswith("_"):
+                continue
+            val = getattr(self, f.name)
+            if val != "":
+                kwargs[f.name] = val
+        return kwargs