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.

Files for rcli, version 0.5.1
Filename, size File type Python version Upload date Hashes
Filename, size rcli-0.5.1-py3-none-any.whl (22.0 kB) File type Wheel Python version 3.8 Upload date Hashes View hashes
Filename, size rcli-0.5.1.tar.gz (29.6 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page