python-base-command 0.1.0__py3-none-any.whl

python_base_command/__init__.py

@@ -0,0 +1,40 @@
+"""
+python-base-command
+===================
+
+A Django-style BaseCommand framework for standalone Python CLI tools.
+
+Public API
+----------
+- BaseCommand      — base class for all commands (use self.logger for output)
+- LabelCommand     — base class for commands that accept one or more labels
+- CommandError     — exception to signal a clean error exit
+- CommandParser    — customized ArgumentParser used internally
+- CommandRegistry  — manual command registry (decorator-based)
+- Runner           — auto-discovery runner (folder-based, like manage.py)
+- call_command     — programmatic command invocation
+"""
+
+from custom_python_logger import build_logger
+
+from .base import (
+    BaseCommand,
+    CommandError,
+    CommandParser,
+    LabelCommand,
+)
+from .registry import CommandRegistry
+from .runner import Runner
+from .utils import call_command
+
+__all__ = [
+    "BaseCommand",
+    "CommandError",
+    "CommandParser",
+    "CommandRegistry",
+    "LabelCommand",
+    "Runner",
+    "call_command",
+]
+
+build_logger(project_name="python-base-command")

python_base_command/base.py

@@ -0,0 +1,325 @@
+"""
+Base classes for writing CLI commands outside of Django.
+
+Mirrors Django's django.core.management.base as closely as possible,
+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 typing import Any, TextIO
+
+from custom_python_logger import CustomLoggerAdapter, get_logger
+
+__all__ = [
+    "BaseCommand",
+    "CommandError",
+    "CommandParser",
+    "LabelCommand",
+]
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+
+class CommandError(Exception):
+    """
+    Exception class indicating a problem while executing a command.
+
+    If raised during command execution it will be caught and logged as an error;
+    the process exits with ``returncode`` (default 1).
+
+    When invoked via ``call_command()``, it propagates normally.
+    """
+
+    def __init__(self, *args: Any, returncode: int = 1, **kwargs: Any) -> None:
+        self.returncode = returncode
+        super().__init__(*args, **kwargs)
+
+
+# ---------------------------------------------------------------------------
+# Argument parser
+# ---------------------------------------------------------------------------
+
+
+class CommandParser(ArgumentParser):
+    """
+    Customized ArgumentParser that raises CommandError instead of calling
+    sys.exit() when the command is invoked programmatically.
+    """
+
+    def __init__(
+        self,
+        *,
+        missing_args_message: str | None = None,
+        called_from_command_line: bool | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self.missing_args_message = missing_args_message
+        self.called_from_command_line = called_from_command_line
+        super().__init__(**kwargs)
+
+    def parse_args(
+        self,
+        args: Sequence[str] | None = None,
+        namespace: argparse.Namespace | None = None,
+    ) -> argparse.Namespace:
+        if self.missing_args_message and not (args or any(not arg.startswith("-") for arg in (args or []))):
+            self.error(self.missing_args_message)
+        return super().parse_args(args, namespace)
+
+    def error(self, message: str) -> None:
+        if self.called_from_command_line:
+            super().error(message)
+        else:
+            raise CommandError(f"Error: {message}")
+
+
+# ---------------------------------------------------------------------------
+# Help formatter
+# ---------------------------------------------------------------------------
+
+
+class CommandHelpFormatter(HelpFormatter):
+    """
+    Pushes common base arguments to the bottom of --help output so that
+    command-specific arguments appear first.
+    """
+
+    show_last: set[str] = {
+        "--version",
+        "--verbosity",
+        "--traceback",
+        "--no-color",
+        "--force-color",
+    }
+
+    def _reordered_actions(self, actions: list[Action]) -> list[Action]:
+        return sorted(
+            actions,
+            key=lambda a: bool(set(a.option_strings) & self.show_last),
+        )
+
+    def add_usage(
+        self,
+        usage: str | None,
+        actions: list[Action],
+        *args: Any,
+        **kwargs: Any,
+    ) -> None:
+        super().add_usage(usage, self._reordered_actions(actions), *args, **kwargs)
+
+    def add_arguments(self, actions: list[Action]) -> None:
+        super().add_arguments(self._reordered_actions(actions))
+
+
+# ---------------------------------------------------------------------------
+# BaseCommand
+# ---------------------------------------------------------------------------
+
+
+class BaseCommand:
+    """
+    The base class from which all commands derive.
+
+    Instead of Django's self.stdout / self.style, this class exposes
+    self.logger — a CustomLoggerAdapter from custom-python-logger.
+
+    Execution flow
+    --------------
+    1. run_from_argv() parses sys.argv and calls execute().
+    2. execute() calls handle() with the parsed options.
+    3. Any CommandError raised in handle() is caught, logged, and the
+       process exits with the error's returncode.
+
+    Attributes
+    ----------
+    help : str
+        Short description printed in --help output.
+    output_transaction : bool
+        If True, wrap any string returned by handle() with BEGIN; / COMMIT;.
+    suppressed_base_arguments : set[str]
+        Option strings whose help text should be suppressed.
+    stealth_options : tuple[str, ...]
+        Options used by the command but not declared via add_arguments().
+    missing_args_message : str | None
+        Custom error message when required positional arguments are missing.
+    """
+
+    help: str = ""
+    output_transaction: bool = False
+    suppressed_base_arguments: set[str] = set()
+    stealth_options: tuple[str, ...] = ()
+    missing_args_message: str | None = None
+
+    _called_from_command_line: bool = False
+
+    # ------------------------------------------------------------------ init
+
+    def __init__(
+        self,
+        stdout: TextIO | None = None,
+        stderr: TextIO | None = None,
+    ) -> 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"
+
+    # ------------------------------------------------------------------ parser
+
+    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)
+        parser = CommandParser(
+            prog=f"{os.path.basename(prog_name)} {subcommand}",
+            description=self.help or None,
+            missing_args_message=self.missing_args_message,
+            called_from_command_line=self._called_from_command_line,
+            **kwargs,
+        )
+
+        self.add_base_argument(
+            parser,
+            "--version",
+            action="version",
+            version=self.get_version(),
+            help="Show program's version number and exit.",
+        )
+        self.add_base_argument(
+            parser,
+            "-v",
+            "--verbosity",
+            default=1,
+            type=int,
+            choices=[0, 1, 2, 3],
+            help="Verbosity level; 0=minimal, 1=normal, 2=verbose, 3=very verbose.",
+        )
+        self.add_base_argument(
+            parser,
+            "--traceback",
+            action="store_true",
+            help="Raise on CommandError instead of logging cleanly.",
+        )
+
+        self.add_arguments(parser)
+        return parser
+
+    def add_base_argument(self, parser: CommandParser, *args: Any, **kwargs: Any) -> None:
+        """Add a base argument, suppressing help if in suppressed_base_arguments."""
+        for arg in args:
+            if arg in self.suppressed_base_arguments:
+                kwargs["help"] = argparse.SUPPRESS
+                break
+        parser.add_argument(*args, **kwargs)
+
+    def add_arguments(self, parser: CommandParser) -> None:
+        """Override to add command-specific arguments."""
+
+    def print_help(self, prog_name: str, subcommand: str) -> None:
+        """Print the help message for this command."""
+        parser = self.create_parser(prog_name, subcommand)
+        parser.print_help()
+
+    # ------------------------------------------------------------------ execution
+
+    def run_from_argv(self, argv: list[str]) -> None:
+        """
+        Primary entry point when the command is invoked from the CLI.
+
+        argv[0] = prog name, argv[1:] = arguments (no subcommand slot).
+        """
+        self._called_from_command_line = True
+
+        prog = argv[0]
+        remaining = argv[1:]
+
+        parser = self.create_parser(prog, "")
+        options = parser.parse_args(remaining)
+        cmd_options = vars(options)
+        cmd_options.pop("args", ())
+
+        try:
+            self.execute(**cmd_options)
+        except CommandError as e:
+            if options.traceback:
+                raise
+            self.logger.error(f"{e.__class__.__name__}: {e}")
+            sys.exit(e.returncode)
+        except KeyboardInterrupt:
+            self.logger.warning("Aborted.")
+            sys.exit(1)
+
+    def execute(self, **kwargs: Any) -> str | None:
+        """
+        Try to execute the command, then delegate to handle().
+        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;"
+            self.logger.info(output)
+
+        return output
+
+    def handle(self, **kwargs: Any) -> str | None:
+        """
+        The actual logic of the command. Subclasses must implement this.
+
+        Use self.logger.info() / .warning() / .error() / .step() etc.
+        May return a string (used with output_transaction).
+        """
+        raise NotImplementedError("Subclasses of BaseCommand must implement a handle() method.")
+
+
+# ---------------------------------------------------------------------------
+# LabelCommand
+# ---------------------------------------------------------------------------
+
+
+class LabelCommand(BaseCommand):
+    """
+    A command that accepts one or more string labels and calls
+    handle_label() once per label. Override handle_label() instead of handle().
+    """
+
+    label: str = "label"
+    missing_args_message: str = "Enter at least one %s."
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        if self.missing_args_message == LabelCommand.missing_args_message:
+            self.missing_args_message = self.missing_args_message % self.label
+
+    def add_arguments(self, parser: CommandParser) -> None:
+        parser.add_argument("args", metavar=self.label, nargs="+")
+
+    def handle(self, *labels: str, **kwargs: Any) -> str | None:
+        output = []
+        for label in labels:
+            if result := self.handle_label(label, **kwargs):
+                output.append(result)
+        return "\n".join(output) if output else None
+
+    def handle_label(self, label: str, **kwargs: Any) -> str | None:
+        """Perform the command's actions for a single label. Subclasses must implement this."""
+        raise NotImplementedError("Subclasses of LabelCommand must implement handle_label().")

