| Name | mancer JSON |
| Version |
0.1.4
JSON |
| download |
| home_page | None |
| Summary | Framework DDD dla komend systemowych |
| upload_time | 2025-08-21 17:21:26 |
| maintainer | None |
| docs_url | None |
| author | Kacper Paczos |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
ddd
commands
framework
system
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Mancer
Mancer — Multisystem Programmable Engine
A domain-driven framework for programmable system automation: local bash and remote SSH, composable commands, structured results (JSON/DataFrame/ndarray), execution history, and version-aware behavior.
> **Status: Early-stage development version 0.1** - This is a pre-release version under active development. The API may evolve between releases. We appreciate feedback and contributions.
> **⚠️ Platform Support: Linux Only** - Mancer currently supports Linux systems only. Windows and macOS support is planned for future releases.
## Installation
### From PyPI (recommended)
```bash
pip install -U mancer
```
### From source
```bash
git clone https://github.com/Liberos-Systems/mancer.git
cd mancer
python -m venv .venv && source .venv/bin/activate
pip install -e .
```
## What is Mancer?
- Execute system commands locally (bash) or remotely (SSH) via a unified API
- Compose commands into pipelines and reusable building blocks
- Get structured results (JSON / pandas DataFrame / NumPy ndarray)
- Track execution history and metadata for auditing and analysis
- Adapt to tool versions with version‑aware behavior
- Extend with your own commands and backends
## Quickstart
```python
from mancer.application.shell_runner import ShellRunner
runner = ShellRunner(backend_type="bash")
cmd = runner.create_command("echo").text("hello mancer")
result = runner.execute(cmd)
print(result.raw_output)
```
## Examples
- Quick Examples: [User Guide Examples](docs/user-guide/examples.md)
- All Examples: [Examples Directory](docs/examples/all-examples.md)
## Documentation
- Getting Started: [Installation Guide](docs/getting-started/installation.md)
- User Guide: [Commands & Usage](docs/user-guide/commands.md)
- API Reference: [API Documentation](docs/api.md)
- Development: [Developer Guide](docs/development.md)
## How Mancer differs from Plumbum
Mancer is a domain-focused automation framework; Plumbum is a lightweight Pythonic shell toolbox. Both are valuable, but they serve different purposes.
- Domain model & history
- Mancer: CommandResult with execution history/metadata for analysis and reporting
- Plumbum: Emphasis on concise shell combinators and piping
- Data conversion
- Mancer: Built-in converters to JSON/DataFrame/ndarray
- Plumbum: Operates on stdio/strings; conversions left to user
- Version-aware behavior
- Mancer: Detects tool versions and adapts parsing/behavior
- Plumbum: No built-in tool version compatibility layer
- Extensibility via commands/backends
- Mancer: Extensible command classes and execution backends
- Plumbum: Focused on shell DSL and process primitives
- Orchestration and context
- Mancer: Unified CommandContext (env, cwd, remote) and ShellRunner orchestration
- Plumbum: Excellent primitives; orchestration remains in user code
See Plumbum: https://github.com/tomerfiliba/plumbum
## Roadmap & Status
- Status: Early development version 0.1, API subject to change
- Planned: richer CLI, more system commands, more backends, Windows/PowerShell maturity, extended data adapters
- **Platform Support**: Linux (current), Windows and macOS (planned)
## Contributing
```bash
git clone https://github.com/Liberos-Systems/mancer.git
cd mancer
python -m venv .venv && source .venv/bin/activate
pip install -e .[dev]
pytest -q
```
## Versioning and Releases
- Semantic Versioning (pre‑1.0 semantics apply)
- Release notes in GitHub Releases
## License
MIT
## Links
- Repository: https://github.com/Liberos-Systems/mancer
- Issues: https://github.com/Liberos-Systems/mancer/issues
- Documentation: [docs/](docs/)
## Available Tools
The framework provides several tools to facilitate work:
### Development Environment Setup Script
```bash
./dev_tools/mancer_tools.sh
```
### Running Tests
```bash
./scripts/run_tests.sh # All tests
./scripts/run_tests.sh --unit # Only unit tests
./scripts/run_tests.sh --coverage # With code coverage report
```
### Managing Tool Versions
```bash
./dev_tools/mancer_tools.sh --versions list # List all versions
./dev_tools/mancer_tools.sh --versions list ls # Versions for a specific tool
./dev_tools/mancer_tools.sh --versions add grep 3.8 # Add a version manually
./dev_tools/mancer_tools.sh --versions detect --all # Detect and add all versions
./dev_tools/mancer_tools.sh --versions detect ls grep # Detect specific tools
./dev_tools/mancer_tools.sh --versions remove df 2.34 # Remove a version
```
## Usage Examples
The `examples/` directory contains examples demonstrating various framework capabilities:
- `basic_usage.py` - Basic command usage
- `remote_usage.py` - Remote command execution via SSH
- `remote_sudo_usage.py` - Remote command execution with sudo
- `command_chains.py` - Chaining commands
- `data_formats_usage.py` - Working with different data formats
- `cache_usage.py` - Caching command results
- `version_checking.py` - Checking system tool versions
To run an example:
```bash
cd examples
python basic_usage.py
```
## Core Classes: ShellRunner vs CommandManager
Mancer provides two main approaches for command execution:
### ShellRunner (Recommended for most users)
- **High-level interface** for quick command execution
- **Automatic context management** (working directory, environment variables)
- **Built-in remote execution** support via SSH
- **Simplified API** for common use cases
```python
from mancer.application.shell_runner import ShellRunner
runner = ShellRunner(backend_type="bash")
result = runner.execute(runner.create_command("ls").long())
```
### CommandManager
- **Lower-level interface** for advanced command orchestration
- **Manual context management** for fine-grained control
- **Command chaining and pipelines** with explicit control
- **Advanced features** like execution history and caching
```python
from mancer.application.command_manager import CommandManager
from mancer.domain.model.command_context import CommandContext
manager = CommandManager()
context = CommandContext()
result = manager.execute_command("ls -la", context)
```
For most users, **ShellRunner** is the recommended starting point. Use **CommandManager** when you need advanced features or fine-grained control over command execution.
## Tool Versioning Mechanism
Mancer includes a unique system tool versioning mechanism that allows:
1. Defining allowed tool versions in configuration files
2. Automatically detecting tool versions in the system
3. Warning when a version is not on the whitelist
4. **Adapting command behavior based on the detected tool version** for backward compatibility
The configuration of allowed versions is located in the file `~/.mancer/tool_versions.yaml` or `src/mancer/config/tool_versions.yaml`.
### Version Compatibility Example
```python
from mancer.domain.model.command_context import CommandContext
from mancer.infrastructure.command.system.ls_command import LsCommand
# Create context
context = CommandContext()
# Execute ls command with version verification
ls_command = LsCommand().with_option("-la")
result = ls_command.execute(context)
# Check for version warnings
if result.metadata and "version_warnings" in result.metadata:
print("Version warnings:")
for warning in result.metadata["version_warnings"]:
print(f" - {warning}")
```
## Configuration
The framework uses YAML configuration files:
- `tool_versions.yaml` - Allowed system tool versions
- `settings.yaml` - General framework settings
Configuration files are searched in the following order:
1. Current directory
2. `~/.mancer/`
3. `/etc/mancer/`
4. Package directory `src/mancer/config/`
## Creating Custom Commands
You can create custom commands by extending the `BaseCommand` class:
```python
from mancer.infrastructure.command.base_command import BaseCommand
from mancer.domain.model.command_context import CommandContext
from mancer.domain.model.command_result import CommandResult
class MyCustomCommand(BaseCommand):
# Define tool name for version checking
tool_name = "my_tool"
def __init__(self):
super().__init__("my-command")
def execute(self, context: CommandContext, input_result=None) -> CommandResult:
# Build command string
command_str = self.build_command()
# Get appropriate backend
backend = self._get_backend(context)
# Execute command
exit_code, output, error = backend.execute(command_str)
# Process result
return self._prepare_result(
raw_output=output,
success=exit_code == 0,
exit_code=exit_code,
error_message=error,
metadata={}
)
def _parse_output(self, raw_output: str):
# Convert command output to structured data
# ...
return structured_data
```
## New Logging System
Since version 0.1.0, Mancer includes an advanced logging system based on the Icecream library, which significantly simplifies debugging and monitoring commands.
### Main Features
- **Automatic Icecream detection** - if the Icecream library is available, the system uses it for log formatting; otherwise, it uses the standard Python logger
- **Hierarchical logging** - clearly organized logs at different levels (debug, info, warning, error, critical)
- **Pipeline tracking** - automatic logging of command input and output data in chains
- **Execution history** - complete history of executed commands with execution times and statuses
- **Command chain logging** - visualization of command chain structures
- **Support for multiple data formats** - structural formatting of command results
### Usage Example
```python
from mancer.infrastructure.logging.mancer_logger import MancerLogger
from mancer.domain.service.log_backend_interface import LogLevel
# Get singleton logger instance
logger = MancerLogger.get_instance()
# Configure logger
logger.initialize(
log_level=LogLevel.DEBUG, # Logging level
console_enabled=True, # Console logging
file_enabled=True, # File logging
log_file="mancer.log" # Log file name
)
# Logging at different levels
logger.debug("Detailed debugging information")
logger.info("Progress information")
logger.warning("Warning about a potential problem")
logger.error("Error during execution")
# Logging with context (additional data)
logger.info("Connecting to host", {
"host": "example.com",
"port": 22,
"user": "admin"
})
```
More detailed examples can be found in the `examples/new_logger_example.py` file.
## License
This project is available under the [MIT license](LICENSE).
Raw data
{
"_id": null,
"home_page": null,
"name": "mancer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "ddd, commands, framework, system",
"author": "Kacper Paczos",
"author_email": "Kacper Paczos <kacperpaczos2024@proton.me>",
"download_url": "https://files.pythonhosted.org/packages/04/d5/3d9e295dbb6cd50477ec3e01ccb962042f87350c36d6d27401d21a003e34/mancer-0.1.4.tar.gz",
"platform": null,
"description": "# Mancer\n\nMancer \u2014 Multisystem Programmable Engine\n\nA domain-driven framework for programmable system automation: local bash and remote SSH, composable commands, structured results (JSON/DataFrame/ndarray), execution history, and version-aware behavior.\n\n> **Status: Early-stage development version 0.1** - This is a pre-release version under active development. The API may evolve between releases. We appreciate feedback and contributions.\n\n> **\u26a0\ufe0f Platform Support: Linux Only** - Mancer currently supports Linux systems only. Windows and macOS support is planned for future releases.\n\n## Installation\n\n### From PyPI (recommended)\n```bash\npip install -U mancer\n```\n\n### From source\n```bash\ngit clone https://github.com/Liberos-Systems/mancer.git\ncd mancer\npython -m venv .venv && source .venv/bin/activate\npip install -e .\n```\n\n## What is Mancer?\n- Execute system commands locally (bash) or remotely (SSH) via a unified API\n- Compose commands into pipelines and reusable building blocks\n- Get structured results (JSON / pandas DataFrame / NumPy ndarray)\n- Track execution history and metadata for auditing and analysis\n- Adapt to tool versions with version\u2011aware behavior\n- Extend with your own commands and backends\n\n## Quickstart\n```python\nfrom mancer.application.shell_runner import ShellRunner\n\nrunner = ShellRunner(backend_type=\"bash\")\ncmd = runner.create_command(\"echo\").text(\"hello mancer\")\nresult = runner.execute(cmd)\nprint(result.raw_output)\n```\n\n## Examples\n- Quick Examples: [User Guide Examples](docs/user-guide/examples.md)\n- All Examples: [Examples Directory](docs/examples/all-examples.md)\n\n## Documentation\n- Getting Started: [Installation Guide](docs/getting-started/installation.md)\n- User Guide: [Commands & Usage](docs/user-guide/commands.md)\n- API Reference: [API Documentation](docs/api.md)\n- Development: [Developer Guide](docs/development.md)\n\n## How Mancer differs from Plumbum\nMancer is a domain-focused automation framework; Plumbum is a lightweight Pythonic shell toolbox. Both are valuable, but they serve different purposes.\n\n- Domain model & history\n - Mancer: CommandResult with execution history/metadata for analysis and reporting\n - Plumbum: Emphasis on concise shell combinators and piping\n- Data conversion\n - Mancer: Built-in converters to JSON/DataFrame/ndarray\n - Plumbum: Operates on stdio/strings; conversions left to user\n- Version-aware behavior\n - Mancer: Detects tool versions and adapts parsing/behavior\n - Plumbum: No built-in tool version compatibility layer\n- Extensibility via commands/backends\n - Mancer: Extensible command classes and execution backends\n - Plumbum: Focused on shell DSL and process primitives\n- Orchestration and context\n - Mancer: Unified CommandContext (env, cwd, remote) and ShellRunner orchestration\n - Plumbum: Excellent primitives; orchestration remains in user code\n\nSee Plumbum: https://github.com/tomerfiliba/plumbum\n\n## Roadmap & Status\n- Status: Early development version 0.1, API subject to change\n- Planned: richer CLI, more system commands, more backends, Windows/PowerShell maturity, extended data adapters\n- **Platform Support**: Linux (current), Windows and macOS (planned)\n\n## Contributing\n```bash\ngit clone https://github.com/Liberos-Systems/mancer.git\ncd mancer\npython -m venv .venv && source .venv/bin/activate\npip install -e .[dev]\npytest -q\n```\n\n## Versioning and Releases\n- Semantic Versioning (pre\u20111.0 semantics apply)\n- Release notes in GitHub Releases\n\n## License\nMIT\n\n## Links\n- Repository: https://github.com/Liberos-Systems/mancer\n- Issues: https://github.com/Liberos-Systems/mancer/issues\n- Documentation: [docs/](docs/)\n\n## Available Tools\n\nThe framework provides several tools to facilitate work:\n\n### Development Environment Setup Script\n\n```bash\n./dev_tools/mancer_tools.sh\n```\n\n### Running Tests\n\n```bash\n./scripts/run_tests.sh # All tests\n./scripts/run_tests.sh --unit # Only unit tests\n./scripts/run_tests.sh --coverage # With code coverage report\n```\n\n### Managing Tool Versions\n\n```bash\n./dev_tools/mancer_tools.sh --versions list # List all versions\n./dev_tools/mancer_tools.sh --versions list ls # Versions for a specific tool\n./dev_tools/mancer_tools.sh --versions add grep 3.8 # Add a version manually\n./dev_tools/mancer_tools.sh --versions detect --all # Detect and add all versions\n./dev_tools/mancer_tools.sh --versions detect ls grep # Detect specific tools\n./dev_tools/mancer_tools.sh --versions remove df 2.34 # Remove a version\n```\n\n## Usage Examples\n\nThe `examples/` directory contains examples demonstrating various framework capabilities:\n\n- `basic_usage.py` - Basic command usage\n- `remote_usage.py` - Remote command execution via SSH\n- `remote_sudo_usage.py` - Remote command execution with sudo\n- `command_chains.py` - Chaining commands\n- `data_formats_usage.py` - Working with different data formats\n- `cache_usage.py` - Caching command results\n- `version_checking.py` - Checking system tool versions\n\nTo run an example:\n\n```bash\ncd examples\npython basic_usage.py\n```\n\n## Core Classes: ShellRunner vs CommandManager\n\nMancer provides two main approaches for command execution:\n\n### ShellRunner (Recommended for most users)\n- **High-level interface** for quick command execution\n- **Automatic context management** (working directory, environment variables)\n- **Built-in remote execution** support via SSH\n- **Simplified API** for common use cases\n\n```python\nfrom mancer.application.shell_runner import ShellRunner\n\nrunner = ShellRunner(backend_type=\"bash\")\nresult = runner.execute(runner.create_command(\"ls\").long())\n```\n\n### CommandManager\n- **Lower-level interface** for advanced command orchestration\n- **Manual context management** for fine-grained control\n- **Command chaining and pipelines** with explicit control\n- **Advanced features** like execution history and caching\n\n```python\nfrom mancer.application.command_manager import CommandManager\nfrom mancer.domain.model.command_context import CommandContext\n\nmanager = CommandManager()\ncontext = CommandContext()\nresult = manager.execute_command(\"ls -la\", context)\n```\n\nFor most users, **ShellRunner** is the recommended starting point. Use **CommandManager** when you need advanced features or fine-grained control over command execution.\n\n## Tool Versioning Mechanism\n\nMancer includes a unique system tool versioning mechanism that allows:\n\n1. Defining allowed tool versions in configuration files\n2. Automatically detecting tool versions in the system\n3. Warning when a version is not on the whitelist\n4. **Adapting command behavior based on the detected tool version** for backward compatibility\n\nThe configuration of allowed versions is located in the file `~/.mancer/tool_versions.yaml` or `src/mancer/config/tool_versions.yaml`.\n\n### Version Compatibility Example\n\n```python\nfrom mancer.domain.model.command_context import CommandContext\nfrom mancer.infrastructure.command.system.ls_command import LsCommand\n\n# Create context\ncontext = CommandContext()\n\n# Execute ls command with version verification\nls_command = LsCommand().with_option(\"-la\")\nresult = ls_command.execute(context)\n\n# Check for version warnings\nif result.metadata and \"version_warnings\" in result.metadata:\n print(\"Version warnings:\")\n for warning in result.metadata[\"version_warnings\"]:\n print(f\" - {warning}\")\n```\n\n## Configuration\n\nThe framework uses YAML configuration files:\n\n- `tool_versions.yaml` - Allowed system tool versions\n- `settings.yaml` - General framework settings\n\nConfiguration files are searched in the following order:\n1. Current directory\n2. `~/.mancer/`\n3. `/etc/mancer/`\n4. Package directory `src/mancer/config/`\n\n## Creating Custom Commands\n\nYou can create custom commands by extending the `BaseCommand` class:\n\n```python\nfrom mancer.infrastructure.command.base_command import BaseCommand\nfrom mancer.domain.model.command_context import CommandContext\nfrom mancer.domain.model.command_result import CommandResult\n\nclass MyCustomCommand(BaseCommand):\n # Define tool name for version checking\n tool_name = \"my_tool\"\n \n def __init__(self):\n super().__init__(\"my-command\")\n \n def execute(self, context: CommandContext, input_result=None) -> CommandResult:\n # Build command string\n command_str = self.build_command()\n \n # Get appropriate backend\n backend = self._get_backend(context)\n \n # Execute command\n exit_code, output, error = backend.execute(command_str)\n \n # Process result\n return self._prepare_result(\n raw_output=output,\n success=exit_code == 0,\n exit_code=exit_code,\n error_message=error,\n metadata={}\n )\n \n def _parse_output(self, raw_output: str):\n # Convert command output to structured data\n # ...\n return structured_data\n```\n\n## New Logging System\n\nSince version 0.1.0, Mancer includes an advanced logging system based on the Icecream library, which significantly simplifies debugging and monitoring commands.\n\n### Main Features\n\n- **Automatic Icecream detection** - if the Icecream library is available, the system uses it for log formatting; otherwise, it uses the standard Python logger\n- **Hierarchical logging** - clearly organized logs at different levels (debug, info, warning, error, critical)\n- **Pipeline tracking** - automatic logging of command input and output data in chains\n- **Execution history** - complete history of executed commands with execution times and statuses\n- **Command chain logging** - visualization of command chain structures\n- **Support for multiple data formats** - structural formatting of command results\n\n### Usage Example\n\n```python\nfrom mancer.infrastructure.logging.mancer_logger import MancerLogger\nfrom mancer.domain.service.log_backend_interface import LogLevel\n\n# Get singleton logger instance\nlogger = MancerLogger.get_instance()\n\n# Configure logger\nlogger.initialize(\n log_level=LogLevel.DEBUG, # Logging level\n console_enabled=True, # Console logging\n file_enabled=True, # File logging\n log_file=\"mancer.log\" # Log file name\n)\n\n# Logging at different levels\nlogger.debug(\"Detailed debugging information\")\nlogger.info(\"Progress information\")\nlogger.warning(\"Warning about a potential problem\")\nlogger.error(\"Error during execution\")\n\n# Logging with context (additional data)\nlogger.info(\"Connecting to host\", {\n \"host\": \"example.com\",\n \"port\": 22,\n \"user\": \"admin\"\n})\n```\n\nMore detailed examples can be found in the `examples/new_logger_example.py` file.\n\n## License\n\nThis project is available under the [MIT license](LICENSE).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Framework DDD dla komend systemowych",
"version": "0.1.4",
"project_urls": null,
"split_keywords": [
"ddd",
" commands",
" framework",
" system"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3935035a0ed21eba843613eda8240c72dc76c393e1826303233a5e2a368d4366",
"md5": "e29d5192f19c6da18da59a53c42bacaf",
"sha256": "7e4f492581c269151aa3a9dedd0e3b9d391b38fa53a6b5189d889f3e0de3dc76"
},
"downloads": -1,
"filename": "mancer-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e29d5192f19c6da18da59a53c42bacaf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 157086,
"upload_time": "2025-08-21T17:21:24",
"upload_time_iso_8601": "2025-08-21T17:21:24.984813Z",
"url": "https://files.pythonhosted.org/packages/39/35/035a0ed21eba843613eda8240c72dc76c393e1826303233a5e2a368d4366/mancer-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "04d53d9e295dbb6cd50477ec3e01ccb962042f87350c36d6d27401d21a003e34",
"md5": "61966fb23382360dd2e2b111d829fe1d",
"sha256": "e488b7f04ce84d5755291c0d062189dd0d6b4b7b2f181212f440b468e1da9e48"
},
"downloads": -1,
"filename": "mancer-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "61966fb23382360dd2e2b111d829fe1d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 115335,
"upload_time": "2025-08-21T17:21:26",
"upload_time_iso_8601": "2025-08-21T17:21:26.807016Z",
"url": "https://files.pythonhosted.org/packages/04/d5/3d9e295dbb6cd50477ec3e01ccb962042f87350c36d6d27401d21a003e34/mancer-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-21 17:21:26",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "mancer"
}
