A CLI tool to build beautiful command-line interfaces with type validation.
It is as simple as
from piou import Cli, Option
cli = Cli(description='A CLI tool')
@cli.command(cmd='foo', help='Run foo command')
def foo_main(
bar: int = Option(..., help='Bar positional argument (required)'),
baz: str = Option(..., '-b', '--baz', help='Baz keyword argument (required)'),
foo: str = Option(None, '--foo', help='Foo keyword argument'),
):
"""
A longer description on what the function is doing.
You can run it with:
```bash
poetry run python -m piou.test.simple foo 1 -b baz
```
And you are good to go!
"""
pass
if __name__ == '__main__':
cli.run()The output will look like this:
python -m piou.test.simple -h
python -m piou.test.simple foo -h
I could not find a library that provided:
- the same developer experience than FastAPI
- customization of the interface (to build a CLI similar to the one of Poetry)
- type validation / casting
Typer is the closest alternative in terms of experience but lacks the possibility to format the output is a custom way using external libraries (like Rich).
Piou provides all these possibilities and lets you define your own Formatter.
You can install piou with either:
pip install piouconda install piou -c conda-forge
from piou import Cli, Option
cli = Cli(description='A CLI tool')
@cli.command(cmd='foo',
help='Run foo command')
def foo_main(
foo1: int = Option(..., help='Foo arguments'),
foo2: str = Option(..., '-f', '--foo2', help='Foo2 arguments'),
foo3: str = Option(None, '-g', '--foo3', help='Foo3 arguments'),
):
pass
@cli.command(cmd='bar',
help='Run bar command')
def bar_main(
foo1: int = Option(..., help='Foo arguments'),
foo2: str = Option(..., '-f', '--foo2', help='Foo2 arguments'),
foo3: str = Option(None, '-g', '--foo3', help='Foo3 arguments'),
):
pass
if __name__ == '__main__':
cli.run()In this case, foo1 is a positional argument while foo2 and foo3 are keyword arguments.
You can optionally specify global options that will be passed to all commands:
cli = Cli(description='A CLI tool')
cli.add_option('-q', '--quiet', help='Do not output any message')The description can also be extracted from the function docstring. Both functions here return the same description.
@cli.command(cmd='bar', description='Run foo command')
def bar_main():
pass
@cli.command(cmd='bar2')
def bar_2_main():
"""
Run foo command
"""
passA command can also be asynchronous, it will be run automatically using asyncio.run.
@cli.command(cmd='bar', help='Run foo command')
async def bar_main():
passYou can group commands into sub-commands:
from piou import Cli, Option
cli = Cli(description='A CLI tool')
@cli.command(cmd='foo', help='Run foo command')
def foo_main():
pass
sub_cmd = cli.add_sub_parser(cmd='sub', help='A sub command')
sub_cmd.add_option('--test', help='Test mode')
@sub_cmd.command(cmd='bar', help='Run bar command')
def sub_bar_main(**kwargs):
pass
@sub_cmd.command(cmd='foo', help='Run foo command')
def sub_foo_main(
test: bool,
foo1: int = Option(..., help='Foo argument'),
foo2: str = Option(..., '-f', '--foo2', help='Foo2 argument'),
):
pass
if __name__ == '__main__':
cli.run()So when running python run.py sub -h it will output the following:
Sometimes, you want to run a function using the global arguments before running the actual command (for instance
initialize a logger based on the verbose level).
To do so, you use set_options_processor that will receive all the current global options of the CLI.
from piou import Cli
cli = Cli(description='A CLI tool')
cli.add_option('--verbose', help='Increase verbosity')
def processor(verbose: bool):
print(f'Processing {verbose=}')
cli.set_options_processor(processor)You can also use the decorator syntax:
from piou import Cli, Option
cli = Cli(description='A CLI tool')
@cli.processor()
def processor(verbose: bool = Option(False, '--verbose', help='Increase verbosity')):
print(f'Processing {verbose=}')By default, when a processor is set, the global arguments will not be passed downstream. If you still want them to be passed to the functions by setting
cli = Cli(description='A CLI tool', propagate_options=True)or in the case of a sub-command
cli.add_sub_parser(cmd='sub', help='A sub command', propagate_options=True)Sometimes, you want to reuse the options in multiple command and group them into a single output to pass to the command. For instance, you might want to group a connection string parameter to connect to a database. Here is a full example:
from piou import Cli, Option, Derived, Password
import psycopg2
cli = Cli(description='A CLI tool')
def get_pg_conn(
pg_user: str = Option('postgres', '--pg-user'),
pg_pwd: Password = Option('postgres', '--pg-pwd'),
pg_host: str = Option('localhost', '--pg-host'),
pg_port: int = Option(5432, '--pg-port'),
pg_db: str = Option('postgres', '--pg-db')
):
conn = psycopg2.connect(dbname=pg_db, user=pg_user, password=pg_pwd,
host=pg_host, port=pg_port)
return conn
@cli.command(help='Run foo command')
def foo(pg_conn=Derived(get_pg_conn)):
...
@cli.command(help='Run bar command')
def bar(pg_conn=Derived(get_pg_conn)):
...You can also pass dynamic derived functions to avoid duplicating the derived logic:
import os
from typing import Literal
from piou import Cli, Option, Derived
cli = Cli(description='A CLI tool')
def get_pg_url_dynamic(source: Literal['db1', 'db2']):
_source_upper = source.upper()
_host_arg = f'--host-{source}'
_db_arg = f'--{source}'
def _derived(
# We need to specify the `arg_name` here
pg_host: str = Option(os.getenv(f'PG_HOST_{_source_upper}', 'localhost'),
_host_arg, arg_name=_host_arg),
pg_db: str = Option(os.getenv(f'PG_DB_{_source_upper}', source),
_db_arg, arg_name=_db_arg),
):
return f'postgresql://postgres:postgres@{pg_host}:5432/{pg_db}'
return _derived
@cli.command(help='Run dynamic command')
def dynamic(url_1: str = Derived(get_pg_url_dynamic('db1')),
url_2: str = Derived(get_pg_url_dynamic('db2'))):
...So that the output will look like this:
If you want to get the command name and arguments information that are passed to it (in case of general purpose
debugging for instance), you can pass on_cmd_run to the CLI.
from piou import Cli, Option, CommandMeta, Derived
def on_cmd_run(meta: CommandMeta):
pass
cli = Cli(description='A CLI tool',
on_cmd_run=on_cmd_run)
def processor(a: int = Option(1, '-a'),
b: int = Option(2, '-b')):
return a + b
@cli.command()
def test(
value: int = Derived(processor),
bar: str = Option(None, '--bar')
):
passIn this case, meta will be equal to:
CommandMeta(cmd_name='test',
fn_args={'bar': 'bar', 'value': 5},
cmd_args={'a': 3, 'b': 2, 'bar': 'bar'})You can customize the help and the different errors displayed by the CLI by passing a Formatter. The default one is the Rich formatter based on the Rich package:
cmd_color: set the color of the command in the helpoption_color: set the color of the positional / keyword arguments in the helpdefault_color: set the color of the default values in the helpshow_default: show the default values if the keyword arguments (if available)
You can create your own Formatter by subclassing the Formatter class (see
the Rich formatter
for example).
The Rich Formatter supports the Password type that will hide the default value when printing help.
For instance:
from piou import Password, Option
def test(pg_pwd: Password = Option('postgres', '--pg-pwd')):
...You can try a more complete example by running python -m piou.test -h
If you are migrating code from argparse to piou here are some differences:
add_argument('--pick', choices=['foo', 'bar'])
can be replaced with the following:
pick: Literal['foo', 'bar'] = Option(None, '--pick')pick: Literal['foo'] | Literal['bar'] = Option(None, '--pick')pick: str = Option(None, '--pick', choices=['foo', 'bar'])
Notes:
- You can disable the case sensitivity by passing
Option(None, '--pick', case_sentitive=False) - Specifying both a
Literaltype andchoiceswill raise an error.
add_argument('--verbose', action='store_true')
can be replaced with
verbose: bool = Option(False, '--verbose')