In-project CLI tooling support

Pronounced /ˈtuːlər/ (tool-er)

ToolR is a tool similar to invoke and the next generation of 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:

   python -m pip install toolr

2. Create a tools package in your project root:

   mkdir tools
   touch tools/__init__.py

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

   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:

   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 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 for property-based testing to automatically discover edge cases and potential vulnerabilities. Fuzzing tests are integrated into the regular test suite:

# 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 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.