Why begins?

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 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.

Installation

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

The begin.start() function can be
used as a function call
or a decorator.
If called as a function
it returns True when
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__':
... 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 __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 of begin.start() as
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

If begin.start() decorates a
function accepts parameters
begin.start() will
process the command for
options to pass as
those parameters:

Command 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,
pass False as the
short_args keyword argument to
the begin.start decorator: