.. image:: https://travis-ci.org/Lucretiel/autocommand.svg?branch=master
    :target: https://travis-ci.org/Lucretiel/autocommand
.. image:: https://coveralls.io/repos/Lucretiel/autocommand/badge.svg
    :target: https://coveralls.io/r/Lucretiel/autocommand

autocommand
===========

A library to automatically generate and run simple argparse parsers from function signatures.

Installation
------------

Autocommand is installed via pip:

::

    $ pip install autocommand

Usage
-----

Autocommand turns a function into a command-line program. It converts the function's parameter signature into command-line arguments, and automatically runs the function if the module was called as ``__main__``. In effect, it lets your create a smart main function.

.. code:: python

    from autocommand import autocommand

    # This program takes exactly one argument and echos it.
    @autocommand(__name__)
    def echo(thing)
        print(thing)

::

    $ python echo.py hello
    hello
    $ python echo.py -h
    usage: echo [-h] thing

    positional arguments:
      thing

    optional arguments:
      -h, --help  show this help message and exit
    $ python echo.py hello world  # too many arguments
    usage: echo.py [-h] thing
    echo.py: error: unrecognized arguments: world

As you can see, autocommand converts the signature of the function into an argument spec. When you run the file as a program, autocommand collects the command-line arguments and turns them into function arguments. The function is executed with these arguments, and then the program exits with the return value of the function, via ``sys.exit``. Autocommand also automatically creates a usage message, which can be invoked with ``-h`` or ``--help``, and automatically prints an error message when provided with invalid arguments.

Types
~~~~~

You can use a type annotation to give an argument a type. Any type (or in fact any callable) that returns an object when given a string argument can be used, though there are a few special cases that are described later.

.. code:: python

    @autocommand(__name__)
    def net_client(host, port: int):
        ...

Autocommand will catch ``TypeErrors`` raised by the type during argument parsing, so you can supply a callable and do some basic argument validation as well.

Trailing Arguments
~~~~~~~~~~~~~~~~~~

You can add a ``*args`` parameter to your function to give it trailing arguments. The command will collect 0 or more trailing arguments and supply them to `args` as a tuple. If a type annotation is supplied, the type is applied to each argument.

.. code:: python

    #Write the contents of each file, one by one
    @autocommand(__name__)
    def cat(*files):
        for filename in files:
            with open(filename) as file:
                for line in file:
                    print(line.rstrip())

::

    $ python cat.py -h
    usage: ipython [-h] [file [file ...]]

    positional arguments:
      file

    optional arguments:
      -h, --help  show this help message and exit

Options
~~~~~~~

To create ``--option`` switches, just assign a default. Autocommand will automatically create ``--long`` and ``-s``\ hort switches.

.. code:: python

    @autocommand(__name__)
    def do_with_config(argument, config='~/foo.conf'):
        pass

::

    $ python example.py -h
    usage: example.py [-h] [-c CONFIG] argument

    positional arguments:
      argument

    optional arguments:
      -h, --help            show this help message and exit
      -c CONFIG, --config CONFIG

The option's type is automatically deduced from the default, unless one is explicitly given in an annotation:

.. code:: python

    @autocommand(__name__)
    def http_connect(host, port=80):
        print('{}:{}'.format(host, port))

::

    $ python http.py -h
    usage: http.py [-h] [-p PORT] host

    positional arguments:
      host

    optional arguments:
      -h, --help            show this help message and exit
      -p PORT, --port PORT
    $ python http.py localhost
    localhost:80
    $ python http.py localhost -p 8080
    localhost:8080
    $ python http.py localhost -p blah
    usage: http.py [-h] [-p PORT] host
    http.py: error: argument -p/--port: invalid int value: 'blah'

None
````

If an option is given a default value of ``None``, it reads in a value as normal, but supplies ``None`` if the option isn't provided.

Switches
````````

If an argument is given a default value of ``True`` or ``False``, or
given an explicit ``bool`` type, it becomes an option switch.

.. code:: python

    @autocommand(__name__)
    def example(verbose=False, quiet=False):
        pass

::

    $ python example.py -h
    usage: example.py [-h] [-v] [-q]

    optional arguments:
      -h, --help     show this help message and exit
      -v, --verbose
      -q, --quiet

Autocommand attempts to do the "correct thing" in these cases- if the default is ``True``, then supplying the switch makes the argument ``False``; if the type is ``bool`` and the default is some other ``True`` value, then supplying the switch makes the argument ``False``, while not supplying the switch makes the argument the default value.

