Package: begins
OverviewCommand line programs forlazyhumans.Decorate a function to be your programs starting point.Generate command line parser based on function signature.Search system environment for option default values.Why begins?I write a lot of
small programs inPython.
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 writting.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.RequirementsFor Python versions earlier
than Python 3.3,
thefuncsigspackage from thePython Package Indexis
required.For Python version 2.6,
theargparsepackage from thePython Package Indexis
also required.Both of these dependencies are
listed in the package configuration.
If usingPipto
installbeginsthen
the required dependencies will
be automatically installed.Installationbeginsis available
for download from
thePython Package Index.
To install usingPip$ pip install beginsAlternatively, the latest
development version can be
installed directly
fromGithub.$ pip install git+https://github.com/aliles/begins.gitPlease note thatbeginsis still in
an alpha state
and therefore
the API or behaviour
could change.Setting a programs starting pointThebegin.start()function can be
used as a function call
or a decorator.
If called as a function
it returnsTruewhen
called from the__main__module.
To do this it inspects
the stack frame of the caller,
checking the__name__global.This allows the following Python pattern:>>> if __name__ == '__main__':
...     passTo be replace with:>>> import begin
>>> if begin.start():
...    passIf used as a decorator
to annotate a function
the function will be called
if defined in the__main__module
as determined by inspecting
the current stack frame.
Any definitions that follow
the decorated function
wont be created until
after the function call
is complete.Usage ofbegin.start()as
a decorator looks like:>>> import begin
>>> @begin.start
... def run():
...     passBy 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 optionsIfbegin.start()decorates a
function accepts parametersbegin.start()will
process the command for
options to pass as
those parameters:>>> import begin
>>> @begin.start
... def run(name='Arther', 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: Arther)
  -q QUEST, --quest QUEST
                        (default: Holy Grail)
  -c COLOUR, --colour COLOUR
                        (default: blue)In Python3, anyfunction annotationsfor 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?'):
...     passWill 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 argumentskeyword argumentsdefault valuesvariable length argumentsannotationsCommand line parsing
does not support
variable length keyword arguments,
commonly written as**kwargs.
If variable length keyword arguments
are used by
the decorated function
an exception
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,
passFalseas theshort_argskeyword argument to
thebegin.startdecorator:>>> import begin
>>> @begin.start(short_args=False)
... def run(name='Arther', quest='Holy Grail', colour='blue', *knights):
...     "tis but a scratch!"This program will not
accept-n,-qor-cas option names.Similarity, a large number of
command line options may
be better displayed in
alphabetical order.
This can be achieved
by passinglexical_orderasTrue:>>> import begin
>>> @begin.start(lexical_order=True)
... def main(charlie=3, alpha=1, beta=2):
...     passThis program will list
the command line options asalpha,beta,charlieinstead of the order
in which the function
accepts them.Further ReadingA walk-through tutorial,
the remainder of this guide
and API documentation can
are all part of the
officialbeginsdocumentation
hosted onRead The Docs.IssuesAny bug reports or
feature requests can
be made using GitHub’issues system.