Mainline helpers

delfick_project provides an App class that helps with some of the plumbing involved in making a cli application.

To use, define a subclass of App, fill out atleast execute and use the main classmethod on it as the entry point to your application:

classmethod App.main(argv=None, **execute_args)

Instantiates this class and calls the mainline

Usage is intended to be:

from delfick_project.app import App

class MyApp(App):
    def execute(self, args_obj, args_dict, extra_args, logging_handler, **kwargs):
        print("My wonderful program goes here!")

main = MyApp.main

The class is as follows:

class delfick_project.app.App

VERSION = <class 'delfick_project.app.Ignore'>

The version of your application, best way is to define this somewhere and import it into your mainline and setup.py from that location

CliParserKls

The class to use for our CliParser

logging_handler_file

The file to log output to (default is stderr)

cli_categories = None

self.execute is passed a dictionary args_dict which is from looking at the args_obj object returned by argparse

This option will break up arguments into hierarchies based on the name of the argument.

For example:

cli_categories = ['app']

and we have arguments for [silent, verbose, debug, app_config, app_option1, app_option2]

Then args_dict will be:

{ "app":
    { "config": "value"
    , "option1": "value"
    , "option2": "value"
    }
, "silent": "value"
, "verbose": "value"
, "debug": "value"
}

cli_description = 'My amazing app'

The description to give at the top of --help output

cli_environment_defaults = None

A map of environment variables to --argument that you want to map

For example:

cli_environment_defaults = {"APP_CONFIG": "--config"}

Items may also be a tuple of (replacement, default)

For example, {"APP_CONFIG": ("--config", "./config.yml")}

Which means defaults["--config"] == {'default': "./config.yml"} if APP_CONFIG isn’t in the environment.

cli_positional_replacements = None

A list mapping positional arguments to --arguments

For example:

cli_positional_replacements = ['--environment', '--stack'] Will mean the first positional argument becomes the value for --environment and the second positional becomes the value for --stack

Note for this to work, you must do something like:

def setup_other_args(self, parser, defaults):
    parser.add_argument('--environment'
        , help = "the environment!"
        , **defaults['--environment']
        )

Items in positional_replacements may also be a tuple of (replacement, default)

For example:

cli_positional_replacements = [('--task', 'list_tasks')]

will mean the first positional argument becomes the value for --task

But if it’s not specified, then defaults['--task'] == {"default": "list_tasks"}

issue_tracker_link = None

A link to where users can go to post issues

It is used when we get an unexpected exception.

Hooks

execute(args_obj, args_dict, extra_args, logging_handler, **kwargs)

Hook for executing the application itself

args_obj

The object from argparse.parse_args

args_dict

The options for args_obj as a dictionary

extra_args

A string of everything specified after a -- on the cli.

logging_handler

The logging handler created by setup_logging

kwargs

Extra keyword arguments passed down from the mainline.

setup_other_logging(args_obj, verbose=False, silent=False, debug=False)

Hook for setting up any other logging configuration

For example:

def setup_other_logging(self, args_obj, verbose, silent, debug):
    logging.getLogger("requests").setLevel([logging.CRITICAL, logging.ERROR][verbose or debug])
    logging.getLogger("paramiko.transport").setLevel([logging.CRITICAL, logging.ERROR][verbose or debug])

specify_other_args(parser, defaults)

Hook for adding more arguments to the argparse Parser

For example:

def specify_other_args(self, parser, defaults):
    parser.add_argument("--special"
        , help = "taste the rainbow"
        , action = "store_true"
        )

exception_handler(exc_info, args_obj, args_dict, extra_args)

Handler for doing things like bugsnag

Customize

setup_logging_theme(handler, colors='light')

Setup a logging theme, the two options for colors is light and dark

Note that nothing calls this method by default

Default cli arguments

--verbose --silent --debug

These control the level of logging in your application. Note that you may only specify one of these three.

--silent means Errors only. --verbose and --debug do the same thing and just means we get DEBUG logs as well.

If none of these three are specified then you’ll get INFO and above logs.

Logging options

There are some options that are passed into setup_logging()

• --logging-program

• --tcp-logging-address

• --udp-logging-address

• --syslog-address

• --json-console-logs

--version

Print out the version and quit

Setting silent by default

If you want --silent to be default then you can set silent_by_default_environ_name to be the name of a special environment variable that when set to “1” will mean we have an --unsilent instead of --silent.

By default it will recognise DELFICK_APP_SILENT_BY_DEFAULT

You may turn this off altogether by setting that property to None