Metadata-Version: 2.0
Name: clinner
Version: 0.2.0
Summary: Command Line Interface builder that helps creating an entry point for your application.
Home-page: https://github.com/PeRDy/Clinner
Author: José Antonio Perdiguero López
Author-email: perdy.hh@gmail.com
License: GPLv3
Download-URL: https://github.com/PeRDy/Clinner
Keywords: python command cli interface run script
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: colorama
Requires-Dist: colorlog
Requires-Dist: requests
Provides-Extra: dev
Requires-Dist: bumpversion; extra == 'dev'
Requires-Dist: colorama; extra == 'dev'
Requires-Dist: colorlog; extra == 'dev'
Requires-Dist: coverage; extra == 'dev'
Requires-Dist: nose; extra == 'dev'
Requires-Dist: pip; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: prospector; extra == 'dev'
Requires-Dist: requests; extra == 'dev'
Requires-Dist: setuptools; extra == 'dev'
Requires-Dist: tox; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Requires-Dist: wheel; extra == 'dev'
Provides-Extra: test
Requires-Dist: colorama; extra == 'test'
Requires-Dist: colorlog; extra == 'test'
Requires-Dist: coverage; extra == 'test'
Requires-Dist: nose; extra == 'test'
Requires-Dist: prospector; extra == 'test'
Requires-Dist: requests; extra == 'test'
Requires-Dist: tox; extra == 'test'

=======
Clinner
=======

:Version: 0.2.0
:Status: Production/Stable
:Author: José Antonio Perdiguero López

Command Line Interface builder that helps creating an entry point for your application.


Quick start
===========

1. Install this package using pip:

.. code:: bash

    pip install clinner

2. Create a command

.. code:: python

    from clinner.command import command

    @command
    def foo(*args, **kwargs):
        return True

3. Create a main file:

.. code:: python

    from clinner.run.main import Main

    if __name__ == '__main__':
        sys.exit(Main().run())

Commands
========
Commands are declared using a decorator to register given functions. Commands are functions with the follow parameters:

    func
        Function that will be called when command would be executed.

    command_type
        Type of the command, could be a *bash* or *python* command.

    args
        Parser arguments for this command.

    parser_opts
        Command subparser's keywords, such as description.

This decorator allows to be used as a common decorator without arguments, where default type (*python*) will be used:

.. code:: python
    @command
    def foobar(bar):
        pass

Or specifying the type:

.. code:: python
    @command(command_type=Type.python)
    def foobar(bar):
        pass

But also is possible to provide command line arguments, as expected by argparse.ArgumentParser.add_argument:

.. code:: python
    @command(args=((('-f', '--foo'), {'help': 'Foo argument that does nothing'}),                   # Command argument
                   (('--bar',), {'action': 'store_true', 'help': 'Bar argument stored as True'})),  # Another argument
             parser_opts={'title': 'foobar_command', 'help': 'Help for foobar_command'})            # Parser parameters
    def foobar(*args, **kwargs):
        pass

All commands will be registered in a command register that can be accessed through ``command.register``. Each entry in
this register is a dictionary with the fields declared at the beginning of this section.

Main
====

A main class is defined to ease the creation of command line applications. This class follows the process:

1. Create a parser using ``argparse.ArgumentParser`` for the application:

    a) Calling all ``add_arguments(parser)`` methods from all super classes, e.g: ``clinner.mixins.HealthCheckMixin``.
    b) Addding a subparser for each command with their specific arguments.

2. Parse arguments using the argument parser created previously.

3. Load settings module from **CLINNER_SETTINGS** environment variable. More details below.

4. Inject variables into environment calling all super classes methods whose name starts with ``inject_``. Again, e.g: ``clinner.mixins.VaultMixin``.

Settings
========

Clinner settings can be specified through **CLINNER_SETTINGS** environment variable or using ``-s`` or ``--settings``
command line flags during invocation. The format to specify settings module or class should be either ``package.module``
or ``package.module:Class``.

Default Arguments
-----------------

Default arguments for commands. Let a command ``foo`` declared:

.. code:: python
    default_args = {
        'foo': ['-v', '--bar', 'foobar'],
    }

Vault
-----

Vault arguments to retrieve secrets from this service and inject them as environment variables:

.. code:: python
    vault = {
        'url': 'http://vaulturl',
        'secrets_path': 'vault_secrets_path_to_retrieve',
        'app_id_path': '/path/to/app_id_file',
        'user_id_path': '/path/to/user_id_file',
    }

Example
=======

Full code example:

.. code:: python
    import os
    import shlex
    import sys

    from clinner.command import command, Type as CommandType
    from clinner.run.main import Main


    @command(command_type=CommandType.bash
             args=(('-i', '--input'),
                   ('-o', '--output')))
    def foo(*args, **kwargs):
        """List of foo commands"""
        ls_cmd = shlex.split('ls')
        wc_cmd = shlex.split('wc')
        wc_cmd += [kwargs['input'], kwargs['output']]

        return [ls_cmd, wc_cmd]


    @command(command_type=CommandType.python)
    def bar(*args, **kwargs):
        """Do a bar."""
        return True


    if __name__ == '__main__':
        sys.exit(Main().run())


