Piou
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(
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()
The output will look like this:
Install
You can install piou with either:
pip install piouconda install piou -c conda-forge
Features
Commands
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 foo 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 help can also be extracted from the function docstring, both functions here have the same one.
@cli.command(cmd='bar', help='Run foo command')
def bar_main():
pass
@cli.command(cmd='bar2')
def bar_2_main():
"""
Run foo command
"""
pass
Sub-commands
You can group commands into sub-commands:
from piou import Cli, Option
cli = Cli(description='A CLI tool')
sub_cmd = cli.add_sub_parser(cmd='sub', description='A sub command')
sub_cmd.add_option('--dry-run', help='Run in dry run mode')
@sub_cmd.command(cmd='foo', help='Run baz command')
def baz_bar_main(**kwargs):
pass
@sub_cmd.command(cmd='bar', help='Run toto command')
def toto_main(
foo1: int = Option(..., help='Foo arguments'),
foo2: str = Option(..., '-f', '--foo2', help='Foo2 arguments'),
):
pass
if __name__ == '__main__':
cli.run()
Options processor
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)
Complete example
Here is a more complete example that you can try by running python -m piou.test
from piou import Cli, Option
cli = Cli(description='A CLI tool')
cli.add_option('-q', '--quiet', help='Do not output any message')
cli.add_option('--verbose', help='Increase verbosity')
@cli.command(cmd='foo',
help='Run foo command')
def foo_main(
quiet: bool,
verbose: bool,
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(**kwargs):
pass
sub_cmd = cli.add_sub_parser(cmd='sub', description='A sub command')
sub_cmd.add_option('--test', help='Test mode')
@sub_cmd.command(cmd='bar', help='Run baz command')
def baz_bar_main(
**kwargs
):
pass
@sub_cmd.command(cmd='toto', help='Run toto command')
def toto_main(
test: bool,
quiet: bool,
verbose: bool,
foo1: int = Option(..., help='Foo arguments'),
foo2: str = Option(..., '-f', '--foo2', help='Foo2 arguments'),
):
pass
if __name__ == '__main__':
cli.run()
8.1k Jan 4, 2023
2 Dec 22, 2022
1.1k Dec 31, 2022
22 Jan 3, 2023
984 Jan 2, 2023
249 Jan 2, 2023
17 Dec 11, 2022
23.6k Dec 31, 2022
39 Oct 20, 2022
30 Nov 8, 2022
2 Apr 4, 2022
14 Sep 11, 2022
165 Dec 21, 2022
119 Dec 27, 2022
34 Jan 5, 2023
31 Oct 21, 2022
12.1k Jan 5, 2023
123 Nov 12, 2022
10.1k Jan 02, 2023
0 Jun 19, 2022
1.7k Jan 02, 2023
64 Dec 27, 2022
41.4k Jan 02, 2023
7.7k Dec 30, 2022
82 Dec 28, 2022
13.3k Dec 31, 2022
7 Aug 09, 2022
1 Aug 14, 2022
7 Dec 01, 2021
1.4k Jan 07, 2023
1.1k Jan 08, 2023
3.2k Jan 09, 2023
63 Nov 12, 2022