Metadata-Version: 2.4
Name: toolr
Version: 0.11.1
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
Classifier: License :: OSI Approved :: Apache Software License
Requires-Dist: msgspec>=0.19.0
Requires-Dist: rich-argparse>=1.7.0
License-File: LICENSE
Summary: In-project CLI tooling support
Author-email: Pedro Algarvio <pedro@algarvio.me>
Requires-Python: >=3.11, <3.15
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/s0undt3ch/ToolR/blob/main/CHANGELOG.md
Project-URL: Documentation, https://toolr.readthedocs.io
Project-URL: Issues, https://github.com/s0undt3ch/ToolR/issues
Project-URL: Repository, https://github.com/s0undt3ch/ToolR

<h1 align="center">
  <img width="240px" src="https://raw.githubusercontent.com/s0undt3ch/Toolr/main/docs/imgs/toolr.png" alt="ToolR - AI Generated Logo">
</h1>

<h2 align="center">
  <em>In-project CLI tooling support</em>
</h2>

<p align="center">
  <em>Pronounced <tt>/ˈtuːlər/</tt> (tool-er)</em>
</p>

ToolR is a tool similar to [invoke](https://www.pyinvoke.org/) and the next generation of [python-tools-scripts](https://github.com/saltstack/python-tools-scripts).

The goal is to quickly enable projects to write a Python module under the project's `tools/` sub-directory and it automatically becomes a sub command to the `toolr` CLI.

## Key Features

### Automatic Command Discovery

ToolR automatically discovers and registers commands from your project's `tools/` directory, making it easy to organize and maintain your project's CLI tools.

### Simple Command Definition

Define commands using simple Python functions with type hints. ToolR automatically generates argument parsing based on your function signatures.

### Nested Command Groups

Organize commands into logical groups and subgroups using dot notation, providing a clean and intuitive CLI structure.

### Rich Help System

Built-in support for rich text formatting and automatic help generation from docstrings and type annotations.

### Third-Party Command Support

Extend ToolR's functionality by installing packages that provide additional commands through Python entry points.

## Quick Start

1. **Install ToolR**:

   ```bash
   python -m pip install toolr
   ```

2. **Create a tools package** in your project root:

   ```bash
   mkdir tools
   touch tools/__init__.py
   ```

3. **Write your first command** in `tools/example.py`:

   ```python
   from toolr import Context, command_group

   group = command_group("example", "Example Commands", "Example command group")

   @group.command
   def hello(ctx: Context, name: str = "World"):
       """Say hello to someone.

       Args:
         name: The name to say hello to.
       """
       ctx.print(f"Hello, {name}!")
   ```

4. **Run your command**:

   ```bash
   toolr example hello --name Alice
   ```

## Advanced Usage

### Third-Party Commands

ToolR supports 3rd-party commands from installable Python packages. Create packages that extend ToolR's functionality by defining commands and registering them as entry points.

See the [Advanced Topics section](https://s0undt3ch.github.io/ToolR/usage/#advanced-topics) in the documentation for detailed information about creating 3rd-party command packages.

## Testing and Security

ToolR includes comprehensive testing with a focus on security and robustness:

### Property-Based Testing (Fuzzing)

ToolR uses [Hypothesis](https://hypothesis.works/) for property-based testing to automatically discover edge cases and potential vulnerabilities.
Fuzzing tests are integrated into the regular test suite:

```bash
# Run all tests (including fuzzing tests)
uv run pytest

# Run only fuzzing tests
uv run pytest -k "test_fuzz"

# Run with coverage
uv run coverage run -m pytest -ra -s -v
```

### Security Testing Features

- **Automated Fuzzing**: Property-based tests that generate thousands of test cases
- **Unicode Edge Cases**: Comprehensive testing of text processing with various encodings
- **Malformed Input Handling**: Tests ensure graceful handling of invalid input

The integrated fuzzing tests help ensure ToolR can safely handle malformed input, unusual Unicode sequences, and other edge cases that might cause crashes or security vulnerabilities.

## Contributing

We welcome contributions from the community! ToolR is an open-source project and we appreciate:

- 🐛 Bug reports and fixes
- ✨ Feature requests and implementations
- 📖 Documentation improvements
- 🧪 Test coverage enhancements
- 💡 Ideas and suggestions

Please read our [Contributing Guide](CONTRIBUTING.md) for:

- Setting up your development environment
- Coding standards and best practices
- Pull request process
- Commit message conventions
- Testing guidelines

## License

ToolR is licensed under the [Apache License 2.0](LICENSE).