python_base_command/registry.py

@@ -0,0 +1,123 @@
+"""
+Manual command registry.
+
+Allows registering commands by name and running them from a single entry point,
+without relying on the auto-discovery folder convention.
+
+Usage::
+
+    from python_base_command import BaseCommand, CommandRegistry
+
+    registry = CommandRegistry()
+
+    @registry.register("greet")
+    class GreetCommand(BaseCommand):
+        help = "Greet someone"
+
+        def add_arguments(self, parser):
+            parser.add_argument("name")
+
+        def handle(self, *args, **options):
+            self.stdout.write(self.style.SUCCESS(f"Hello, {options['name']}!"))
+
+    if __name__ == "__main__":
+        registry.run()
+"""
+
+import sys
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from custom_python_logger import get_logger
+
+if TYPE_CHECKING:
+    from .base import BaseCommand as BaseCommandType
+
+logger = get_logger(name="python-base-command")
+
+
+class CommandRegistry:
+    """
+    A registry that maps command names to ``BaseCommand`` subclasses and
+    exposes a single ``run()`` entry point.
+    """
+
+    def __init__(self) -> None:
+        self._commands: dict[str, type[BaseCommandType]] = {}
+
+    # ------------------------------------------------------------------ registration
+
+    def register(self, name: str) -> Callable[[type["BaseCommandType"]], type["BaseCommandType"]]:
+        """
+        Class decorator that registers a ``BaseCommand`` subclass under *name*.
+
+        Usage::
+
+            @registry.register("greet")
+            class GreetCommand(BaseCommand):
+                ...
+        """
+
+        def decorator(cls: type["BaseCommandType"]) -> type["BaseCommandType"]:
+            self._commands[name] = cls
+            return cls
+
+        return decorator
+
+    def add(self, name: str, command_class: type["BaseCommandType"]) -> None:
+        """
+        Programmatically register *command_class* under *name*.
+        """
+        self._commands[name] = command_class
+
+    # ------------------------------------------------------------------ lookup
+
+    def get(self, name: str) -> type["BaseCommandType"] | None:
+        """Return the command class registered under *name*, or ``None``."""
+        return self._commands.get(name)
+
+    def list_commands(self) -> list[str]:
+        """Return a sorted list of registered command names."""
+        return sorted(self._commands)
+
+    # ------------------------------------------------------------------ running
+
+    def run(self, argv: list[str] | None = None) -> None:
+        """
+        Parse *argv* (defaults to ``sys.argv``), find the requested command,
+        and run it.
+
+        The expected argv format is::
+
+            [prog, subcommand, ...args...]
+
+        e.g. ``["myapp", "greet", "Alice", "--shout"]``
+        """
+
+        argv = argv or sys.argv[:]
+
+        # Show top-level help if no subcommand is given.
+        if len(argv) < 2 or argv[1] in {"-h", "--help"}:
+            self._print_help(argv[0] if argv else "unknown")
+            sys.exit(0)
+
+        subcommand = argv[1]
+        if (command_class := self._commands.get(subcommand)) is None:
+            prog = argv[0] if argv else "unknown"
+            available = ", ".join(self.list_commands()) or "(none registered)"
+            logger.error(
+                f"Unknown command: '{subcommand}'. "
+                f"Available commands: {available}. "
+                f"Type '{prog} --help' for usage."
+            )
+            sys.exit(1)
+        command_class().run_from_argv([argv[0]] + argv[2:])
+
+    def _print_help(self, prog: str) -> None:
+        print(f"Usage: {prog} <command> [options]\n")
+        print("Available commands:")
+        for name in self.list_commands():
+            cls = self._commands[name]
+            desc = cls.help or "(no description)"
+            print(f"  {name:<20} {desc}")
+        print(f"\nRun '{prog} <command> --help' for command-specific help.")

