cookbook
Cookbook module.
- class spicerack.cookbook.ArgparseFormatter(prog, indent_increment=2, max_help_position=24, width=None)[source]
Bases:
ArgumentDefaultsHelpFormatter
,RawDescriptionHelpFormatter
Custom argparse formatter class for cookbooks.
It can be used as the
formatter_class
for theArgumentParser
instances and it has the capabilities of bothargparse.ArgumentDefaultsHelpFormatter
andargparse.RawDescriptionHelpFormatter
.
- class spicerack.cookbook.CookbookBase(spicerack: spicerack.Spicerack)[source]
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.
Initialize 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 [source]
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. The arguments will be parsed by the Spicerack framework.- Return type:
- abstract get_runner(args: argparse.Namespace) spicerack.cookbook.CookbookRunnerBase [source]
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 definedargument_parser()
.- Raises:
BaseException -- any exception raised in the
get_runner()
method will be catched by Spicerack and the Cookbook will not be executed.- Return type:
- Returns:
Must return an instance of a custom class derived from
spicerack.cookbook.CookbookRunnerBase
that implements the actual execution of the cookbook.
-
owner_team:
str
= 'unowned' Name of the team owning this cookbook and responsible to keep it up to date. If unset and any parent package (directory of cookbooks) has the
__owner_team__
property set it will inherit it. It shows up when listing cookbooks and in the help message as parser epilog.
-
spicerack_name:
str
Reserved class property used by Spicerack internally to track the Cookbook's name.
- class spicerack.cookbook.CookbookRunnerBase[source]
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 [source]
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 inconsistent 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
.- Return type:
- abstract run() int | None [source]
Execute the cookbook.
- Return type:
- Returns:
The return code of the cookbook, it should be zero or
None
on success, a positive integer smaller than128
and not in the range90-99
(see Reserved exit codes) in case of failure.- Raises:
BaseException -- any exception raised in the
run()
method will be catched by Spicerack and the Cookbook execution will be considered failed.
- property lock_args: LockArgs
Optional property to dynamically modify the arguments used for the distributed lock of the cookbook runs.
It is useful to allow to set a different concurrency and TTL for the cookbook's lock based on the operation performed. For example allowing for an increased concurrency when performing read-only operations, or to differentiate the lock based on the given arguments, say having different locks for different datacenters or clusters. This property by default returns the static
max_concurrency
andlock_ttl
class properties with an empty suffix.- Returns:
the arguments to be used by Spicerack to acquire the lock for the current cookbook.
-
lock_ttl:
int
= 1800 The concurrency lock time to live (TTL) in seconds. For each concurrent run a lock is acquired for this amount of seconds. If the
lock_args
property is defined this one is ignored.
-
max_concurrency:
int
= 20 How many parallel runs of a specific cookbook inheriting from this class are accepted. If the
lock_args
property is defined this one is ignored.
- 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. The default implementation returns an empty string.
- class spicerack.cookbook.LockArgs(suffix: str, concurrency: int, ttl: int) None [source]
Bases:
object
A dataclass to represent the arguments to use for the cookbook automatically acquired lock for each run.
To be used when a cookbook overrides the
lock_args
property.- Parameters:
suffix (
str
) -- a custom suffix to add to the lock key. The lock key is based on the cookbook's full name and the suffix is added to it with a colon separator, for example with suffixro
the key will becomesre.some.cookbook:ro
.concurrency (
int
) -- how many parallel runs of the cookbook with the same lock arguments can be run.ttl (
int
) -- the lock time to live (TTL) in seconds. It should be higher than the expected run time of the cookbook.
- spicerack.cookbook.CLASS_FAIL_INIT_RETCODE: int = 94
failed to initialize the cookbook.
- Type:
Reserved exit code
- spicerack.cookbook.EXCEPTION_RETCODE: int = 99
a cookbook raised an exception while executing.
- Type:
Reserved exit code
- spicerack.cookbook.GET_ARGS_PARSER_FAIL_RETCODE: int = 95
the call to get the argument parser failed.
- Type:
Reserved exit code
- spicerack.cookbook.INTERRUPTED_RETCODE: int = 97
a cookbook execution was interrupted.
- Type:
Reserved exit code
- spicerack.cookbook.NOT_FOUND_RETCODE: int = 98
no cookbook was found for the selection.
- Type:
Reserved exit code