Autocommand also supports the creation of switch inverters. Pass ``add_nos=True`` to ``autocommand`` to enable this.

.. code:: python

    @autocommand(__name__, add_nos=True)
    def example(verbos=False):
        pass

::

    $ python example.py -h
    usage: ipython [-h] [-v] [--no-verbose]

    optional arguments:
      -h, --help     show this help message and exit
      -v, --verbose
      --no-verbose

Using the `--no-` version of a switch will pass the opposite value in as a function argument. If multiple switches are present, the last one takes precedence.

Files
`````

If the default value is a file object, such as ``sys.stdout``, then autocommand just looks for a string, for a file path. It doesn't do any special checking on the string, though (such as checking if the file exists); it's better to let the client decide how to handle errors in this case. Instead, it provides a special context manager called ``smart_open``, which behaves exactly like ``open`` if a filename or other openable type is provided, but also lets you use already open files:

.. code:: python

    from autocommand import autocommand, smart_open
    import sys

    # Write the contents of stdin, or a file, to stdout
    @autocommand(__name__)
    def write_out(infile=sys.stdin):
        with smart_open(infile) as f:
            for line in f:
                print(line.rstrip())
        # If a file was opened, it is closed here. If it was just stdin, it is untouched.

::

    $ echo "Hello World!" | python write_out.py | tee hello.txt
    Hello World!
    $ python write_out.py --infile hello.txt
    Hello World!

Descriptions and docstrings
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``autocommand`` decorator accepts ``description`` and ``epilog`` kwargs, corresponding to the `description <https://docs.python.org/3/library/argparse.html#description>`_ and `epilog <https://docs.python.org/3/library/argparse.html#epilog>`_ of the ``ArgumentParser``. If no description is given, but the decorated function has a docstring, then it is taken as the ``description`` for the ``ArgumentParser``

.. code:: python

    @autocommand(__name__, epilog='Some extra documentation in the epilog')
    def copy(infile=sys.stdin, outfile=sys.stdout):
        '''
        Copy an the contents of a file (or stdin) to another file (or stdout)
        '''
        with smart_open(infile) as istr:
            with smart_open(outfile, 'w') as ostr:
                for line in istr:
                    ostr.write(line)

::

    $ python copy.py -h
    usage: copy.py [-h] [-i INFILE] [-o OUTFILE]

    Copy an the contents of a file (or stdin) to another file (or stdout)

    optional arguments:
      -h, --help            show this help message and exit
      -i INFILE, --infile INFILE
      -o OUTFILE, --outfile OUTFILE

    Some extra documentation in the epilog
    $ echo "Hello World" | python copy.py --outfile hello.txt
    $ python copy.py --infile hello.txt --outfile hello2.txt
    $ python copy.py --infile hello2.txt
    Hello World

Parameter descriptions
~~~~~~~~~~~~~~~~~~~~~~

You can also attach description text to individual parameters in the annotation. To attach both a type and a description, supply them both in any order in a tuple

.. code:: python

    @autocommand(__name__)
    def copy_net(
        infile: 'The name of the file to send',
        host: 'The host to send the file to',
        port: (int, 'The port to connect to')):

        '''
        Copy a file over raw TCP to a remote destination.
        '''
        # Left as an exercise to the reader

Decorators and wrappers
~~~~~~~~~~~~~~~~~~~~~~~

Autocommand automatically follows wrapper chains created by ``@functools.wraps``. This means that you can apply other wrapping decorators to your main function, and autocommand will still correctly detect the signature.

.. code:: python

    from functools import wraps
    from autocommand import autocommand

    def print_yielded(func):
        '''
        Convert a generator into a function that prints all yielded elements
        '''
        @wraps(func)
        def wrapper(*args, **kwargs):
            for thing in func(*args, **kwargs):
                print(thing)
        return wrapper

    @autocommand(__name__,
        description= 'Print all the values from START to STOP, inclusive, in steps of STEP',
        epilog=      'STOP and STEP default to 1')
    @print_yielded
    def seq(stop, start=1, step=1):
        for i in range(start, stop + 1, step):
            yield i

::

    $ seq.py -h
    usage: seq.py [-h] [-s START] [-S STEP] stop

    Print all the values from START to STOP, inclusive, in steps of STEP

    positional arguments:
      stop

    optional arguments:
      -h, --help            show this help message and exit
      -s START, --start START
      -S STEP, --step STEP

    STOP and STEP default to 1