python_base_command/runner.py

@@ -0,0 +1,162 @@
+"""
+Auto-discovery runner.
+
+Discovers ``BaseCommand`` subclasses from a ``commands/`` directory
+(or any directory you point it at) and exposes a single ``run()``
+entry point — exactly like Django's ``manage.py``.
+
+Convention
+----------
+Each Python module inside the commands directory must define a class
+named ``Command`` that extends ``BaseCommand``.  Files whose names start
+with an underscore are ignored.
+
+Usage::
+
+    # myapp/cli.py
+    from base_command.runner import Runner
+
+    runner = Runner(commands_dir="commands")   # relative to cwd
+
+    if __name__ == "__main__":
+        runner.run()
+
+Then create ``commands/greet.py``::
+
+    from base_command import BaseCommand, CommandError
+
+    class Command(BaseCommand):
+        help = "Greet someone"
+
+        def add_arguments(self, parser):
+            parser.add_argument("name")
+
+        def handle(self, **kwargs):
+            self.stdout.write(self.style.SUCCESS(f"Hello, {kwargs['name']}!"))
+
+And run::
+
+    python cli.py greet Alice
+"""
+
+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
+
+logger = get_logger("python-base-command")
+
+
+class Runner:
+    """
+    Discovers and runs commands from a directory of Python modules.
+
+    Parameters
+    ----------
+    commands_dir:
+        Path to the directory containing command modules.  Can be absolute
+        or relative to the current working directory (where the user runs
+        the script from) — just like Django resolves commands from the
+        project root.
+    """
+
+    def __init__(
+        self,
+        commands_dir: str | Path = "commands",
+    ):
+        # 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()
+
+    # ------------------------------------------------------------------ discovery
+
+    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``.
+        """
+        commands: dict[str, type[BaseCommand]] = {}
+
+        if not self._commands_dir.is_dir():
+            return commands
+
+        for path in sorted(self._commands_dir.glob("*.py")):
+            if path.stem.startswith("_"):
+                continue
+
+            module = self._load_module(path)
+            if module is None:
+                continue
+
+            command_class = getattr(module, "Command", None)
+            if command_class is None:
+                continue
+            if not (
+                isinstance(command_class, type) and issubclass(command_class, BaseCommand)
+            ):
+                continue
+
+            commands[path.stem] = command_class
+
+        return commands
+
+    @staticmethod
+    def _load_module(path: Path) -> Optional[ModuleType]:
+        """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)
+        if spec is None or spec.loader is None:
+            return None
+        module = importlib.util.module_from_spec(spec)
+        try:
+            spec.loader.exec_module(module)  # type: ignore[attr-defined]
+        except Exception as exc:
+            logger.error(f"Error loading command module '{path}': {exc}")
+            return None
+        return module
+
+    # ------------------------------------------------------------------ running
+
+    def run(self, argv: list[str] | None = None):
+        """
+        Parse *argv* (defaults to ``sys.argv``), discover commands, find the
+        requested one, and run it.
+        """
+        argv = argv or sys.argv[:]
+        commands = self._discover()
+
+        # Show top-level help if no subcommand is given.
+        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:
+            prog = argv[0] if argv else "unknown"
+            available = ", ".join(sorted(commands)) or "(none found)"
+            logger.error(
+                f"Unknown command: '{subcommand}'. "
+                f"Available commands: {available}. "
+                f"Type '{prog} --help' for usage."
+            )
+            sys.exit(1)
+
+        # Strip the subcommand so run_from_argv receives [prog, ...args]
+        command_class().run_from_argv([argv[0]] + argv[2:])
+
+    @staticmethod
+    def _print_help(prog: str, commands: dict[str, type[BaseCommand]]):
+        print(f"Usage: {prog} <command> [options]\n")
+        print("Available commands:")
+        for name, cls in sorted(commands.items()):
+            desc = cls.help or "(no description)"
+            print(f"  {name:<20} {desc}")
+        print(f"\nRun '{prog} <command> --help' for command-specific help.")

