Skip to main content

A library for rapidly creating command-line tools.

Project description

PyPI Python Versions Build Status Coverage Status Code Quality

Rapidly create full-featured command line interfaces with help, subcommand dispatch, and validation.

rcli uses docopt to give you the control over your usage messages that you want, but adds functionality such as automatic subcommand dispatching, usage string wrapping, internationalization, and parameter validation.

Installation

Install it using pip:

pip install rcli

Features

  • Automatic creation of console scripts and entry points based on usage strings.

  • Argument parsing based on usage string.

  • Usage string wrapping.

  • Command line arguments are normalized into python function parameters.

  • Validation of command line arguments using PEP 484 type hints.

  • Logging with multiple levels and crash log generation.

  • Color coded logging based on log level.

  • Extensible subcommand generation based on entry point groups.

Upcoming Features

  • Automatic generation of bash and zsh autocompletion scripts.

  • Internationalization of usage strings.

Basic Usage

To use rcli, add rcli to your setup_requires argument in your setup.py and set the autodetect_commands parameter to True.

from setuptools import setup
setup(
    ...,
    install_requires=['rcli'],
    setup_requires=['rcli'],
    autodetect_commands=True,
    ...,
)

In your code, create a function with a usage string as its docstring and type hint annotations for validation.

def repeat(message: str, num_times: int):
    """Usage: repeat <message> [--num-times <num>]

    Arguments:
        message  A message to print to the console.

    Options:
        -n, --num-times <num>  The number of times to print the message [default: 1].
    """
    for i in range(num_times):
        print(message)

Once your package is installed, a new console script repeat will be automatically generated that will validate and normalize your parameters and call your function.

Subcommand Dispatch

To generate a git-style command line interface with subcommand dispatching, you only need to create your subcommand functions and your primary command will be automatically generated for you.

def roar():
    """Usage: cat-sounds roar"""
    print('ROAR!')

def meow():
    """Usage: cat-sounds meow"""
    print('Meow!')

This automatically generates the command cat-sounds with the following help message:

Usage:
  cat-sounds [--help] [--version] [--log-level <level> | --debug | --verbose]
             <command> [<args>...]

Options:
  -h, --help           Display this help message and exit.
  -V, --version        Display the version and exit.
  -d, --debug          Set the log level to DEBUG.
  -v, --verbose        Set the log level to INFO.
  --log-level <level>  Set the log level to one of DEBUG, INFO, WARN, or ERROR.

'cat-sounds help -a' lists all available subcommands.
See 'cat-sounds help <command>' for more information on a specific command.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

rcli-0.4.0.tar.gz (26.6 kB view hashes)

Uploaded Source

Built Distribution

rcli-0.4.0-py3-none-any.whl (23.6 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page