Commands

Command Decorator

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.
class command(func=None, command_type=<Type.PYTHON: 'python'>, args=None, parser_opts=None)[source]

Decorator to register the given functions in a register, along with their command line arguments.

How to use

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

@command
def foobar(bar):
    pass

Or specifying the type:

@command(command_type=Type.SHELL)
def foobar(bar):
    return [['cat', 'foobar']]

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'}),
               (('--bar',), {'action': 'store_true', 'help': 'Bar argument stored as True'})),
         parser_opts={'title': 'foobar_command', 'help': 'Help for foobar_command'})
def foobar(*args, **kwargs):
    pass

For last, is possible to decorate functions or class methods:

class Foo:
    @staticmethod
    @command
    def bar():
        pass

Types

Define the type of process to be executed by clinner.run.Main.

Python

Python function executed in a different process. Must implement the function itself.

Shell

List of shell commands executed in different processes. Each command must be a list of splitted command such as returned from shlex.split(). As it can execute more than a single command, a list of lists should be returned.

Bash

Alias for Shell.

Arguments

Command line arguments are defined through args parameter of command decorator. This arguments can be defined using the follow structure:

@command(args=(
    (('positionals',) {'help': 'Positional arguments', 'nargs': '+'}),
    (('-f', '--foo'), {'help': 'Foo argument', 'default': 'foo'}),
    (('--bar',), {'help': 'Bar argument', 'default': 1, 'type': int, 'choices': range(1, 6)}),
))
def cmd(*args, **kwargs):
    pass

Also is possible to define args using a callable that receives the parser:

def add_arguments(parser):
    parser.add_argument('positionals', help='Positional arguments', nargs='+')
    parser.add_argument('-f', '--foo', help='Foo argument', default='foo')
    parser.add_argument('--bar', help='Bar argument', default=1, type=int, choices=range(1, 6))

@command(args=add_arguments)
def cmd(*args, **kwargs):
    pass

Parser options

It is possible to pass options to the command parser, such as title, help… These options should be passed through parser_opts parameter of command decorator:

@command(parser_opts={'help': 'Command doing awesome things!'})
def cmd(*args, **kwargs):
    pass

Register

All commands will be registered in a clinner.command.CommandRegister 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.

class CommandRegister[source]

Register for commands.