Command line programs for lazy humans.
- Decorate a function to be your programs starting point.
- Generate command line parser based on function signature.
- Search system environment for option default values.
I write a lot of small programs in Python. These programs often accept a small number of simple command line arguments. Having to write command line parsing code in each of these small programs both breaks my train of thought and greatly increases the volume of code I am writing.
Begins was implemented to remove the boilerplate code from these Python programs. It's not intended to replace the rich command line processing needed for larger applications.
Both of these dependencies are listed in the package configuration. If using Pip to install begins then the required dependencies will be automatically installed.
$ pip install begins
Alternatively, the latest development version can be installed directly from Github.
$ pip install git+https://github.com/aliles/begins.git
Please note that begins is still in an alpha state and therefore the API or behaviour could change.
Setting a programs starting point
begin.start() function can be
used as a function call
or a decorator.
If called as a function
called from the
To do this it inspects
the stack frame of the caller,
This allows the following Python pattern:
>>> if __name__ == '__main__': ... pass
To be replace with:
>>> import begin >>> if begin.start(): ... pass
If used as a decorator
to annotate a function
the function will be called
if defined in the
as determined by inspecting
the current stack frame.
Any definitions that follow
the decorated function
wont be created until
after the function call
a decorator looks like:
>>> import begin >>> @begin.start ... def run(): ... pass
By deferring the execution of the function until after the remainder of the module has loaded ensures the main function doesn't fail if depending on something defined in later code.
Parsing command line options
begin.start() decorates a
function accepts parameters
process the command for
options to pass as
>>> import begin >>> @begin.start ... def run(name='Arthur', quest='Holy Grail', colour='blue', *knights): ... "tis but a scratch!"
The decorated function above will generate the following command line help:
usage: example.py [-h] [-n NAME] [-q QUEST] [-c COLOUR] [knights [knights ...]] tis but a scratch! positional arguments: knights optional arguments: -h, --help show this help message and exit -n NAME, --name NAME (default: Arthur) -q QUEST, --quest QUEST (default: Holy Grail) -c COLOUR, --colour COLOUR (default: blue)
In Python 3, any function annotations for a parameter become the command line option help. For example:
>>> import begin >>> @begin.start # doctest: +SKIP ... def run(name: 'What, is your name?', ... quest: 'What, is your quest?', ... colour: 'What, is your favourite colour?'): ... pass
Will generate command help like:
usage: holygrail_py3.py [-h] -n NAME -q QUEST -c COLOUR optional arguments: -h, --help show this help message and exit -n NAME, --name NAME What, is your name? -q QUEST, --quest QUEST What, is your quest? -c COLOUR, --colour COLOUR What, is your favourite colour?
Command line parsing supports:
- positional arguments
- keyword arguments
- default values
- variable length arguments
Command line parsing
does not support
variable length keyword arguments,
commonly written as
If variable length keyword arguments
are used by
the decorated function
will be raised.
If a parameter does not have a default, failing to pass a value on the command line will cause running the program to print an error and exit.
For programs that have
a large number of options
it may be preferable to
only use long options.
To suppress short options,
False as the
short_args keyword argument to
>>> import begin >>> @begin.start(short_args=False) ... def run(name='Arthur', quest='Holy Grail', colour='blue', *knights): ... "tis but a scratch!"
This program will not
as option names.
Similarity, a large number of
command line options may
be better displayed in
This can be achieved
>>> import begin >>> @begin.start(lexical_order=True) ... def main(charlie=3, alpha=1, beta=2): ... pass
This program will list
the command line options as
instead of the order
in which the function
A walk-through tutorial, the remainder of this guide and API documentation can are all part of the official begins documentation hosted on Read The Docs.
Any bug reports or feature requests can be made using GitHub's issues system.