Metadata-Version: 1.1
Name: begins
Version: 0.3
Summary: Command line programs for lazy humans
Home-page: http://begins.readthedocs.org
Author: Aaron Iles
Author-email: aaron.iles@gmail.com
License: ASL
Description: ======
        begins
        ======
        
        --------
        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.
        
        |pypi_version| |build_status| |coverage|
        
        -----------
        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 Inex`_ is
        also required.
        
        Both of these dependencies are
        listed in the package configurtion.
        If using `Pip`_ to 
        install *begins* then
        the required dependencies will
        be automatically installed.
        
        ------------
        Installation
        ------------
        
        Currently *begins* is not available
        for downloading from the
        `Python Package Index`_.
        However, if using `Pip`_
        you can install directly
        from `Github`_. ::
        
        $ pip install git+https://github.com/aliles/begins.git
        
        Please note that
        *begins* is still in
        an alpha state so
        the API and behaviour could
        still 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 defering 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()`` deocrates 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 paramter 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 paramater
        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.
        
        ---------------------
        Environment Variables
        ---------------------
        
        Environment variables can
        be used to override the
        default values for
        command line options.
        To use environment variables
        pass a prefix string to
        ``begin.start()`` decorator through
        the ``env_prefix`` paramater::
        
            >>> import begin
            >>> @begin.start(env_prefix='MP_')
            ... def run(name='Arther', quest='Holy Grail', colour='blue', *knights):
            ...     "tis but a scratch!"
        
        In the example above,
        if an environment variable
        ``MP_NAME`` existed,
        it's value would be
        used as the default for
        the ``name`` option.
        The options value can
        still be set by
        explicitly passing a
        new value as
        a command line option.
        
        ---------------------
        Argument type casting
        ---------------------
        
        Command line arguments are
        always passed as strings.
        Sometimes thought it is
        more convenient to
        receive arguments of
        different types.
        For example, this is a
        possible function for
        starting a web application::
        
            >>> @begin.start
            ... def main(host='127.0.0.1', port='8080', debug='False'):
            ...    port = int(port)
            ...    debug = begin.utils.tobool(debug)
            ...    "Run web application"
        
        Having to convert
        the ``port`` argument to
        an integer and
        the ``debug`` argument to
        a boolean is
        additional boilerplate code.
        To avoid this *begins* provides
        the ``begin.convert()`` decorator.
        This decorator accepts functions
        as keyword arguments where
        the argument name matches that of
        the decorator function.
        These functions are used
        to convert the
        types of arguments.
        
        Rewritting the example above using
        the ``begin.convert()`` decorator::
        
            >>> @begin.start
            ... @begin.convert(port=int, debug=begin.utils.tobool)
            ... def main(host='127.0.0.1', port=8080, debug=False):
            ...    "Run web application"
        
        The module ``begin.utils`` contains
        useful functions for
        converting argument types.
        
        ------
        Issues
        ------
        
        Any bug reports or
        freature requests can
        be made using GitHub' `issues system`_.
        
        .. _Github: https://github.com/aliles/begins
        .. _Python: http://python.org
        .. _Python Package Index: https://pypi.python.org/pypi
        .. _Pip: http://www.pip-installer.org
        .. _argparse: https://pypi.python.org/pypi/argparse
        .. _issues system: https://github.com/aliles/begins/issues
        .. _funcsigs: https://pypi.python.org/pypi/funcsigs
        .. _function annotations: http://www.python.org/dev/peps/pep-3107/
        
        .. |build_status| image:: https://secure.travis-ci.org/aliles/begins.png?branch=master
           :target: https://travis-ci.org/aliles/begins
           :alt: Current build status
        
        .. |coverage| image:: https://coveralls.io/repos/aliles/begins/badge.png?branch=master
           :target: https://coveralls.io/r/aliles/begins?branch=master
           :alt: Latest PyPI version
        
        .. |pypi_version| image:: https://pypip.in/v/begins/badge.png
           :target: https://crate.io/packages/begins/
           :alt: Latest PyPI version
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries :: Python Modules
