Skip to main content

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

Project description


Build Status codecov PyPI version

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

Clinner is a library that provides some useful tools to create command line interfaces for your application

Check Clinner docs.


Can define commands in multiple way:

  • List of shell commands such as ["docker build", "docker push"].
  • Python functions.
  • Python async functions.

Clinner provides a set of commands ready to use like:

  • Black.
  • Flake8.
  • Isort.
  • Nosetest.
  • Prospector.
  • Pytest.
  • Sphinx.
  • Tox.

Hooks for injecting variables or add global arguments to your script.

Quick start

Install this package using pip:

pip install clinner

Create a command

from clinner.command import command

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

Create a main file:

from import Main

if __name__ == '__main__':


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

  1. func: Function that will be called when command would be executed.
  2. command_type: Type of the command, could be a bash or python command.
  3. args: Parser arguments for this command.
  4. 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:

def foobar(*args, **kwargs):

Or specifying the type:

def foobar(*args, **kwargs):

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

@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):

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.

Shell command

Example of running ls -la shell command.

def lsla(*args, **kwargs):
    return [shlex.split("ls -la")]

Python function

Run a python function.

def foo(*args, **kwargs):
    return "foo"

Python async function

Run a python async function.

async def bar(*args, **kwargs):
    await asyncio.sleep(1)
    return "bar"


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. Inject variables into environment calling all super classes methods whose name starts with inject_.


Some Clinner examples.

Simple Main

Example of a simple main with two defined commands foo and bar.

#!/usr/bin/env python
import shlex
import sys

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

         args=(('-i', '--input'),
               ('-o', '--output')),
         parser_opts={'help': 'Foo command'})
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]

         parser_opts={'help': 'Bar command'})
def bar(*args, **kwargs):
    """Do a bar."""
    return True

if __name__ == '__main__':

Builder Main

Example of main module with build utilities such as unit tests, lint, sphinx doc, tox and dist packaging:

#!/usr/bin/env python
import sys

from import Main

class Build(Main):
    commands = (

if __name__ == '__main__':

Check Clinner docs to see more advanced examples.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for clinner, version 1.12.3
Filename, size File type Python version Upload date Hashes
Filename, size clinner-1.12.3.tar.gz (26.4 kB) File type Source Python version None Upload date Hashes View
Filename, size clinner-1.12.3-py3-none-any.whl (75.4 kB) File type Wheel Python version py3 Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page