cookbook

Cookbook module.

class spicerack.cookbook.ArgparseFormatter(prog, indent_increment=2, max_help_position=24, width=None)

Bases: argparse.ArgumentDefaultsHelpFormatter, argparse.RawDescriptionHelpFormatter

Custom argparse formatter class for cookbooks.

It can be used as the formatter_class for the ArgumentParser instances and it has the capabilities of both argparse.ArgumentDefaultsHelpFormatter and argparse.RawDescriptionHelpFormatter.

class spicerack.cookbook.CookbookBase(spicerack: spicerack.Spicerack)

Bases: object

abstract Base Cookbook class that all cookbooks must extend to use the class-based API to define a cookbook.

The class will be instantiated without any parameter.

Initializee the instance and store the Spicerack instance into self.spicerack.

Parameters

spicerack (spicerack.Spicerack) -- the Spicerack accessor instance with which the cookbook can access all the Spicerack capabilities.

argument_parser() → argparse.ArgumentParser

Optionally define an argument parser for the cookbook, if the cookbook accepts CLI arguments.

The default implementation returns an empty ArgumentParser instance that doesn't accept any arguments and uses the class docstring as description.

Returns

the argument parser object, the arguments will be parsed by the framework.

Return type

argparse.ArgumentParser

abstract get_runner(args: argparse.Namespace) → spicerack.cookbook.CookbookRunnerBase

Return the runner object that will be used to execute the cookbook.

Derived classes must override this method and can perform any initialization and validation of the parsed arguments, but must not perform any real action here.

If any exception is raised in this method Spicerack will not execute the cookbook.

Parameters

args (argparse.Namespace) -- the parsed arguments that were parsed using the defined argument_parser().

Raises

BaseException -- any exception raised in the get_runner() method will be catched by Spicerack and the Cookbook will not be executed.

Returns

an instance of a custom class derived from spicerack.cookbook.CookbookRunnerBase that implements the actual execution of the cookbook.

Return type

spicerack.cookbook.CookbookRunnerBase

spicerack_name: str

Reserved class property used by Spicerack internally to track the Cookbook's name.

spicerack_path: str

Reserved class property used by Spicerack internally to track the Cookbook's path.

property title: str

Retuns the title of the Cookbook, must be a single line string.

The default implementation returns the first line of the class docstring if there is any, a single dash otherwise.

Returns

the cookbook static title.

Return type

str

class spicerack.cookbook.CookbookRunnerBase

Bases: object

abstract Base class that all cookbooks must extend to use the class-based API to define the execution plan.

The constructor of the class is left outside of the interface contract so that each cookbook is free to customize it as needed.

rollback() → None

Called by Spicerack when the cookbook fails the execution.

This method by default does nothing. Cookbooks classes that inherit from this one can override it to add their own custom actions to perform on error to rollback to a previous state. The method will be called if the cookbook raises any un-caught exception or exits with a non-zero exit code. For example it can be used to cleanup any left-over unconsistent state as if the cookbook was never run.

Any un-caught exception raised by this method will be caught by Spicerack and logged, along with the original exit code of the cookbook. The final exit code will be the reserved cookbooks.ROLLBACK_FAIL_RETCODE.

abstract run() → Optional[int]

Excute the cookbook.

Returns

the return code of the cookbook, it should be zero or None on success, a positive integer smaller than 128 and not in the range 90-99 (see Reserved exit codes) in case of failure.

Return type

int, None

Raises

BaseException -- any exception raised in the run() method will be catched by Spicerack and the Cookbook execution will be considered failed.

property runtime_description: str

Optional message to be used as the runtime description of the cookbook.

Cookbooks can override this instance property to define their custom description, also based on the given command line arguments. For example this will be used in the task start/end messages.

Returns

the runtime description. If not overriden an empty string will be used.

Return type

str

spicerack.cookbook.CLASS_FAIL_INIT_RETCODE = 94

Reserved exit code: failed to initialize the cookbook.

Type

int

spicerack.cookbook.EXCEPTION_RETCODE = 99

Reserved exit code: a cookbook raised an exception while executing.

Type

int

spicerack.cookbook.GET_ARGS_PARSER_FAIL_RETCODE = 95

Reserved exit code: the call to get the argument parser failed.

Type

int

spicerack.cookbook.INTERRUPTED_RETCODE = 97

Reserved exit code: a cookbook execution was interrupted.

Type

int

spicerack.cookbook.NOT_FOUND_RETCODE = 98

Reserved exit code: no cookbook was found for the selection.

Type

int

spicerack.cookbook.PARSE_ARGS_FAIL_RETCODE = 96

Reserved exit code: a cookbook failed to parse arguments.

Type

int

spicerack.cookbook.ROLLBACK_FAIL_RETCODE = 93

Reserved exit code: the cookbook had failed and raised an exception while executing the rollback() method.

Type

int