CliFire 0.1.2

Minimal CLI framework to build Python commands quickly and elegantly.

CliFire

Minimal CLI framework to build Python commands quickly and elegantly.

CliFire is a lightweight Python library designed to simplify the creation of command-line interfaces (CLI). It allows developers to define commands, options, and arguments in a straightforward way, making it easy to build complex CLI applications without the overhead of bigger frameworks.

Key Features

• Two Usage Styles: Define commands using decorators or classes.
• Intuitive Syntax: Focus on writing application logic without worrying about CLI infrastructure.
• Arguments & Options: Flexible parsing with positional arguments and command options.
• Grouped Commands: Organize related commands using a dot-based naming convention.
• Formatted Output: Leverage the Rich library for colorful and styled messages.
• Templates: Generate files using Jinja2 templates.
• Centralized Configuration: Manage configuration via YAML using the Config module.

Installation

Install CliFire using pip:

pip install clifire

Or with Poetry:

poetry add clifire

Quick Start

Create a simple CLI command using decorators. For example, save the following as fire/hello.py:

from clifire import command, out

@command.fire
def hello(cmd, user: str = "", _sudo: bool = False):
    """
    Display a greeting on the console.

    Args:
        user: Name of the user to greet. If empty, the current system user is used.
        _sudo: Run the command with sudo privileges.
    """
    if not user:
        sudo = 'sudo' if _sudo else ''
        user = cmd.app.shell(f"{sudo} whoami").stdout
    out.info(f'Hi {user}!')

Then run:

fire hello Rob

For more details, see our Quick Start Guide.

Documentation

The full documentation is available on GitHub Pages in English and Spanish. It covers topics such as:

• CliFire Basics
• Decorators
• Class-based Commands
• Options and Arguments
• Grouped Commands
• Output and Styling
• Configuration
• Templates
• Changelog
• Contributing

Development

To contribute to CliFire:

1. Fork the repository on GitHub.
2. Clone your fork locally:

   git clone https://github.com/<your-username>/clifire.git
   cd clifire
   

3. Create a new branch for your feature or bug fix:

   git checkout -b feature/my-feature
   

4. Install development dependencies:

   poetry install --with dev
   

5. Run tests to ensure everything works:

   poetry run pytest
   # or to check coverage:
   poetry run coverage run -m pytest && poetry run coverage html
   

6. Update the CHANGELOG.md with your changes.
7. Commit and push your changes, and then create a pull request.

For further contribution details, please see our Contributing Guide.

License

CliFire is released under the MIT License. See the LICENSE file for details.