qodalis-cli-server-abstractions 1.0.0b1__tar.gz

qodalis_cli_server_abstractions-1.0.0b1/.gitignore

@@ -0,0 +1,43 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Environment variables
+.env
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+TestResults/
+
+# Type checking / linting
+.mypy_cache/
+.ruff_cache/
+
+# C extensions
+*.so
+
+# IDEs and editors
+.idea/
+.vscode/*
+!.vscode/settings.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+# System files
+.DS_Store
+Thumbs.db

qodalis_cli_server_abstractions-1.0.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Qodalis Solutions
+
+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.

qodalis_cli_server_abstractions-1.0.0b1/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: qodalis-cli-server-abstractions
+Version: 1.0.0b1
+Summary: Shared interfaces and base classes for Qodalis CLI command processors — zero framework dependencies
+Project-URL: Homepage, https://github.com/qodalis-solutions/cli-server-python
+Project-URL: Repository, https://github.com/qodalis-solutions/cli-server-python
+Project-URL: Issues, https://github.com/qodalis-solutions/cli-server-python/issues
+Author-email: Nicolae Lupei <nicolae.lupei@qodalis.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: abstractions,cli,command-processor,commands,qodalis,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# qodalis-cli-server-abstractions
+
+Shared interfaces and base classes for building [Qodalis CLI](https://qodalis.com/) command processors in Python. **Zero framework dependencies** — install this package when writing plugins, without pulling in FastAPI, uvicorn, or websockets.
+
+## Install
+
+```bash
+pip install qodalis-cli-server-abstractions
+```
+
+## Quick Start
+
+Create a custom command processor by subclassing `CliCommandProcessor`:
+
+```python
+from qodalis_cli_server_abstractions import (
+    CliCommandProcessor,
+    CliProcessCommand,
+    CliCommandParameterDescriptor,
+)
+
+
+class GreetCommandProcessor(CliCommandProcessor):
+    @property
+    def command(self) -> str:
+        return "greet"
+
+    @property
+    def description(self) -> str:
+        return "Greets a user by name"
+
+    @property
+    def parameters(self):
+        return [
+            CliCommandParameterDescriptor("--name", "Name to greet", required=True),
+        ]
+
+    async def handle_async(self, command: CliProcessCommand) -> str:
+        name = command.args.get("name", "World")
+        return f"Hello, {name}!"
+```
+
+Then register the processor with the server package. See [`qodalis-cli-server`](https://pypi.org/project/qodalis-cli-server/) for server setup.
+
+## API Reference
+
+### Abstract Base Classes
+
+| Class | Description |
+|-------|-------------|
+| `ICliCommandProcessor` | Abstract base defining the processor contract: command, description, author, parameters, sub-processors, and `handle_async()` |
+| `CliCommandProcessor` | Convenience subclass of `ICliCommandProcessor` with sensible defaults |
+
+### Protocols
+
+| Protocol | Description |
+|----------|-------------|
+| `ICliCommandAuthor` | Author metadata: `name` and `email` (runtime-checkable) |
+| `ICliCommandParameterDescriptor` | Parameter declaration: name, type, required, aliases, default value (runtime-checkable) |
+
+### Data Classes
+
+| Class | Description |
+|-------|-------------|
+| `CliProcessCommand` | Parsed command input: `command`, `value`, `args`, `chain_commands`, `raw_command`, `data` |
+| `CliCommandAuthor` | Simple implementation of `ICliCommandAuthor` |
+| `CliCommandParameterDescriptor` | Simple implementation of `ICliCommandParameterDescriptor` |
+
+### Constants
+
+| Constant | Description |
+|----------|-------------|
+| `DEFAULT_LIBRARY_AUTHOR` | Default `CliCommandAuthor` instance used when no author is specified |
+
+### `ICliCommandProcessor` Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `command` | `str` | *(abstract)* | The command name users type to invoke this processor |
+| `description` | `str` | *(abstract)* | Human-readable description shown in help |
+| `author` | `ICliCommandAuthor` | `DEFAULT_LIBRARY_AUTHOR` | Author metadata |
+| `version` | `str` | `"1.0.0"` | Processor version |
+| `api_version` | `int` | `1` | Minimum API version this processor targets |
+| `allow_unlisted_commands` | `bool \| None` | `None` | Accept sub-commands not in `processors` list |
+| `value_required` | `bool \| None` | `None` | Whether a positional value argument is required |
+| `processors` | `list \| None` | `None` | Nested sub-command processors |
+| `parameters` | `list \| None` | `None` | Declared parameters for autocompletion and validation |
+| `handle_async(command)` | method | *(abstract)* | Execute the command, return result string |
+
+## License
+
+MIT

qodalis_cli_server_abstractions-1.0.0b1/README.md

@@ -0,0 +1,92 @@
+# qodalis-cli-server-abstractions
+
+Shared interfaces and base classes for building [Qodalis CLI](https://qodalis.com/) command processors in Python. **Zero framework dependencies** — install this package when writing plugins, without pulling in FastAPI, uvicorn, or websockets.
+
+## Install
+
+```bash
+pip install qodalis-cli-server-abstractions
+```
+
+## Quick Start
+
+Create a custom command processor by subclassing `CliCommandProcessor`:
+
+```python
+from qodalis_cli_server_abstractions import (
+    CliCommandProcessor,
+    CliProcessCommand,
+    CliCommandParameterDescriptor,
+)
+
+
+class GreetCommandProcessor(CliCommandProcessor):
+    @property
+    def command(self) -> str:
+        return "greet"
+
+    @property
+    def description(self) -> str:
+        return "Greets a user by name"
+
+    @property
+    def parameters(self):
+        return [
+            CliCommandParameterDescriptor("--name", "Name to greet", required=True),
+        ]
+
+    async def handle_async(self, command: CliProcessCommand) -> str:
+        name = command.args.get("name", "World")
+        return f"Hello, {name}!"
+```
+
+Then register the processor with the server package. See [`qodalis-cli-server`](https://pypi.org/project/qodalis-cli-server/) for server setup.
+
+## API Reference
+
+### Abstract Base Classes
+
+| Class | Description |
+|-------|-------------|
+| `ICliCommandProcessor` | Abstract base defining the processor contract: command, description, author, parameters, sub-processors, and `handle_async()` |
+| `CliCommandProcessor` | Convenience subclass of `ICliCommandProcessor` with sensible defaults |
+
+### Protocols
+
+| Protocol | Description |
+|----------|-------------|
+| `ICliCommandAuthor` | Author metadata: `name` and `email` (runtime-checkable) |
+| `ICliCommandParameterDescriptor` | Parameter declaration: name, type, required, aliases, default value (runtime-checkable) |
+
+### Data Classes
+
+| Class | Description |
+|-------|-------------|
+| `CliProcessCommand` | Parsed command input: `command`, `value`, `args`, `chain_commands`, `raw_command`, `data` |
+| `CliCommandAuthor` | Simple implementation of `ICliCommandAuthor` |
+| `CliCommandParameterDescriptor` | Simple implementation of `ICliCommandParameterDescriptor` |
+
+### Constants
+
+| Constant | Description |
+|----------|-------------|
+| `DEFAULT_LIBRARY_AUTHOR` | Default `CliCommandAuthor` instance used when no author is specified |
+
+### `ICliCommandProcessor` Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `command` | `str` | *(abstract)* | The command name users type to invoke this processor |
+| `description` | `str` | *(abstract)* | Human-readable description shown in help |
+| `author` | `ICliCommandAuthor` | `DEFAULT_LIBRARY_AUTHOR` | Author metadata |
+| `version` | `str` | `"1.0.0"` | Processor version |
+| `api_version` | `int` | `1` | Minimum API version this processor targets |
+| `allow_unlisted_commands` | `bool \| None` | `None` | Accept sub-commands not in `processors` list |
+| `value_required` | `bool \| None` | `None` | Whether a positional value argument is required |
+| `processors` | `list \| None` | `None` | Nested sub-command processors |
+| `parameters` | `list \| None` | `None` | Declared parameters for autocompletion and validation |
+| `handle_async(command)` | method | *(abstract)* | Execute the command, return result string |
+
+## License
+
+MIT

qodalis_cli_server_abstractions-1.0.0b1/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qodalis-cli-server-abstractions"
+version = "1.0.0b1"
+description = "Shared interfaces and base classes for Qodalis CLI command processors — zero framework dependencies"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Nicolae Lupei", email = "nicolae.lupei@qodalis.com" },
+]
+keywords = ["cli", "qodalis", "terminal", "commands", "command-processor", "abstractions"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+[project.urls]
+Homepage = "https://github.com/qodalis-solutions/cli-server-python"
+Repository = "https://github.com/qodalis-solutions/cli-server-python"
+Issues = "https://github.com/qodalis-solutions/cli-server-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qodalis_cli_server_abstractions"]

qodalis_cli_server_abstractions-1.0.0b1/src/qodalis_cli_server_abstractions/__init__.py

@@ -0,0 +1,21 @@
+from .cli_command_author import ICliCommandAuthor, CliCommandAuthor, DEFAULT_LIBRARY_AUTHOR
+from .cli_process_command import CliProcessCommand
+from .cli_command_parameter_descriptor import (
+    ICliCommandParameterDescriptor,
+    CliCommandParameterDescriptor,
+)
+from .cli_command_processor import ICliCommandProcessor, CliCommandProcessor
+from .cli_module import ICliModule, CliModule
+
+__all__ = [
+    "ICliCommandAuthor",
+    "CliCommandAuthor",
+    "DEFAULT_LIBRARY_AUTHOR",
+    "CliProcessCommand",
+    "ICliCommandParameterDescriptor",
+    "CliCommandParameterDescriptor",
+    "ICliCommandProcessor",
+    "CliCommandProcessor",
+    "ICliModule",
+    "CliModule",
+]

qodalis_cli_server_abstractions-1.0.0b1/src/qodalis_cli_server_abstractions/cli_command_author.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ICliCommandAuthor(Protocol):
+    name: str
+    email: str
+
+
+class CliCommandAuthor:
+    def __init__(self, name: str, email: str) -> None:
+        self.name = name
+        self.email = email
+
+
+DEFAULT_LIBRARY_AUTHOR = CliCommandAuthor("Nicolae Lupei", "nicolae.lupei@qodalis.com")

qodalis_cli_server_abstractions-1.0.0b1/src/qodalis_cli_server_abstractions/cli_command_parameter_descriptor.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ICliCommandParameterDescriptor(Protocol):
+    name: str
+    description: str
+    required: bool
+    type: str
+    aliases: list[str] | None
+    default_value: Any
+
+
+class CliCommandParameterDescriptor:
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        required: bool = False,
+        type: str = "string",
+        aliases: list[str] | None = None,
+        default_value: Any = None,
+    ) -> None:
+        self.name = name
+        self.description = description
+        self.required = required
+        self.type = type
+        self.aliases = aliases
+        self.default_value = default_value

qodalis_cli_server_abstractions-1.0.0b1/src/qodalis_cli_server_abstractions/cli_command_processor.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import abc
+from typing import TYPE_CHECKING
+
+from .cli_command_author import DEFAULT_LIBRARY_AUTHOR, ICliCommandAuthor
+
+if TYPE_CHECKING:
+    from .cli_command_parameter_descriptor import ICliCommandParameterDescriptor
+    from .cli_process_command import CliProcessCommand
+
+
+class ICliCommandProcessor(abc.ABC):
+    @property
+    @abc.abstractmethod
+    def command(self) -> str: ...
+
+    @property
+    @abc.abstractmethod
+    def description(self) -> str: ...
+
+    @property
+    def author(self) -> ICliCommandAuthor:
+        return DEFAULT_LIBRARY_AUTHOR
+
+    @property
+    def version(self) -> str:
+        return "1.0.0"
+
+    @property
+    def allow_unlisted_commands(self) -> bool | None:
+        return None
+
+    @property
+    def value_required(self) -> bool | None:
+        return None
+
+    @property
+    def api_version(self) -> int:
+        """API version this processor targets. Default 1 for backward compat."""
+        return 1
+
+    @property
+    def processors(self) -> list[ICliCommandProcessor] | None:
+        return None
+
+    @property
+    def parameters(self) -> list[ICliCommandParameterDescriptor] | None:
+        return None
+
+    @abc.abstractmethod
+    async def handle_async(self, command: CliProcessCommand) -> str: ...
+
+
+class CliCommandProcessor(ICliCommandProcessor):
+    """Convenience base class with sensible defaults."""
+
+    pass

qodalis_cli_server_abstractions-1.0.0b1/src/qodalis_cli_server_abstractions/cli_module.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import abc
+from typing import Sequence
+
+from .cli_command_processor import ICliCommandProcessor
+from .cli_command_author import ICliCommandAuthor, DEFAULT_LIBRARY_AUTHOR
+
+
+class ICliModule(abc.ABC):
+    """Represents a module that bundles one or more command processors."""
+
+    @property
+    @abc.abstractmethod
+    def name(self) -> str:
+        """Unique name of the module."""
+        ...
+
+    @property
+    @abc.abstractmethod
+    def version(self) -> str:
+        """Module version."""
+        ...
+
+    @property
+    @abc.abstractmethod
+    def description(self) -> str:
+        """Short description of the module."""
+        ...
+
+    @property
+    def author(self) -> ICliCommandAuthor:
+        """Author of the module."""
+        return DEFAULT_LIBRARY_AUTHOR
+
+    @property
+    @abc.abstractmethod
+    def processors(self) -> Sequence[ICliCommandProcessor]:
+        """Command processors provided by this module."""
+        ...
+
+
+class CliModule(ICliModule):
+    """Base class for CLI modules providing sensible defaults."""
+    pass

qodalis_cli_server_abstractions-1.0.0b1/src/qodalis_cli_server_abstractions/cli_process_command.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class CliProcessCommand:
+    command: str = ""
+    raw_command: str = ""
+    value: str | None = None
+    args: dict[str, Any] = field(default_factory=dict)
+    chain_commands: list[str] = field(default_factory=list)
+    data: Any = None