Overview¶

arc is a tool for building declartive, and highly extendable CLI applications for Python ^3.10 based on Python type-hints

arc's features include:

Command line arguments based on Python type hints
Arbitrary command nesting
Automatic --help documentation generation
Dynamic command loading at runtime
Single and multi-command modes

Installation¶

arc can be installed with pip

$ pip install arc-cli

Example¶

To start off, here's a simple example application that can be used to greet someone

hello.py

import arc


@arc.command()
def hello(name: str):
    """My first arc program!"""
    arc.print(f"Hello {name}!")


hello()

Tip

The above example, and all examples in this documentation are complete and should run as-is. Additionally all examples are available in the source repo

$ python hello.py Joseph
Hello Joseph!

Automatic Documentation¶

And a quick demonstration of the documention generation:

$ python hello.py --help
USAGE
    hello.py [-h] [--] name

DESCRIPTION
    My first arc program!

ARGUMENTS
    name

OPTIONS
    --help (-h)  Displays this help message

Pretty cool, huh? arc will pull all of the information that it needs from your function docstrings and parameter definitons.

Configuration¶

arc is easily configurable via the arc.configure() function.

For example, you can set a version string for you application. This will add a --version flag to your application. Additionally you can set a "brand color" which is the primary color used for the documentation.

examples/hello_configuration.py

import arc
from arc import color

arc.configure(
    version="1.0.0",
    brand_color=color.fg.RED,
)


@arc.command()
def hello(name: str):
    """My first arc program!"""
    arc.print(f"Hello {name}!")


hello()

$ python hello_configuration.py --help
USAGE
    hello_configuration.py [-h] [-v] [--] name

DESCRIPTION
    My first arc program!

ARGUMENTS
    name

OPTIONS
    --help (-h)     Displays this help message
    --version (-v)  Displays the app's version number

$ python hello_configuration.py --version
1.0.0

View the reference for details on all the configuration options