Even though autocommand is being applied to the ``wrapper`` returned by ``print_yielded``, it still retreives the signature of the underlying ``seq`` function to create the argument parsing.

Custom Parser
~~~~~~~~~~~~~

While autocommand's automatic parser generator is a powerful convenience, it doesn't cover all of the different features that argparse provides. If you need these features, you can provide your own parser as a kwarg to `autocommand`:

.. code:: python

    from argparse import ArgumentParser
    from autocommand import autocommand

    parser = ArgumentParser()
    # autocommand can't do optional positonal parameters
    parser.add_argument('arg', nargs='?')
    # or mutually exclusive options
    group = parser.add_mutually_exclusive_group()
    group.add_argument('-v', '--verbose', action='store_true')
    group.add_argument('-q', '--quiet', action='store_true')

    @autocommand(__name__, parser=parser)
    def main(arg, verbose, quiet):
        print(arg, verbose, quiet)

::

    $ python parser.py -h
    usage: write_file.py [-h] [-v | -q] [arg]

    positional arguments:
      arg

    optional arguments:
      -h, --help     show this help message and exit
      -v, --verbose
      -q, --quiet
    $ python parser.py
    None False False
    $ python parser.py hello
    hello False False
    $ python parser.py -v
    None True False
    $ python parser.py -q
    None False True
    $ python parser.py -vq
    usage: parser.py [-h] [-v | -q] [arg]
    parser.py: error: argument -q/--quiet: not allowed with argument -v/--verbose

Any parser should work fine, so long as each of the parser's arguments has a corresponding parameter in the decorated main function. The order of parameters doesn't matter, as long as they are all present. Note that when using a custom parser, autocommand doesn't modify the parser or the retrieved arguments. This means that no description/epilog will be added, and the function's type annotations and defaults (if present) will be ignored.

Testing and Library use
-----------------------

The decorated function is only called and exited from if the first argument to ``autocommand`` is ``'__main__'`` or ``True``. If it is neither of these values, or no argument is given, then a new main function is created by the decorator. This function has the signature ``main(argv=None)``, and is intended to be called with arguments as if via ``main(sys.argv[1:])``. The function has the attributes ``parser`` and ``main``, which are the generated ``ArgumentParser`` and the original main function that was decorated. This is to facilitate testing and library use of your main. Calling the function triggers a ``parse_args()`` with the supplied arguments, and returns the result of the main function. Note that, while it returns instead of calling ``sys.exit``, the ``parse_args()`` function will raise a ``SystemExit`` in the event of a parsing error or ``-h/--help`` argument.

.. code:: python

    @autocommand()
    def test_prog(arg1, arg2: int, quiet=False, verbose=False):
        if not quiet:
            print(arg1, arg2)
            if verbose:
                print("LOUD NOISES")

        return 0

    print(test_prog(['-v', 'hello', '80']))

::

    $ python test_prog.py
    hello 80
    LOUD NOISES
    0

If the function is called with no arguments, ``sys.argv[1:]`` is used. This is to allow the autocommand function to be used as a setuptools entry point.

Exceptions and limitations
--------------------------

- There are a few possible exceptions that ``autocommand`` can raise. All of them derive from ``autocommand.AutocommandError``, which is a ``TypeError``.

  - If an invalid annotation is given (that is, it isn't a ``type``, ``str``, ``(type, str)``, or ``(str, type)``, an ``AnnotationError`` is raised
  - If the function has a ``**kwargs`` parameter, a ``KWargError`` is raised.
  - If, somehow, the function has a positional-only parameter, a ``PositionalArgError`` is raised. This means that the argument doesn't have a name, which is currently not possible with a plain ``def`` or ``lambda``, though many built-in functions have this kind of parameter.

- There are a few argparse features that are not supported by autocommand.

  - It isn't possible to have an optional positional argument (as opposed to a ``--option``). POSIX thinks this is bad form anyway.
  - It isn't possible to have mutually exclusive arguments or options
  - It isn't possible to have subcommands or subparsers, though I'm working on a few solutions involving classes or nested function definitions to allow this.

Development
-----------

Autocommand cannot be important from the project root; this is to enforce separation of concerns and prevent accidental importing of `setup.py` or tests. To develop, install the project in editable mode:

::

    $ python setup.py develop

This will create a link to the source files in the deployment directory, so that any source changes are reflected when it is imported.
