Getting Started
Simple scripts usually contain a single Command and implement a def main(self):
method in that Command to be
called after arguments are parsed.
Multiple Parameters can be specified as attributes inside the Command to define how CLI arguments will be parsed.
The main()
function that can be imported from cli_command_parser
provides the main entry point for parsing
arguments and running the Command.
Here’s a basic example of a program that uses CLI Command Parser:
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()
After saving the example above as hello_world.py
, we can run it with multiple variations of arguments:
$ hello_world.py
Hello World!
$ hello_world.py -n John
Hello John!
$ hello_world.py --name John
Hello John!
Parameters
Types
Rather than needing to infer the type of parameter that will result from a combination of arguments when defining it, each distinct type has its own Parameter class. Commands may contain any number of Parameters to define how they will parse CLI arguments.
The basic types are Positional, Option, and Flag, but there are others as well, including groups that can be mutually exclusive or dependent.
Names
Even without explicitly specifying the long form for the name
Option in the example above, it was
automatically added based on the name of that Parameter attribute. Following the
DRY principle, the --long
form for Options,
Flags, etc. is generated automatically. To avoid conflicts, short forms are not automatically generated.
The Option(...)
Parameters in the above Hello example would be equivalent to the following
if you were using argparse:
parser.add_argument('--name', '-n', default='World', help='The person to say hello to')
parser.add_argument('--count', '-c', type=int, default=1, help='Number of times to repeat the message')
If an explicit long form is provided, then it will be used instead of the default name-based one. Any number of long and/or short forms may be provided:
example = Option('--foo', '-f', '--FOO')
Entry Points
The example above contains only one Command and uses the main()
function to handle parsing arguments and running
the Command. By default, arguments will be parsed from sys.argv
, but it is also possible to pass a list
of strings as the first argument to parse arguments from that instead.
More advanced programs may contain multiple Commands, and more complex entry points for commands are also supported.
Help Text
Using the Hello World example again, we can see the automatically generated help text:
$ hello_world.py -h
usage: hello_world.py [--name NAME] [--help]
Simple greeting example
Optional arguments:
--name NAME, -n NAME The person to say hello to (default: 'World')
--help, -h Show this help message and exit
The --help
/ -h
option is automatically added to the command, and usage / help text is automatically generated
based on the Command, the file it is in, and the Parameters in the Command.
More information about help text and other ways to document programs (such as generating RST) can be found in Documentation.