pillar.application

Application

Application(argv: Optional[List[str]] = None)

Bases: LoggingMixin

Base class for running applications.

Child classes should override the self.main method with their application logic.

Some attributes should be set on the class while others will be computed and set on the instance. All attributes that are set on the class have default value and are optional. They are tagged as (class) below.

Important: the types in the Attributes table below represent the type on the instance, some of these (e.g. name) shadow the ones set on the class (on purpose).

Attributes:

Name	Type	Description
name	str	(class) name of application - used in logging.
application_name	str	(class) argparse prog name.
epilog	Optional[str]	(class) argparse help text epilog (e.g. copyright info).
version	Optional[str]	(class) version of application - used in argparse help text.
logging_manifest	LoggingManifest	(class) configuration of application's logging.
config_args_enabled	bool	(class) enable collecting config from args.
config_required	bool	(class) providing a config file via args is mandatory.
default_config	Dict[str, Any]	(class) default config of the application
config_loader_class	Type[ConfigLoader]	(class) ConfigLoader to use with the application.
logger	Logger	logger of application
log_level	int	computed logging level
args	Namespace	parsed arguments from argparse
config_loader	ConfigLoader	the ConfigLoader of the application.
config	Dict[str, Any]	the config_loader.config dict.

Parameters:

Name	Type	Description	Default
argv	Optional[List[str]]	arguments to pass to this application. If None will collect from sys.argv instead.	None

critical

critical(msg: str, *args, **kwargs) -> None

Log a CRITICAL message

Something is on fire. We somehow caught it but we probably need to exit now. If we keep going more things may catch on fire.

In a larger system, someone is probably going to get paged over this. An end user is definitely going to get an error message, probably not even a useful one, just a HTTP 500.

debug

debug(msg: str, *args, **kwargs) -> None

Log a DEBUG message

Basic debug messages

error

error(msg: str, *args, **kwargs) -> None

Log an ERROR message

Something bad has happened but we caught it. We might be able to continue, but other things might start breaking. We can probably still safely exit.

In a larger system, this will likely cause a gentle alert to be placed somewhere. An end user might receive a useful error message (like a HTTP 4xx 5xx).

get_argument_parser

get_argument_parser() -> argparse.ArgumentParser

Get the argument parser for this application.

To add your own arguments you should override this method and call super().get_argument_parser().

get_logger classmethod

get_logger(prefix: str = '') -> logging.Logger

Get a logging.Logger for this class

Parameters:

Name	Type	Description	Default
prefix	str	optional prefix for the logger name	''

info

info(msg: str, *args, **kwargs) -> None

Log an INFO message

Print something to the screen/logfile so we know what is happening

main

main() -> Optional[int]

Main application entrypoint.

Child classes MUST implement this method.

Returns:

Type	Description
Optional[int]	An integer exit code. None will be converted to 0 during application exit.

run

run(*, prevent_exit: bool = False) -> int

Run this application until completion.

Parameters:

Name	Type	Description	Default
prevent_exit	bool	Do not call sys.exit and instead allow the method to return.	False

Returns:

Type	Description
int	the exit_code that would have been passed to sys.exit

setup

setup(*, suppress_warning: bool = False) -> None

Prepare the application to be run

In no particular order, this will:

• Setup Logging
• Parse arguments
• Load configuration

Once called the following instance attributes will be populated:

• self.args
• self.config
• self.config_loader
• self.log_level

Generally you will not need to call this method as it is called during self.run.

This method may only be called once per an instance. If it is called multiple times, subsequent calls will have no effect and a RuntimeWarning will be emited.

If this method is overridden in a child class, it should call super().setup() or otherwise set self._setup_called to True to indicate the the application has been correctly setup.

Parameters:

Name	Type	Description	Default
suppress_warning	bool	Suppress the RuntimeWarning if this method is called multiple times.	False

vdebug

vdebug(msg: str, *args, **kwargs) -> None

Log a Verbose Debug (VDEBUG) message.

More than debug, less than everything.

vvdebug

vvdebug(msg: str, *args, **kwargs) -> None

Log a Very Verbose Debug (VVDEBUG) message.

When you're tired of finding the bug and want to log everything.

warning

warning(msg: str, *args, **kwargs) -> None

Log a WARNING message

Something is wrong but we likely can recover or skip it without issue.

In a larger system this will likely just go to centralised logging.

LoggingManifest

Simplified configuration of an Application's logging.

Important:

Be careful when modifying these options. Errors during logging setup may cause the application to error before any logging is setup causing errors to not be sent to the log files (making debugging much harder). The initial logging will use settings from both the console and file logging settings.

Attributes:

Name	Type	Description
default_level	int	Default logging level. Actual log level will be computed from this level and the application's verbosity args.
additional_namespaces	List[str]	Additional namespaces that should be logged.
initial_log_location	str	Directory for storing the initial log
initial_log_filename	str	filename of the initial log. Will be formatted with the application's name.
initial_log_level	Union[str, int]	logging level of initial log.
console_stream	IO	stream to output console logging to
console_format	str	text format for console logging
console_format_style	str	console_format format style
console_date_format	str	console_format date format
file_enabled	bool	enable logging to files.
file_default_location	str	default log file location. Actual location may be changed from the applications log-dir arg.
file_filename	str	filename of log. Will be formatted with the applications name.
file_format	str	text format for file logging
file_format_style	str	file_format format style
file_date_format	str	file_format date format
file_max_size	int	max size of a log file in bytes (see RotatingFileHandler).
file_backup_count	int	number of old log files to keep (see RotatingFileHandler).