This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description

Overview

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.

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.

Requirements

For Python versions earlier than Python 3.3, the funcsigs package from the Python Package Index is required.

For Python version 2.6, the argparse package from the Python Package Index is also required.

Both of these dependencies are listed in the package configuration. If using Pip to install begins then the required dependencies will be automatically installed.

Installation

begins is available for download from the Python Package Index. To install using Pip

$ 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

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:

>>> 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, 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
  • annotations

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:

>>> 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, -q or -c as option names.

Similarity, a large number of command line options may be better displayed in alphabetical order. This can be achieved by passing lexical_order as True:

>>> 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 alpha, beta, charlie instead of the order in which the function accepts them.

Further Reading

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.

Issues

Any bug reports or feature requests can be made using GitHub’ issues system.

Release History

Release History

0.9

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.8

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.7.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.7

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.6

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.5

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.4

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.3

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.2

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
begins-0.9-py2-none-any.whl (27.2 kB) Copy SHA256 Checksum SHA256 2.7 Wheel Aug 2, 2014
begins-0.9.tar.gz (678.2 kB) Copy SHA256 Checksum SHA256 Source Aug 2, 2014

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting