python-base-command 0.1.3__tar.gz → 0.1.5__tar.gz

{python_base_command-0.1.3 → python_base_command-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-base-command
-Version: 0.1.3
+Version: 0.1.5
 Summary: Django-style BaseCommand framework for standalone Python CLI tools
 Project-URL: Homepage, https://github.com/aviz92/python-base-command
 Project-URL: Repository, https://github.com/aviz92/python-base-command
@@ -18,6 +18,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Utilities
 Requires-Python: >=3.12
 Requires-Dist: custom-python-logger>=2.0.13
+Requires-Dist: python-base-toolkit>=1.0.2
 Description-Content-Type: text/markdown
 
 ![PyPI version](https://img.shields.io/pypi/v/python-base-command)
@@ -66,7 +67,7 @@ Start by creating `cli.py` — your entry point, the equivalent of Django's `man
 
 ```python
 # cli.py
-from base_command import Runner
+from python_base_command import Runner
 
 Runner(commands_dir="commands").run()
 ```
@@ -83,11 +84,12 @@ myapp/
 
 ```python
 # commands/greet.py
-from base_command import BaseCommand, CommandError
+from python_base_command import BaseCommand, CommandError
 
 
 class Command(BaseCommand):
     help = "Greet a user by name"
+    version = "1.0.0"
 
     def add_arguments(self, parser):
         parser.add_argument("name", type=str, help="Name to greet")
@@ -105,24 +107,48 @@ class Command(BaseCommand):
         self.logger.info(msg)
 ```
 
+```python
+# commands/greet.py
+from python_base_command import BaseCommand, CommandError
+
+
+class Command(BaseCommand):
+    help = "Greet a user by name"
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.set_project_version("python-base-command")
+
+    def add_arguments(self, parser):
+        pass
+
+    def handle(self, **kwargs):
+        pass
+```
+
 Run from anywhere inside the project:
 
 ```bash
-python cli.py --help                  # lists all available commands
-python cli.py greet Alice
-python cli.py greet Alice --shout
-python cli.py greet --version
-python cli.py greet --verbosity 2
+python3 cli.py --help                  # lists all available commands
+python3 cli.py greet Alice
+python3 cli.py greet Alice --shout
+python3 cli.py greet --version
+python3 cli.py greet --verbosity 2
 ```
 
 ---
 
 ## 📋 Manual Registry
 
-Register commands explicitly using the `@registry.register()` decorator — useful when commands live across different modules.
+Register commands explicitly using the `@registry.register()` decorator — useful when you want multiple commands in a single file.
+
+The registry style works in two ways:
+
+**Standalone** — run the registry directly as a script:
 
 ```python
-from base_command import BaseCommand, CommandError, CommandRegistry
+# my_commands.py
+from python_base_command import BaseCommand, CommandError, CommandRegistry
 
 registry = CommandRegistry()
 
@@ -130,6 +156,7 @@ registry = CommandRegistry()
 @registry.register("greet")
 class GreetCommand(BaseCommand):
     help = "Greet a user"
+    version = "2.0.0"
 
     def add_arguments(self, parser):
         parser.add_argument("name", type=str)
@@ -141,6 +168,7 @@ class GreetCommand(BaseCommand):
 @registry.register("export")
 class ExportCommand(BaseCommand):
     help = "Export data"
+    version = "3.0.0"
 
     def add_arguments(self, parser):
         parser.add_argument("--format", choices=["csv", "json"], default="csv")
@@ -158,10 +186,26 @@ if __name__ == "__main__":
 ```
 
 ```bash
-python cli.py --help
-python cli.py greet Alice
-python cli.py export --format json
-python cli.py export --dry-run
+python3 my_commands.py greet Alice
+python3 my_commands.py export --format json
+python3 my_commands.py export --dry-run
+```
+
+**Auto-discovered** — drop the registry file into your `commands/` folder and `Runner` will discover it automatically alongside any classic `Command` files:
+
+```
+myapp/
+├── cli.py
+└── commands/
+    ├── __init__.py
+    ├── greet.py       ← classic Command class
+    └── reg_cmd.py     ← CommandRegistry with multiple commands
+```
+
+```bash
+python3 cli.py --help          # shows commands from both files
+python3 cli.py greet Alice
+python3 cli.py export --format json
 ```
 
 ---
@@ -171,7 +215,7 @@ python cli.py export --dry-run
 Invoke commands programmatically — ideal for unit tests.
 
 ```python
-from base_command import call_command, CommandError
+from python_base_command import call_command, CommandError
 import pytest
 
 from commands.greet import Command as GreetCommand
@@ -202,6 +246,7 @@ Base class for all commands. Inherit from it and implement `handle()`.
 | Attribute | Type | Default | Description |
 |---|---|---|---|
 | `help` | `str` | `""` | Description shown in `--help` |
+| `version` | `str` | `"unknown"` | Version string exposed via `--version`. Set this per command. |
 | `output_transaction` | `bool` | `False` | Wrap `handle()` return value in `BEGIN;` / `COMMIT;` |
 | `suppressed_base_arguments` | `set[str]` | `set()` | Base flags to hide from `--help` |
 | `stealth_options` | `tuple[str]` | `()` | Options used but not declared via `add_arguments()` |
@@ -213,7 +258,6 @@ Base class for all commands. Inherit from it and implement `handle()`.
 |---|---|---|
 | `handle(**kwargs)` | ✅ | Command logic. May return a string. |
 | `add_arguments(parser)` | ❌ | Add command-specific arguments to the parser. |
-| `get_version()` | ❌ | Override to expose your package version via `--version`. |
 
 **`self.logger`**
 
@@ -255,7 +299,7 @@ raise CommandError("Fatal error.", returncode=2)
 For commands that accept one or more arbitrary string labels. Override `handle_label()` instead of `handle()`.
 
 ```python
-from base_command import LabelCommand, CommandError
+from python_base_command import LabelCommand, CommandError
 
 
 class Command(LabelCommand):
@@ -278,24 +322,27 @@ class Command(LabelCommand):
 ```
 
 ```bash
-python cli.py process report.csv notes.txt image.png
-python cli.py process report.csv notes.txt image.png --strict
+python3 cli.py process report.csv notes.txt image.png
+python3 cli.py process report.csv notes.txt image.png --strict
 ```
 
 ---
 
 ### `Runner`
 
-Auto-discovers commands from a directory. Every `.py` file in the folder that defines a `Command` class subclassing `BaseCommand` is automatically registered.
+Auto-discovers commands from a directory. Two conventions are supported:
+
+1. **Classic** — a `.py` file that defines a class named `Command` subclassing `BaseCommand`. The command name is the file stem.
+2. **Registry** — a `.py` file that defines one or more `CommandRegistry` instances. Every command registered on those instances is merged in automatically; command names come from the registry, not the file name.
+
+Files whose names start with `_` are ignored.
 
 ```python
-from base_command import Runner
+from python_base_command import Runner
 
 Runner(commands_dir="commands").run()
 ```
 
-Files whose names start with `_` are ignored.
-
 ---
 
 ### `CommandRegistry`
@@ -303,17 +350,19 @@ Files whose names start with `_` are ignored.
 Manually register commands using a decorator or programmatically.
 
 ```python
-from base_command import CommandRegistry
+from python_base_command import BaseCommand, CommandRegistry
 
 registry = CommandRegistry()
 
+
 @registry.register("greet")
 class GreetCommand(BaseCommand): ...
 
+
 registry.add("export", ExportCommand)  # programmatic alternative
 
-registry.run()                                    # uses sys.argv
-registry.run(["myapp", "greet", "Alice"])         # explicit argv
+registry.run()                                      # uses sys.argv
+registry.run(["myapp", "greet", "Alice"])           # explicit argv
 ```
 
 ---
@@ -323,7 +372,7 @@ registry.run(["myapp", "greet", "Alice"])         # explicit argv
 Invoke a command from Python code. Accepts either a class or an instance.
 
 ```python
-from base_command import call_command
+from python_base_command import call_command
 
 call_command(GreetCommand, name="Alice")
 call_command(GreetCommand, name="Alice", verbosity=0)

{python_base_command-0.1.3 → python_base_command-0.1.5}/README.md

@@ -44,7 +44,7 @@ Start by creating `cli.py` — your entry point, the equivalent of Django's `man
 
 ```python
 # cli.py
-from base_command import Runner
+from python_base_command import Runner
 
 Runner(commands_dir="commands").run()
 ```
@@ -61,11 +61,12 @@ myapp/
 
 ```python
 # commands/greet.py
-from base_command import BaseCommand, CommandError
+from python_base_command import BaseCommand, CommandError
 
 
 class Command(BaseCommand):
     help = "Greet a user by name"
+    version = "1.0.0"
 
     def add_arguments(self, parser):
         parser.add_argument("name", type=str, help="Name to greet")
@@ -83,24 +84,48 @@ class Command(BaseCommand):
         self.logger.info(msg)
 ```
 
+```python
+# commands/greet.py
+from python_base_command import BaseCommand, CommandError
+
+
+class Command(BaseCommand):
+    help = "Greet a user by name"
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.set_project_version("python-base-command")
+
+    def add_arguments(self, parser):
+        pass
+
+    def handle(self, **kwargs):
+        pass
+```
+
 Run from anywhere inside the project:
 
 ```bash
-python cli.py --help                  # lists all available commands
-python cli.py greet Alice
-python cli.py greet Alice --shout
-python cli.py greet --version
-python cli.py greet --verbosity 2
+python3 cli.py --help                  # lists all available commands
+python3 cli.py greet Alice
+python3 cli.py greet Alice --shout
+python3 cli.py greet --version
+python3 cli.py greet --verbosity 2
 ```
 
 ---
 
 ## 📋 Manual Registry
 
-Register commands explicitly using the `@registry.register()` decorator — useful when commands live across different modules.
+Register commands explicitly using the `@registry.register()` decorator — useful when you want multiple commands in a single file.
+
+The registry style works in two ways:
+
+**Standalone** — run the registry directly as a script:
 
 ```python
-from base_command import BaseCommand, CommandError, CommandRegistry
+# my_commands.py
+from python_base_command import BaseCommand, CommandError, CommandRegistry
 
 registry = CommandRegistry()
 
@@ -108,6 +133,7 @@ registry = CommandRegistry()
 @registry.register("greet")
 class GreetCommand(BaseCommand):
     help = "Greet a user"
+    version = "2.0.0"
 
     def add_arguments(self, parser):
         parser.add_argument("name", type=str)
@@ -119,6 +145,7 @@ class GreetCommand(BaseCommand):
 @registry.register("export")
 class ExportCommand(BaseCommand):
     help = "Export data"
+    version = "3.0.0"
 
     def add_arguments(self, parser):
         parser.add_argument("--format", choices=["csv", "json"], default="csv")
@@ -136,10 +163,26 @@ if __name__ == "__main__":
 ```
 
 ```bash
-python cli.py --help
-python cli.py greet Alice
-python cli.py export --format json
-python cli.py export --dry-run
+python3 my_commands.py greet Alice
+python3 my_commands.py export --format json
+python3 my_commands.py export --dry-run
+```
+
+**Auto-discovered** — drop the registry file into your `commands/` folder and `Runner` will discover it automatically alongside any classic `Command` files:
+
+```
+myapp/
+├── cli.py
+└── commands/
+    ├── __init__.py
+    ├── greet.py       ← classic Command class
+    └── reg_cmd.py     ← CommandRegistry with multiple commands
+```
+
+```bash
+python3 cli.py --help          # shows commands from both files
+python3 cli.py greet Alice
+python3 cli.py export --format json
 ```
 
 ---
@@ -149,7 +192,7 @@ python cli.py export --dry-run
 Invoke commands programmatically — ideal for unit tests.
 
 ```python
-from base_command import call_command, CommandError
+from python_base_command import call_command, CommandError
 import pytest
 
 from commands.greet import Command as GreetCommand
@@ -180,6 +223,7 @@ Base class for all commands. Inherit from it and implement `handle()`.
 | Attribute | Type | Default | Description |
 |---|---|---|---|
 | `help` | `str` | `""` | Description shown in `--help` |
+| `version` | `str` | `"unknown"` | Version string exposed via `--version`. Set this per command. |
 | `output_transaction` | `bool` | `False` | Wrap `handle()` return value in `BEGIN;` / `COMMIT;` |
 | `suppressed_base_arguments` | `set[str]` | `set()` | Base flags to hide from `--help` |
 | `stealth_options` | `tuple[str]` | `()` | Options used but not declared via `add_arguments()` |
@@ -191,7 +235,6 @@ Base class for all commands. Inherit from it and implement `handle()`.
 |---|---|---|
 | `handle(**kwargs)` | ✅ | Command logic. May return a string. |
 | `add_arguments(parser)` | ❌ | Add command-specific arguments to the parser. |
-| `get_version()` | ❌ | Override to expose your package version via `--version`. |
 
 **`self.logger`**
 
@@ -233,7 +276,7 @@ raise CommandError("Fatal error.", returncode=2)
 For commands that accept one or more arbitrary string labels. Override `handle_label()` instead of `handle()`.
 
 ```python
-from base_command import LabelCommand, CommandError
+from python_base_command import LabelCommand, CommandError
 
 
 class Command(LabelCommand):
@@ -256,24 +299,27 @@ class Command(LabelCommand):
 ```
 
 ```bash
-python cli.py process report.csv notes.txt image.png
-python cli.py process report.csv notes.txt image.png --strict
+python3 cli.py process report.csv notes.txt image.png
+python3 cli.py process report.csv notes.txt image.png --strict
 ```
 
 ---
 
 ### `Runner`
 
-Auto-discovers commands from a directory. Every `.py` file in the folder that defines a `Command` class subclassing `BaseCommand` is automatically registered.
+Auto-discovers commands from a directory. Two conventions are supported:
+
+1. **Classic** — a `.py` file that defines a class named `Command` subclassing `BaseCommand`. The command name is the file stem.
+2. **Registry** — a `.py` file that defines one or more `CommandRegistry` instances. Every command registered on those instances is merged in automatically; command names come from the registry, not the file name.
+
+Files whose names start with `_` are ignored.
 
 ```python
-from base_command import Runner
+from python_base_command import Runner
 
 Runner(commands_dir="commands").run()
 ```
 
-Files whose names start with `_` are ignored.
-
 ---
 
 ### `CommandRegistry`
@@ -281,17 +327,19 @@ Files whose names start with `_` are ignored.
 Manually register commands using a decorator or programmatically.
 
 ```python
-from base_command import CommandRegistry
+from python_base_command import BaseCommand, CommandRegistry
 
 registry = CommandRegistry()
 
+
 @registry.register("greet")
 class GreetCommand(BaseCommand): ...
 
+
 registry.add("export", ExportCommand)  # programmatic alternative
 
-registry.run()                                    # uses sys.argv
-registry.run(["myapp", "greet", "Alice"])         # explicit argv
+registry.run()                                      # uses sys.argv
+registry.run(["myapp", "greet", "Alice"])           # explicit argv
 ```
 
 ---
@@ -301,7 +349,7 @@ registry.run(["myapp", "greet", "Alice"])         # explicit argv
 Invoke a command from Python code. Accepts either a class or an instance.
 
 ```python
-from base_command import call_command
+from python_base_command import call_command
 
 call_command(GreetCommand, name="Alice")
 call_command(GreetCommand, name="Alice", verbosity=0)

{python_base_command-0.1.3 → python_base_command-0.1.5}/pyproject.toml

@@ -4,13 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-base-command"
-version = "0.1.3"
+version = "0.1.5"
 description = "Django-style BaseCommand framework for standalone Python CLI tools"
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.12"
 dependencies = [
     "custom-python-logger>=2.0.13",
+    "python-base-toolkit>=1.0.2",
 ]
 keywords = ["cli", "command", "argparse", "django", "management"]
 classifiers = [

{python_base_command-0.1.3 → python_base_command-0.1.5}/python_base_command/__init__.py

@@ -15,8 +15,6 @@ Public API
 - call_command     — programmatic command invocation
 """
 
-from custom_python_logger import build_logger
-
 from .base import (
     BaseCommand,
     CommandError,
@@ -36,8 +34,3 @@ __all__ = [
     "Runner",
     "call_command",
 ]
-
-build_logger(
-    project_name="python-base-command",
-    log_format="%(asctime)s | %(levelname)s | %(message)s",
-)

{python_base_command-0.1.3 → python_base_command-0.1.5}/python_base_command/base.py

@@ -6,14 +6,14 @@ replacing self.stdout / self.style with self.logger from custom-python-logger.
 """
 
 import argparse
-import importlib.metadata
 import os
 import sys
 from argparse import Action, ArgumentParser, HelpFormatter
 from collections.abc import Sequence
+from importlib.metadata import version
 from typing import Any, TextIO
 
-from custom_python_logger import CustomLoggerAdapter, get_logger
+from custom_python_logger import CustomLoggerAdapter, build_logger, get_logger
 
 __all__ = [
     "BaseCommand",
@@ -22,6 +22,7 @@ __all__ = [
     "LabelCommand",
 ]
 
+from python_base_toolkit.utils.path_utils import get_project_path_by_file
 
 # ---------------------------------------------------------------------------
 # Exceptions
@@ -142,6 +143,8 @@ class BaseCommand:
     ----------
     help : str
         Short description printed in --help output.
+    version : str
+        Version string exposed via --version. Set this per command.
     output_transaction : bool
         If True, wrap any string returned by handle() with BEGIN; / COMMIT;.
     suppressed_base_arguments : set[str]
@@ -153,6 +156,7 @@ class BaseCommand:
     """
 
     help: str = ""
+    version: str = "unknown"
     output_transaction: bool = False
     suppressed_base_arguments: set[str] = set()
     stealth_options: tuple[str, ...] = ()
@@ -169,22 +173,23 @@ class BaseCommand:
     ) -> None:
         _ = stdout, stderr  # API compatibility with call_command(stdout=..., stderr=...)
         self.logger: CustomLoggerAdapter = get_logger(name=self.__class__.__module__.split(".", maxsplit=1)[0])
-
-    # ------------------------------------------------------------------ version
-
-    def get_version(self) -> str:
-        """
-        Return the version string for this command.
-        Override to expose your own application version via --version.
-        """
-        try:
-            pkg = self.__module__.split(".", maxsplit=1)[0]
-            return importlib.metadata.version(pkg)
-        except Exception:
-            return "unknown"
+        build_logger(
+            project_name=self.__class__.__name__,
+            log_format="%(asctime)s | %(levelname)s | %(message)s",
+            log_file=os.getenv("PYTHON_BASE_COMMAND_LOG_FILE", "true").lower() == "true",
+        )
 
     # ------------------------------------------------------------------ parser
 
+    def set_project_version(self, project_name: str | None = None) -> None:
+        if not project_name:
+            try:
+                project_path = get_project_path_by_file()
+                project_name = project_path.name
+            except Exception:
+                self.logger.warning("Project name not provided and could not be inferred from file markers.")
+        self.version = version(project_name) if project_name else self.version
+
     def create_parser(self, prog_name: str, subcommand: str, **kwargs: Any) -> CommandParser:
         """Create and return the CommandParser used to parse arguments."""
         kwargs.setdefault("formatter_class", CommandHelpFormatter)
@@ -200,7 +205,7 @@ class BaseCommand:
             parser,
             "--version",
             action="version",
-            version=self.get_version(),
+            version=self.version,
             help="Show program's version number and exit.",
         )
         self.add_base_argument(
@@ -273,7 +278,6 @@ class BaseCommand:
         If handle() returns a string and output_transaction is True,
         wraps it in BEGIN; / COMMIT;.
         """
-        output: str | None = None
         if output := self.handle(**kwargs):
             if self.output_transaction:
                 output = f"BEGIN;\n{output}\nCOMMIT;"

{python_base_command-0.1.3 → python_base_command-0.1.5}/python_base_command/runner.py

@@ -40,16 +40,14 @@ And run::
 """
 
 import importlib.util
-import os
 import sys
 from pathlib import Path
 from types import ModuleType
-from typing import Optional
 
 from custom_python_logger import get_logger
 
-from . import CommandRegistry
-from .base import BaseCommand, CommandError
+from python_base_command.base import BaseCommand
+from python_base_command.registry import CommandRegistry
 
 logger = get_logger("python-base-command")
 
@@ -70,7 +68,7 @@ class Runner:
     def __init__(
         self,
         commands_dir: str | Path = "commands",
-    ):
+    ) -> None:
         # Resolve relative to cwd — the directory the user runs the script from,
         # just like Django resolves manage.py commands from the project root.
         self._commands_dir = (Path.cwd() / commands_dir).resolve()
@@ -98,8 +96,7 @@ class Runner:
             if path.stem.startswith("_"):
                 continue
 
-            module = self._load_module(path)
-            if module is None:
+            if (module := self._load_module(path)) is None:
                 continue
 
             # --- 1. Classic: a top-level class named "Command" ---
@@ -112,14 +109,13 @@ class Runner:
                 obj = getattr(module, attr_name)
                 if isinstance(obj, CommandRegistry):
                     for name in obj.list_commands():
-                        cls = obj.get(name)
-                        if cls is not None:
+                        if (cls := obj.get(name)) is not None:
                             commands[name] = cls
 
         return commands
 
     @staticmethod
-    def _load_module(path: Path) -> Optional[ModuleType]:
+    def _load_module(path: Path) -> ModuleType | None:
         """Dynamically load a Python file as a module."""
         module_name = f"_base_command_discovered_.{path.stem}"
         spec = importlib.util.spec_from_file_location(module_name, path)
@@ -135,7 +131,7 @@ class Runner:
 
     # ------------------------------------------------------------------ running
 
-    def run(self, argv: list[str] | None = None):
+    def run(self, argv: list[str] | None = None) -> None:
         """
         Parse *argv* (defaults to ``sys.argv``), discover commands, find the
         requested one, and run it.
@@ -144,14 +140,12 @@ class Runner:
         commands = self._discover()
 
         # Show top-level help if no subcommand is given.
-        if len(argv) < 2 or argv[1] in ("-h", "--help"):
+        if len(argv) < 2 or argv[1] in {"-h", "--help"}:
             self._print_help(argv[0] if argv else "unknown", commands)
             sys.exit(0)
 
         subcommand = argv[1]
-        command_class = commands.get(subcommand)
-
-        if command_class is None:
+        if (command_class := commands.get(subcommand)) is None:
             prog = argv[0] if argv else "unknown"
             available = ", ".join(sorted(commands)) or "(none found)"
             logger.error(
@@ -165,7 +159,7 @@ class Runner:
         command_class().run_from_argv([argv[0]] + argv[2:])
 
     @staticmethod
-    def _print_help(prog: str, commands: dict[str, type[BaseCommand]]):
+    def _print_help(prog: str, commands: dict[str, type[BaseCommand]]) -> None:
         print(f"Usage: {prog} <command> [options]\n")
         print("Available commands:")
         for name, cls in sorted(commands.items()):

{python_base_command-0.1.3 → python_base_command-0.1.5}/usage_example/commands/greet.py

@@ -7,6 +7,7 @@ from python_base_command.base import CommandParser
 
 class Command(BaseCommand):
     help = "Greet a user by name"
+    version = "1.0.0"
 
     def add_arguments(self, parser: CommandParser) -> None:
         parser.add_argument("name", type=str, help="Name to greet")

{python_base_command-0.1.3 → python_base_command-0.1.5}/usage_example/commands/registry_cmd.py

@@ -1,4 +1,6 @@
-from python_base_command import BaseCommand, CommandError, CommandRegistry
+from typing import Any
+
+from python_base_command import BaseCommand, CommandParser, CommandRegistry
 
 registry = CommandRegistry()
 
@@ -7,22 +9,28 @@ registry = CommandRegistry()
 class Greet2Command(BaseCommand):
     help = "Greet a user"
 
-    def add_arguments(self, parser):
+    def __init__(self) -> None:
+        super().__init__()
+        # self.set_project_version("python-base-command")
+        self.set_project_version()
+
+    def add_arguments(self, parser: CommandParser) -> None:
         parser.add_argument("name", type=str)
 
-    def handle(self, **kwargs):
+    def handle(self, **kwargs: Any) -> None:
         self.logger.info(f"Hello, {kwargs['name']}!")
 
 
 @registry.register("export")
 class ExportCommand(BaseCommand):
     help = "Export data"
+    version = "1.0.0"
 
-    def add_arguments(self, parser):
+    def add_arguments(self, parser: CommandParser) -> None:
         parser.add_argument("--format", choices=["csv", "json"], default="csv")
         parser.add_argument("--dry-run", action="store_true")
 
-    def handle(self, **kwargs):
+    def handle(self, **kwargs: Any) -> None:
         if kwargs["dry_run"]:
             self.logger.warning("Dry run — no files written.")
             return