python_base_command/utils.py

@@ -0,0 +1,54 @@
+"""
+call_command — invoke a command programmatically.
+
+Mirrors Django's django.core.management.call_command.
+
+Usage::
+
+    from python_base_command import call_command, CommandError
+
+    call_command(GreetCommand, name="Alice")
+"""
+
+from typing import Any
+
+from .base import BaseCommand
+
+
+def call_command(
+    command: "type[BaseCommand] | BaseCommand",
+    *args: Any,
+    **options: Any,
+) -> Any:
+    """
+    Call the given BaseCommand subclass (or instance) programmatically.
+
+    Parameters
+    ----------
+    command:
+        A BaseCommand subclass or an already-instantiated command object.
+    *args:
+        Positional arguments forwarded to handle().
+    **options:
+        Keyword arguments forwarded to execute().
+
+    Returns
+    -------
+    Whatever handle() returns.
+
+    Raises
+    ------
+    CommandError
+        Propagated from handle() so callers can handle it themselves.
+    TypeError
+        If *command* is a type that is not a ``BaseCommand`` subclass.
+    """
+    if isinstance(command, type):
+        if not issubclass(command, BaseCommand):
+            raise TypeError(f"command must be a BaseCommand subclass, got {type(command)}")
+        command = command()
+
+    options.setdefault("verbosity", 1)
+    options.setdefault("traceback", False)
+
+    return command.execute(*args, **options)

