rhythmos-cli 0.1.0__tar.gz

rhythmos_cli-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+/.venv
+/.ipynb_checkpoints
+
+/.pytest_cache
+/.ruff_cache
+/.mypy_cache
+/.tox
+/.direnv
+/.eggs
+/*.egg-info
+/src/*.egg-info
+**/*.egg-info/
+
+/dist
+/build
+
+/__pycache__
+/*/__pycache__
+**/__pycache__/
+
+!/.gitignore
+
+/.vscode
+/tests/temp
+
+.env
+data/**/*.yml
+
+.DS_Store
+environment/*.env

rhythmos_cli-0.1.0/LICENCE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 JoanMbela
+
+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.

rhythmos_cli-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: rhythmos-cli
+Version: 0.1.0
+Summary: A lightweight CLI framework with project-local auto-discovered commands
+Project-URL: Homepage, https://gitlab.com/JoanMbela/rhythmos-cli
+Project-URL: Repository, https://gitlab.com/JoanMbela/rhythmos-cli
+Author-email: mbela imm <mbela.immongault@globalnext.rocks>
+License-Expression: MIT
+License-File: LICENCE
+Keywords: argparse,cli,commands
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Rhythmos CLI
+
+A lightweight CLI framework. Install once, put commands in each project's `commands/` folder.
+
+## Install
+
+```bash
+pip install rhythmos-cli
+```
+
+## Usage
+
+In any project:
+
+```bash
+rhythmos-cli make hello -d "Say hello to someone"
+# edit commands/hello.py
+rhythmos-cli hello Alice
+```
+
+`rhythmos` is an optional shorthand for the same CLI.
+
+`make` and `list` are built-in system commands. If you define a user command with the same name, yours wins and a warning is printed.
+
+Commands are loaded from `./commands` (cwd), or from `RHYTHMOS_COMMANDS` if set.
+
+## Write a command
+
+```python
+from rhythmos import BaseCommand
+
+
+class HelloCommand(BaseCommand):
+    def get_description(self):
+        return "Say hello to someone"
+
+    def add_arguments(self):
+        self.parser.add_argument("name", help="Name of the person to greet")
+
+    def handle(self, name):
+        print(f"Hello, {name}!")
+```
+
+File `commands/foo_bar.py` → `rhythmos-cli foo-bar`.
+
+See `examples/commands/hello.py` for a ready example.
+
+## Develop this package
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+RHYTHMOS_COMMANDS=examples/commands rhythmos-cli hello World
+```

rhythmos_cli-0.1.0/README.md

@@ -0,0 +1,55 @@
+# Rhythmos CLI
+
+A lightweight CLI framework. Install once, put commands in each project's `commands/` folder.
+
+## Install
+
+```bash
+pip install rhythmos-cli
+```
+
+## Usage
+
+In any project:
+
+```bash
+rhythmos-cli make hello -d "Say hello to someone"
+# edit commands/hello.py
+rhythmos-cli hello Alice
+```
+
+`rhythmos` is an optional shorthand for the same CLI.
+
+`make` and `list` are built-in system commands. If you define a user command with the same name, yours wins and a warning is printed.
+
+Commands are loaded from `./commands` (cwd), or from `RHYTHMOS_COMMANDS` if set.
+
+## Write a command
+
+```python
+from rhythmos import BaseCommand
+
+
+class HelloCommand(BaseCommand):
+    def get_description(self):
+        return "Say hello to someone"
+
+    def add_arguments(self):
+        self.parser.add_argument("name", help="Name of the person to greet")
+
+    def handle(self, name):
+        print(f"Hello, {name}!")
+```
+
+File `commands/foo_bar.py` → `rhythmos-cli foo-bar`.
+
+See `examples/commands/hello.py` for a ready example.
+
+## Develop this package
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+RHYTHMOS_COMMANDS=examples/commands rhythmos-cli hello World
+```

rhythmos_cli-0.1.0/examples/commands/hello.py

@@ -0,0 +1,12 @@
+from rhythmos import BaseCommand
+
+
+class HelloCommand(BaseCommand):
+    def get_description(self):
+        return "Say hello to someone"
+
+    def add_arguments(self):
+        self.parser.add_argument("name", help="Name of the person to greet")
+
+    def handle(self, name):
+        print(f"Hello, {name}! Welcome to your custom CLI.")

rhythmos_cli-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rhythmos-cli"
+version = "0.1.0"
+description = "A lightweight CLI framework with project-local auto-discovered commands"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "mbela imm", email = "mbela.immongault@globalnext.rocks" },
+]
+keywords = ["cli", "argparse", "commands"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+
+[project.urls]
+Homepage = "https://gitlab.com/JoanMbela/rhythmos-cli"
+Repository = "https://gitlab.com/JoanMbela/rhythmos-cli"
+
+[project.scripts]
+rhythmos-cli = "rhythmos.cli:main"
+rhythmos = "rhythmos.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/rhythmos"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/examples",
+    "/README.md",
+    "/LICENCE",
+]

rhythmos_cli-0.1.0/src/rhythmos/__init__.py

@@ -0,0 +1,6 @@
+"""Rhythmos — a lightweight project CLI framework."""
+
+from rhythmos.base_command import BaseCommand
+
+__version__ = "0.1.0"
+__all__ = ["BaseCommand", "__version__"]

rhythmos_cli-0.1.0/src/rhythmos/__main__.py

@@ -0,0 +1,4 @@
+from rhythmos.cli import main
+
+if __name__ == "__main__":
+    main()

rhythmos_cli-0.1.0/src/rhythmos/base_command.py

@@ -0,0 +1,19 @@
+import argparse
+
+
+class BaseCommand:
+    def __init__(self):
+        self.parser = argparse.ArgumentParser(description=self.get_description())
+        self.add_arguments()
+
+    def get_description(self):
+        return "A command for the CLI"
+
+    def add_arguments(self):
+        pass
+
+    def handle(self, *args, **options):
+        raise NotImplementedError("You must implement the handle method.")
+
+    def run(self, namespace):
+        self.handle(**vars(namespace))

rhythmos_cli-0.1.0/src/rhythmos/cli.py

@@ -0,0 +1,70 @@
+import argparse
+import sys
+
+from rhythmos.base_command import BaseCommand
+from rhythmos.discovery import commands_dir, discover_commands, invoked_as
+from rhythmos.system_commands import SYSTEM_COMMANDS
+
+
+def resolve_commands() -> dict[str, type[BaseCommand]]:
+    """Merge system + user commands. User commands win on name clashes."""
+    user = discover_commands()
+    for name in user:
+        if name in SYSTEM_COMMANDS:
+            print(
+                f"Warning: user command '{name}' overrides system command '{name}'",
+                file=sys.stderr,
+            )
+    return {**SYSTEM_COMMANDS, **user}
+
+
+def main(argv: list[str] | None = None) -> None:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    cli = invoked_as()
+
+    parser = argparse.ArgumentParser(prog=cli, description="Rhythmos CLI")
+    subparsers = parser.add_subparsers(
+        dest="command", help="Command to execute", required=True
+    )
+
+    commands = resolve_commands()
+    command_instances = {}
+
+    for command_name, command_class in commands.items():
+        command_instance = command_class()
+        command_instances[command_name] = command_instance
+        subparsers.add_parser(
+            command_name,
+            help=command_instance.get_description(),
+            parents=[command_instance.parser],
+            conflict_handler="resolve",
+        )
+
+    try:
+        args = parser.parse_args(argv)
+        command_name = args.command
+
+        if command_name not in command_instances:
+            print(f"Command '{command_name}' not found.")
+            print(f"Looking in: {commands_dir()}")
+            print(f"Create one with: {cli} make <name>")
+            raise SystemExit(1)
+
+        args_dict = vars(args)
+        args_dict.pop("command", None)
+        command_instances[command_name].run(argparse.Namespace(**args_dict))
+
+    except KeyboardInterrupt:
+        print("\nOPERATION CANCELLED.\n")
+        raise SystemExit(130) from None
+
+    except SystemExit:
+        raise
+
+    except Exception as e:
+        print(f"\nERROR: {str(e)}\n")
+        raise SystemExit(1) from e
+
+
+if __name__ == "__main__":
+    main()

rhythmos_cli-0.1.0/src/rhythmos/discovery.py

@@ -0,0 +1,94 @@
+import importlib.util
+import inspect
+import os
+import re
+import sys
+from pathlib import Path
+
+from rhythmos.base_command import BaseCommand
+
+COMMANDS_DIR_ENV = "RHYTHMOS_COMMANDS"
+DEFAULT_COMMANDS_DIR = "commands"
+SKIP_STEMS = {"__init__", "base_command"}
+
+
+def commands_dir() -> Path:
+    override = os.environ.get(COMMANDS_DIR_ENV)
+    if override:
+        return Path(override).expanduser().resolve()
+    return (Path.cwd() / DEFAULT_COMMANDS_DIR).resolve()
+
+
+def invoked_as() -> str:
+    name = Path(sys.argv[0]).name
+    return name if name else "rhythmos-cli"
+
+
+def _load_module(path: Path):
+    module_name = f"rhythmos_user_commands.{path.stem}"
+    spec = importlib.util.spec_from_file_location(module_name, path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Could not load {path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def discover_commands(directory: Path | None = None) -> dict[str, type[BaseCommand]]:
+    directory = directory or commands_dir()
+    found: dict[str, type[BaseCommand]] = {}
+
+    if not directory.is_dir():
+        return found
+
+    for file in sorted(directory.glob("*.py")):
+        if file.stem in SKIP_STEMS or file.stem.startswith("_"):
+            continue
+
+        try:
+            module = _load_module(file)
+        except Exception as e:
+            print(f"Warning: Could not load command from {file}: {e}", file=sys.stderr)
+            continue
+
+        for _, obj in inspect.getmembers(module):
+            if (
+                inspect.isclass(obj)
+                and issubclass(obj, BaseCommand)
+                and obj is not BaseCommand
+            ):
+                found[file.stem.replace("_", "-")] = obj
+                break
+
+    return found
+
+
+def to_snake(name: str) -> str:
+    name = name.replace("-", "_")
+    name = re.sub(r"(?<!^)(?=[A-Z])", "_", name)
+    return re.sub(r"[^a-zA-Z0-9_]", "_", name).lower().strip("_")
+
+
+def to_class_name(snake: str) -> str:
+    return "".join(part.capitalize() for part in snake.split("_") if part)
+
+
+def scaffold_command(name: str, description: str = "A command for the CLI") -> Path:
+    directory = commands_dir()
+    directory.mkdir(parents=True, exist_ok=True)
+
+    snake = to_snake(name)
+    if not snake:
+        raise ValueError("Command name is empty")
+
+    target = directory / f"{snake}.py"
+    if target.exists():
+        raise FileExistsError(f"Command already exists: {target}")
+
+    stub = Path(__file__).parent / "stubs" / "command.py.stub"
+    contents = stub.read_text(encoding="utf-8")
+    contents = contents.replace("{{ClassName}}", to_class_name(snake))
+    contents = contents.replace("{{description}}", description)
+    target.write_text(contents, encoding="utf-8")
+    return target

rhythmos_cli-0.1.0/src/rhythmos/stubs/command.py.stub

@@ -0,0 +1,13 @@
+from rhythmos import BaseCommand
+
+
+class {{ClassName}}Command(BaseCommand):
+    def get_description(self):
+        return "{{description}}"
+
+    def add_arguments(self):
+        # self.parser.add_argument("name", help="...")
+        pass
+
+    def handle(self, **options):
+        raise NotImplementedError("Implement this command.")

rhythmos_cli-0.1.0/src/rhythmos/system_commands/__init__.py

@@ -0,0 +1,10 @@
+from rhythmos.base_command import BaseCommand
+from rhythmos.system_commands.list import ListCommand
+from rhythmos.system_commands.make import MakeCommand
+
+SYSTEM_COMMANDS: dict[str, type[BaseCommand]] = {
+    "make": MakeCommand,
+    "list": ListCommand,
+}
+
+__all__ = ["SYSTEM_COMMANDS", "MakeCommand", "ListCommand"]

rhythmos_cli-0.1.0/src/rhythmos/system_commands/list.py

@@ -0,0 +1,21 @@
+from rhythmos.base_command import BaseCommand
+from rhythmos.discovery import commands_dir, discover_commands
+
+
+class ListCommand(BaseCommand):
+    """System command: list system and user commands."""
+
+    def get_description(self):
+        return "List all available commands"
+
+    def handle(self):
+        from rhythmos.system_commands import SYSTEM_COMMANDS
+
+        user = discover_commands()
+        merged = {**SYSTEM_COMMANDS, **user}
+        print(f"Commands directory: {commands_dir()}")
+        print()
+        for name in sorted(merged):
+            origin = "user" if name in user else "system"
+            description = merged[name]().get_description()
+            print(f"  {name:<16} [{origin:<6}]  {description}")

rhythmos_cli-0.1.0/src/rhythmos/system_commands/make.py

@@ -0,0 +1,25 @@
+from rhythmos.base_command import BaseCommand
+from rhythmos.discovery import invoked_as, scaffold_command
+
+
+class MakeCommand(BaseCommand):
+    """System command: scaffold a user command in the project."""
+
+    def get_description(self):
+        return "Create a command in this project's commands/"
+
+    def add_arguments(self):
+        self.parser.add_argument("name", help="Command name (snake or kebab case)")
+        self.parser.add_argument(
+            "-d",
+            "--description",
+            default="A command for the CLI",
+            help="Short help text for the command",
+        )
+
+    def handle(self, name, description="A command for the CLI"):
+        cli = invoked_as()
+        path = scaffold_command(name, description)
+        kebab = path.stem.replace("_", "-")
+        print(f"Created {path}")
+        print(f"Run it with: {cli} {kebab}")