python-base-command 0.1.2__tar.gz → 0.1.4__tar.gz

{python_base_command-0.1.2 → python_base_command-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-base-command
-Version: 0.1.2
+Version: 0.1.4
 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")
@@ -108,21 +110,26 @@ class Command(BaseCommand):
 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 +137,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 +149,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 +167,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 +196,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 +227,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 +239,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 +280,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 +303,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 +331,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 +353,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.2 → python_base_command-0.1.4}/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")
@@ -86,21 +87,26 @@ class Command(BaseCommand):
 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 +114,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 +126,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 +144,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 +173,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 +204,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 +216,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 +257,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 +280,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 +308,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 +330,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.2 → python_base_command-0.1.4}/pyproject.toml

@@ -4,13 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-base-command"
-version = "0.1.2"
+version = "0.1.4"
 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.2 → python_base_command-0.1.4}/python_base_command/base.py

@@ -6,7 +6,6 @@ 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
@@ -142,6 +141,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 +154,7 @@ class BaseCommand:
     """
 
     help: str = ""
+    version: str = "unknown"
     output_transaction: bool = False
     suppressed_base_arguments: set[str] = set()
     stealth_options: tuple[str, ...] = ()
@@ -170,19 +172,6 @@ class BaseCommand:
         _ = 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"
-
     # ------------------------------------------------------------------ parser
 
     def create_parser(self, prog_name: str, subcommand: str, **kwargs: Any) -> CommandParser:
@@ -200,7 +189,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(

{python_base_command-0.1.2 → python_base_command-0.1.4}/python_base_command/runner.py

@@ -40,15 +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 .base import BaseCommand, CommandError
+from python_base_command.base import BaseCommand
+from python_base_command.registry import CommandRegistry
 
 logger = get_logger("python-base-command")
 
@@ -69,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()
@@ -78,8 +77,15 @@ class Runner:
 
     def _discover(self) -> dict[str, type[BaseCommand]]:
         """
-        Walk ``self._commands_dir`` and import every non-private module that
-        exposes a ``Command`` class inheriting from ``BaseCommand``.
+        Walk ``self._commands_dir`` and import every non-private module.
+
+        Two conventions are supported per module:
+
+        1. **Classic** — a class literally named ``Command`` that subclasses
+           ``BaseCommand``.  The command name is the module's file stem.
+        2. **Registry** — one or more ``CommandRegistry`` instances defined at
+           module level.  Every command registered on those instances is merged
+           in; the names come from the registry (not the file stem).
         """
         commands: dict[str, type[BaseCommand]] = {}
 
@@ -90,24 +96,26 @@ 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" ---
             command_class = getattr(module, "Command", None)
-            if command_class is None:
-                continue
-            if not (
-                isinstance(command_class, type) and issubclass(command_class, BaseCommand)
-            ):
-                continue
+            if command_class is not None and isinstance(command_class, type) and issubclass(command_class, BaseCommand):
+                commands[path.stem] = command_class
 
-            commands[path.stem] = command_class
+            # --- 2. Registry: any CommandRegistry instances in the module ---
+            for attr_name in dir(module):
+                obj = getattr(module, attr_name)
+                if isinstance(obj, CommandRegistry):
+                    for name in obj.list_commands():
+                        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)
@@ -123,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.
@@ -132,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(
@@ -153,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.2 → python_base_command-0.1.4}/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.4/usage_example/commands/registry_cmd.py

@@ -0,0 +1,35 @@
+from typing import Any
+
+from python_base_command import BaseCommand, CommandParser, CommandRegistry
+
+registry = CommandRegistry()
+
+
+@registry.register("greet2")
+class Greet2Command(BaseCommand):
+    help = "Greet a user"
+
+    def add_arguments(self, parser: CommandParser) -> None:
+        parser.add_argument("name", type=str)
+
+    def handle(self, **kwargs: Any) -> None:
+        self.logger.info(f"Hello, {kwargs['name']}!")
+
+
+@registry.register("export")
+class ExportCommand(BaseCommand):
+    help = "Export data"
+
+    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: Any) -> None:
+        if kwargs["dry_run"]:
+            self.logger.warning("Dry run — no files written.")
+            return
+        self.logger.info(f"Exported as {kwargs['format']}.")
+
+
+if __name__ == "__main__":
+    registry.run()