python_base_command-0.1.0.dist-info/METADATA

@@ -0,0 +1,364 @@
+Metadata-Version: 2.4
+Name: python-base-command
+Version: 0.1.0
+Summary: Django-style BaseCommand framework for standalone Python CLI tools
+Project-URL: Homepage, https://github.com/yourusername/python-base-command
+Project-URL: Repository, https://github.com/yourusername/python-base-command
+Project-URL: Issues, https://github.com/yourusername/python-base-command/issues
+License: MIT
+License-File: LICENSE
+Keywords: argparse,cli,command,django,management
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: custom-python-logger==2.0.13
+Description-Content-Type: text/markdown
+
+![PyPI version](https://img.shields.io/pypi/v/python-base-command)
+![Python](https://img.shields.io/badge/python->=3.12-blue)
+![Development Status](https://img.shields.io/badge/status-stable-green)
+![Maintenance](https://img.shields.io/maintenance/yes/2026)
+![PyPI](https://img.shields.io/pypi/dm/python-base-command)
+![License](https://img.shields.io/pypi/l/python-base-command)
+
+---
+
+# python-base-command
+A Django-style `BaseCommand` framework for **standalone** Python CLI tools — no Django required.
+
+If you've ever written a Django management command and wished you could use the same clean pattern anywhere in Python, this is for you.
+
+---
+
+## 🚀 Features
+
+- ✅ **Django-style API** — `handle()`, `add_arguments()`, `CommandError`, `LabelCommand` — the same pattern you already know
+- ✅ **Built-in logging** — `self.logger` powered by [`custom-python-logger`](https://pypi.org/project/custom-python-logger/), with colored output and custom levels (`step`, `exception`)
+- ✅ **Auto-discovery** — drop `.py` files into a `commands/` folder and they're automatically available, just like Django's `manage.py`
+- ✅ **Manual registry** — register commands explicitly with the `@registry.register()` decorator
+- ✅ **Built-in flags** — every command gets `--version`, `--verbosity`, `--traceback` for free
+- ✅ **`call_command()`** — invoke commands programmatically, perfect for testing
+- ✅ **`output_transaction`** — wrap SQL output in `BEGIN;` / `COMMIT;` automatically
+- ✅ **Zero Django dependency** — works in any Python project
+- ✅ **Python 3.12+**
+
+---
+
+## 📦 Installation
+
+```bash
+pip install python-base-command
+```
+
+Dependencies: [`custom-python-logger==2.0.13`](https://pypi.org/project/custom-python-logger/) — installed automatically.
+
+---
+
+## ⚡ Quick Start
+
+Start by creating `cli.py` — your entry point, the equivalent of Django's `manage.py`. You only need this once:
+
+```python
+# cli.py
+from base_command import Runner
+
+Runner(commands_dir="commands").run()
+```
+
+Then add commands to a `commands/` folder:
+
+```
+myapp/
+├── cli.py               ← entry point (2 lines)
+└── commands/
+    ├── __init__.py
+    └── greet.py
+```
+
+```python
+# commands/greet.py
+from base_command import BaseCommand, CommandError
+
+
+class Command(BaseCommand):
+    help = "Greet a user by name"
+
+    def add_arguments(self, parser):
+        parser.add_argument("name", type=str, help="Name to greet")
+        parser.add_argument("--shout", action="store_true", help="Print in uppercase")
+
+    def handle(self, **kwargs):
+        name = kwargs["name"].strip()
+        if not name:
+            raise CommandError("Name cannot be empty.")
+
+        msg = f"Hello, {name}!"
+        if kwargs["shout"]:
+            msg = msg.upper()
+
+        self.logger.info(msg)
+```
+
+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
+```
+
+---
+
+## 📋 Manual Registry
+
+Register commands explicitly using the `@registry.register()` decorator — useful when commands live across different modules.
+
+```python
+from base_command import BaseCommand, CommandError, CommandRegistry
+
+registry = CommandRegistry()
+
+
+@registry.register("greet")
+class GreetCommand(BaseCommand):
+    help = "Greet a user"
+
+    def add_arguments(self, parser):
+        parser.add_argument("name", type=str)
+
+    def handle(self, **kwargs):
+        self.logger.info(f"Hello, {kwargs['name']}!")
+
+
+@registry.register("export")
+class ExportCommand(BaseCommand):
+    help = "Export data"
+
+    def add_arguments(self, parser):
+        parser.add_argument("--format", choices=["csv", "json"], default="csv")
+        parser.add_argument("--dry-run", action="store_true")
+
+    def handle(self, **kwargs):
+        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()
+```
+
+```bash
+python cli.py --help
+python cli.py greet Alice
+python cli.py export --format json
+python cli.py export --dry-run
+```
+
+---
+
+## 🧪 Testing with `call_command`
+
+Invoke commands programmatically — ideal for unit tests.
+
+```python
+from base_command import call_command, CommandError
+import pytest
+
+from commands.greet import Command as GreetCommand
+
+
+def test_greet():
+    result = call_command(GreetCommand, name="Alice")
+    assert result is None  # handle() logs, doesn't return
+
+
+def test_greet_empty_name():
+    with pytest.raises(CommandError, match="cannot be empty"):
+        call_command(GreetCommand, name="")
+```
+
+`CommandError` propagates normally when using `call_command()` — it is only caught and logged when invoked from the CLI.
+
+---
+
+## 📖 API Reference
+
+### `BaseCommand`
+
+Base class for all commands. Inherit from it and implement `handle()`.
+
+**Class attributes**
+
+| Attribute | Type | Default | Description |
+|---|---|---|---|
+| `help` | `str` | `""` | Description shown in `--help` |
+| `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()` |
+| `missing_args_message` | `str \| None` | `None` | Custom message when required positional args are missing |
+
+**Methods to override**
+
+| Method | Required | Description |
+|---|---|---|
+| `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`**
+
+A `CustomLoggerAdapter` from `custom-python-logger`, available inside every command:
+
+```python
+self.logger.debug("...")
+self.logger.info("...")
+self.logger.step("...")        # custom level for process steps
+self.logger.warning("...")
+self.logger.error("...")
+self.logger.critical("...")
+self.logger.exception("...")   # logs with full traceback
+```
+
+**Built-in flags** — available on every command automatically:
+
+| Flag | Description |
+|---|---|
+| `--version` | Print the version and exit |
+| `-v` / `--verbosity` | Verbosity level: 0=minimal, 1=normal, 2=verbose, 3=very verbose (default: 1) |
+| `--traceback` | Re-raise `CommandError` with full traceback instead of logging cleanly |
+
+---
+
+### `CommandError`
+
+Raise this to signal that something went wrong. When raised inside `handle()` during CLI invocation, it is caught, logged as an error, and the process exits with `returncode`. When invoked via `call_command()`, it propagates normally.
+
+```python
+raise CommandError("Something went wrong.")
+raise CommandError("Fatal error.", returncode=2)
+```
+
+---
+
+### `LabelCommand`
+
+For commands that accept one or more arbitrary string labels. Override `handle_label()` instead of `handle()`.
+
+```python
+from base_command import LabelCommand, CommandError
+
+
+class Command(LabelCommand):
+    label = "filepath"
+    help = "Process one or more files"
+
+    def add_arguments(self, parser):
+        super().add_arguments(parser)
+        parser.add_argument("--strict", action="store_true")
+
+    def handle_label(self, label, **kwargs):
+        if not label.endswith((".txt", ".csv", ".json")):
+            msg = f"Unsupported file type: '{label}'"
+            if kwargs["strict"]:
+                raise CommandError(msg)
+            self.logger.warning(f"Skipping — {msg}")
+            return None
+        self.logger.info(f"Processed: {label}")
+        return f"ok:{label}"
+```
+
+```bash
+python cli.py process report.csv notes.txt image.png
+python 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.
+
+```python
+from base_command import Runner
+
+Runner(commands_dir="commands").run()
+```
+
+Files whose names start with `_` are ignored.
+
+---
+
+### `CommandRegistry`
+
+Manually register commands using a decorator or programmatically.
+
+```python
+from base_command import 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
+```
+
+---
+
+### `call_command`
+
+Invoke a command from Python code. Accepts either a class or an instance.
+
+```python
+from base_command import call_command
+
+call_command(GreetCommand, name="Alice")
+call_command(GreetCommand, name="Alice", verbosity=0)
+call_command(GreetCommand())
+```
+
+---
+
+## 🔄 Comparison with Django
+
+| Feature | Django `BaseCommand` | `python-base-command` |
+|---|---|---|
+| `handle()` / `add_arguments()` | ✅ | ✅ |
+| `self.logger` (via custom-python-logger) | ❌ | ✅ |
+| `self.stdout` / `self.style` | ✅ | ❌ replaced by `self.logger` |
+| `--version` / `--verbosity` / `--traceback` | ✅ | ✅ |
+| `CommandError` with `returncode` | ✅ | ✅ |
+| `LabelCommand` | ✅ | ✅ |
+| `call_command()` | ✅ | ✅ |
+| `output_transaction` | ✅ | ✅ |
+| Auto-discovery from folder | ✅ | ✅ |
+| Manual registry | ❌ | ✅ |
+| Django dependency | ✅ required | ❌ none |
+
+---
+
+## 🤝 Contributing
+If you have a helpful tool, pattern, or improvement to suggest:
+Fork the repo <br>
+Create a new branch <br>
+Submit a pull request <br>
+I welcome additions that promote clean, productive, and maintainable development. <br>
+
+---
+
+## 🙏 Thanks
+Thanks for exploring this repository! <br>
+Happy coding! <br>

python_base_command-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+python_base_command/__init__.py,sha256=UoAfs_pYL9cYszbrHv_E9f10WzRHxwSzQEMkzBY-YfI,1064
+python_base_command/base.py,sha256=et8HITQhHCcE8oWoUv_10dNknWXNjeT9qD0CEL1EDr8,11028
+python_base_command/registry.py,sha256=WJl5IgjqOWRZuN36od1K-gm_RzDYCwivMkFSHqLbhe0,3883
+python_base_command/runner.py,sha256=_pRW_tn--DcLgCMkLxIAj4dI_sXAtIhNL9b5QOJpucg,5170
+python_base_command/utils.py,sha256=Q0U8uU1YgMJdeP4IpCktsI8dSjqgcF9nUnMTxOvqL0o,1320
+python_base_command-0.1.0.dist-info/METADATA,sha256=EMC54Kuo-069ausaubRpj-0yUTRjHqSF4WAtsZFadGg,10838
+python_base_command-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+python_base_command-0.1.0.dist-info/licenses/LICENSE,sha256=cSikHY6SZFsPZSBizCDAJ0-Bjjzxt-JtX6TVbKxwimo,1067
+python_base_command-0.1.0.dist-info/RECORD,,

python_base_command-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

python_base_command-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Avi Zaguri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.