Metadata-Version: 1.1
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
Description: =======
        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())
        
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
