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:

   1. Calling all add_arguments(parser) methods from all super classes, e.g: clinner.mixins.HealthCheckMixin.
   2. 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_.

4. Load settings module from CLINNER_SETTINGS environment variable. More details below.

class Main(args=None, parse_args=True)

add_arguments(parser: argparse.ArgumentParser)

Add to parser all necessary arguments for this Main.

Parameters:parser – Argument parser.

inject()

Add all environment variables defined in all inject methods.

run(*args, command=None, **kwargs)

Run specified command through system arguments.

Arguments that have been parsed properly will be passed through **kwargs. Unknown arguments will be passed as a list of strings through *args.

This method will print a header and the return code.

Parameters:command – Explicit command. Use that command instead of the one passed by shell arguments.

Commands

All commands previously loaded will be available to use by the main class but also there is a another mechanism to load commands using the main class. To do this simply specify a list of fully qualified name commands, e.g: Given a module foo with a command bar:

from clinner.run.main import Main


class FooMain(Main):
    commands = (
        'foo.bar',
    )

This bar command will be assigned as a staticmethod to FooMain class to provide an easy access: FooMain.bar().

In case of overriding a command already imported, the one defined in the class will prevail, e.g:

from clinner.run.main import Main


class FooMain(Main):
    commands = (
        'foo.bar',
    )

    @staticmethod
    @command
    def bar(*args, **kwargs):
        pass  # This command will be the executed instead of foo.bar

Mixins

Clinner provides some useful mixins for main classes that adds different behaviors to these classes.

class HealthCheckMixin

Adds health checking behavior to Main classes. To do that is necessary to define a health_check method responsible of return the current status of the application.

This mixin also adds a new parameter -r, --retry that defines the number of retries done after a failure. These retries uses an exponential backoff to calculate timing.

health_check()

Does a health check.

Returns:True if health check was successful. False otherwise.

run(*args, **kwargs)

Run specified command through system arguments.

Before running the command, a health check function will be called and if result is not successful, the command will be aborted.

Arguments that have been parsed properly will be passed through **kwargs. Unknown arguments will be passed as a list of strings through *args.

This method will print a header and the return code.