CLI Command Parser

downloads py_version coverage_badge build_status Blue

CLI Command Parser is a class-based CLI argument parser that defines parameters with descriptors. It provides the tools to quickly and easily get started with basic CLIs, and it scales well to support even very large and complex CLIs while remaining readable and easy to maintain.

The primary goals of this project:

  • Make it easy to define subcommands and actions in an clean and organized manner

  • Allow for inheritance so that common parameters don’t need to be repeated

  • Make it easy to handle common initialization tasks for all actions / subcommands once

  • Reduce the amount of boilerplate code that is necessary for setting up parsing and handling argument values

Example Program

from cli_command_parser import Command, Option, main

class Hello(Command, description='Simple greeting example'):
    name = Option('-n', default='World', help='The person to say hello to')
    count: int = Option('-c', default=1, help='Number of times to repeat the message')

    def main(self):
        for _ in range(self.count):
            print(f'Hello {self.name}!')

if __name__ == '__main__':
    main()

$ hello_world.py --name Bob -c 3
Hello Bob!
Hello Bob!
Hello Bob!

$ hello_world.py -h
usage: hello_world.py [--name NAME] [--count COUNT] [--help]

Simple greeting example

Optional arguments:
  --name NAME, -n NAME        The person to say hello to (default: 'World')
  --count COUNT, -c COUNT     Number of times to repeat the message (default: 1)
  --help, -h                  Show this help message and exit

Installing CLI Command Parser

CLI Command Parser can be installed and updated via pip:

$ pip install -U cli-command-parser

There are no required dependencies. Support for formatting wide characters correctly in help text descriptions can be included by adding wcwidth to your project’s requirements, and/or by installing with optional dependencies:

$ pip install -U cli-command-parser[wcwidth]

Python Version Compatibility

Python versions 3.8 and above are currently supported. The last release of CLI Command Parser that supported 3.7 was 2023-04-30. Support for Python 3.7 officially ended on 2023-06-27.

When using Python 3.8, some additional packages that backport functionality that was added in later Python versions are required for compatibility.

To use the argparse to cli-command-parser conversion script with Python 3.8, there is a dependency on astunparse. If you are using Python 3.9 or above, then astunparse is not necessary because the relevant code was added to the stdlib ast module. If you’re unsure, you can install cli-command-parser with the following command to automatically handle whether that extra dependency is needed or not:

$ pip install -U cli-command-parser[conversion]

User Guide

Building Commands

Getting Started

Introduction to Commands, Parameters, and main functions.

Commands

Explanation of special Command methods and Command inheritance.

Parameters

Introduces each Parameter type and their supported options.

Parameter Groups

How to group Parameters for help text organization or to enforce or prevent Parameter combinations.

Subcommands

How to define, use, and customize subcommands.

Input Types

Custom input types.

Configuring & Documenting Commands

Configuration

Configuration options for parsing, help text formatting, and more.

Documentation

How to generate and customize documentation and help text.

Example Scripts

Automatically generated documentation for the example scripts in this project.

Error Handling

How to define custom error handlers for exceptions that were not caught inside Commands.

Advanced

Advanced Usage

Advanced usage patterns.

Testing Commands

How to unit test Commands.

API Documentation

Lower level API documentation.

Indices and Tables