cookbook

Cookbook module.

class spicerack.cookbook.BaseCookbooksItem(module_name, args, spicerack)[source]

Bases: object

Base class for any item collected by the Cookbooks class.

__init__(module_name, args, spicerack)[source]

Base cookbooks's item constructor.

Parameters:
  • module_name (str) -- the Python module to load.
  • args (list, tuple) -- the command line arguments to pass to the item.
  • spicerack (spicerack.Spicerack) -- the initialized instance of the library.
static _get_line_prefix(level, cont_levels, is_final)[source]

Return the line prefix for the given level in the tree.

Parameters:
  • level (int) -- how many levels the item is nested in the tree.
  • cont_levels (list, tuple) -- an iterable of size levels with booleans that indicate for each level if the continuation prefix (True) or an empty prefix (False) should be used.
  • is_final (bool) -- whether the line is the final in its own group.
Returns:

the line prefix to use.
Return type:

str
_get_title()[source]

Calculate the title of the instance item.

Returns:the title of the item.
Return type:str
run()[source]

abstract Excecute the item.

verbose_title

Getter for the verbose_title property, uses the module name if there is no title.

Returns:the verbose title of the item.
Return type:str
spicerack.cookbook.COOKBOOKS_MENU_HELP_MESSAGE = "Cookbooks interactive menu help\n\nAvailable cookbooks and cookbook groups are shown in the menu with the format:\n [STATUS] NAME: DESCRIPTION\nAdditional control commands are also shown.\nTo select an item just input its name and press Enter.\n\nGroup of cookbooks:\n They have a status that represent the number of the executed cookbooks over\n the total number of cookbooks in that group and its child groups\n (i.e. [2/11]) or the status 'DONE' in case all cookbooks in that group were\n executed during the current session.\n When selected the child cookbooks group is shown.\n\nSingle cookbooks:\n Their status has one of the following values:\n {statuses}\n When selected the cookbook is executed and then the current menu is shown\n again after its execution, with the status updated based on the result of the\n execution.\n\nControl commands:\n b: shown when inside a child group of cookbooks to go back one level to the\n parent menu.\n q: shown when at the top level of the current session menu to exit the\n program.\n h: always shown, print this help message.\n\n Note: 'q' and 'b' are mutually exclusive, only one of them is shown.\n\nCLI arguments:\n It's possible to pass CLI parameters to cookbooks and group of cookbooks\n when selecting them (i.e. cookbook_name -a param value1 value2).\n Passing arguments to cookbook groups propagate them also to their cookbooks\n and child cookbook groups.\n Passing arguments override any other argument that might have been passed\n to the cookbook executable or to any of the parent groups when selected.\n\nInterrupting execution:\n Pressing Ctrl+c/d while executing a cookbook interrupts it and show the\n current menu, marking the cookbook status as ERROR.\n Pressing Ctrl+c/d while in a menu is equivalent to select 'b' or 'q'.\n"

the generic CookbooksMenu help message, unformatted.

Type:str
spicerack.cookbook.COOKBOOK_EXCEPTION_RETCODE = 99

reserved exit code: the cookbook raised an exception while executing.

Type:int
spicerack.cookbook.COOKBOOK_INTERRUPTED_RETCODE = 97

reserved exit code: the execution was interrupted.

Type:int
spicerack.cookbook.COOKBOOK_NOT_FOUND_RETCODE = 98

reserved exit code: no cookbook is found for the selection.

Type:int
spicerack.cookbook.COOKBOOK_NO_PARSER_WITH_ARGS_RETCODE = 95

reserved exit code: the cookbook doesn't have an argument_parser() function but was called with arguments.

Type:int
spicerack.cookbook.COOKBOOK_PARSE_ARGS_FAIL_RETCODE = 96

reserved exit code: the cookbook fail to parse arguments.

Type:int
class spicerack.cookbook.Cookbook(module_name, args, spicerack)[source]

Bases: spicerack.cookbook.BaseCookbooksItem

Cookbook class.

__init__(module_name, args, spicerack)[source]

Override parent constructor to add menu-specific initialization.

Parameters:according to spicerack.cookbook.BaseCookbooksItem.
static _get_line_prefix(level, cont_levels, is_final)

static inherited Return the line prefix for the given level in the tree.

Parameters:
  • level (int) -- how many levels the item is nested in the tree.
  • cont_levels (list, tuple) -- an iterable of size levels with booleans that indicate for each level if the continuation prefix (True) or an empty prefix (False) should be used.
  • is_final (bool) -- whether the line is the final in its own group.
Returns:

the line prefix to use.
Return type:

str
_get_title()

static inherited Calculate the title of the instance item.

Returns:the title of the item.
Return type:str
_parse_args()[source]

Get the argument parser from the cookbook, if it exists, and parse the arguments.

Returns:
(int, argparse.Namespace) with the return code to use and the parsed arguments. If the return code is
different from -1 it means that the cookbook should not be executed either because the help message was requested or the parse of the arguments failed or arguments were passed but the cookbook doesn't define a argument_parser() function.
Return type:tuple
_run(args)[source]

Run the cookbook's run() function.

Parameters:args (argparse.Namespace, None) -- the parsed arguments or None if the cookbook doesn't define a argument_parser() function.
Returns:
the return code to use for this cookbook, it should be zero on success, a positive integer smaller than
128 and not in the range 90-99 (reserved exit codes) in case of failure.
Return type:int
run()[source]

Run the cookbook, calling both its argument_parser and run functions.

Returns:
the return code to use for this cookbook, it should be zero on success, a positive integer smaller than
128 and not in the range 90-99 (reserved exit codes) in case of failure.
Return type:int
verbose_title

inherited Getter for the verbose_title property, uses the module name if there is no title.

Returns:the verbose title of the item.
Return type:str
exception spicerack.cookbook.CookbookError[source]

Bases: spicerack.exceptions.SpicerackError

Custom exception class for errors of this module.

class spicerack.cookbook.Cookbooks(base_dir, args, spicerack, path_filter=None)[source]

Bases: object

Collect and represent available cookbooks.

__init__(base_dir, args, spicerack, path_filter=None)[source]

Initialize the Cookbook class and collect CookbooksMenu and Cookbook items.

Parameters:
  • base_dir (str) -- the base directory from where to start looking for cookbooks.
  • args (list, tuple) -- the list of arguments to pass to the collected items.
  • spicerack (spicerack.Spicerack) -- the initialized instance of the library.
  • path_filter (str, optional) -- an optional relative module path to filter for. If set, only cookbooks that are part of this subtree will be collected.
_collect()[source]

Collect available cookbooks starting from a base path.

_collect_filename(filename, prefix, menu)[source]

Iterate the filenames in the current directory as reported by os.walk() and add them to the tree.

Parameters:
  • filename (str) -- the filename to collect.
  • prefix (str) -- the Python module prefix to use to load the given filename.
  • menu (spicerack.cookbook.CookbooksMenu) -- the menu to append the collected cookbook to.
_create_menu_for_path(path)[source]

Create the menu for a given path, including intermediate levels, if missing. Return the existing one if any.

Parameters:path (str) -- the path of the item to look for.
Returns:the existing or created menu.
Return type:spicerack.cookbook.CookbooksMenu
static _filter_dirnames_and_filenames(dirnames, filenames)[source]

Filter the dirnames and filenames in place (required by os.walk()) to select only Python modules.

Parameters:
  • dirnames (list) -- the list of sub-directories, as returned by os.walk().
  • filenames (list) -- the list of filenames in the current directory, as returned by os.walk().
Returns:

(list, list) with the modified dirnames and filenames.
Return type:

tuple
_submenu_add_parent(module_name, path)[source]

Determine if the submenu item to be appended should have a link to the parent menu or not.

When collecting the cookbooks and creating the CookbooksMenu instances, the relation to the parent menu should be skipped for those intermediate menus created for coherence but that should not be accessible by the user, like when using a path_filter.

Parameters:
  • module_name (str) -- the module name of the submenu.
  • path (str) -- of the item to be add.
Returns:

True if the link to the parent menu should be set, False otherwise.
Return type:

bool
get_item(path)[source]

Retrieve the item for a given path.

Parameters:path (str) -- the path of the item to look for.
Returns:when no item is found. spicerack.cookbook.CookbooksMenu: when the item found is a menu of cookbooks. spicerack.cookbook.Cookbook: when the item found is a single cookbook.
Return type:None
class spicerack.cookbook.CookbooksMenu(module_name, args, spicerack)[source]

Bases: spicerack.cookbook.BaseCookbooksItem

Cookbooks Menu class.

__init__(module_name, args, spicerack)[source]

Override parent constructor to add menu-specific initialization.

Parameters:according to spicerack.cookbook.BaseCookbooksItem.
_get_item_args(item, args)[source]

Get the arguments to pass to the given item.

Parameters:
  • item (spicerack.cookbook.Base) -- the item to pass the arguments to.
  • args (list) -- the arguments passed via interactive menu to this item.
static _get_line_prefix(level, cont_levels, is_final)

static inherited Return the line prefix for the given level in the tree.

Parameters:
  • level (int) -- how many levels the item is nested in the tree.
  • cont_levels (list, tuple) -- an iterable of size levels with booleans that indicate for each level if the continuation prefix (True) or an empty prefix (False) should be used.
  • is_final (bool) -- whether the line is the final in its own group.
Returns:

the line prefix to use.
Return type:

str
_get_title()

static inherited Calculate the title of the instance item.

Returns:the title of the item.
Return type:str
append(item, add_parent=True)[source]

Append an item to this menu.

Parameters:
back_answer = 'b'

interactive menu answer to go back to the parent menu.

Type:str
calculate_status()[source]

Calculate the status of a menu, checking the status of all it's tasks recursively.

Returns:(int, int) with the number of completed and total items.
Return type:tuple
get_menu_tree(level, cont_levels)[source]

Calculate the tree lines for a given menu.

Parameters:
  • level (int) -- how many levels the item is nested in the tree.
  • cont_levels (list, tuple) -- an iterable of size levels with booleans that indicate for each level if the continuation prefix (True) or an empty prefix (False) should be used.
Returns:

the list of lines that represent the tree.
Return type:

list
get_tree()[source]

Return the tree representation of the menu as string.

Returns:the tree representation of all the collected items.
Return type:str
help_answer = 'h'

interactive menu answer to print the generic CookbooksMenu help message.

Type:str
help_message = "Cookbooks interactive menu help\n\nAvailable cookbooks and cookbook groups are shown in the menu with the format:\n [STATUS] NAME: DESCRIPTION\nAdditional control commands are also shown.\nTo select an item just input its name and press Enter.\n\nGroup of cookbooks:\n They have a status that represent the number of the executed cookbooks over\n the total number of cookbooks in that group and its child groups\n (i.e. [2/11]) or the status 'DONE' in case all cookbooks in that group were\n executed during the current session.\n When selected the child cookbooks group is shown.\n\nSingle cookbooks:\n Their status has one of the following values:\n ('NOTRUN', 'PASS', 'FAIL', 'ERROR')\n When selected the cookbook is executed and then the current menu is shown\n again after its execution, with the status updated based on the result of the\n execution.\n\nControl commands:\n b: shown when inside a child group of cookbooks to go back one level to the\n parent menu.\n q: shown when at the top level of the current session menu to exit the\n program.\n h: always shown, print this help message.\n\n Note: 'q' and 'b' are mutually exclusive, only one of them is shown.\n\nCLI arguments:\n It's possible to pass CLI parameters to cookbooks and group of cookbooks\n when selecting them (i.e. cookbook_name -a param value1 value2).\n Passing arguments to cookbook groups propagate them also to their cookbooks\n and child cookbook groups.\n Passing arguments override any other argument that might have been passed\n to the cookbook executable or to any of the parent groups when selected.\n\nInterrupting execution:\n Pressing Ctrl+c/d while executing a cookbook interrupts it and show the\n current menu, marking the cookbook status as ERROR.\n Pressing Ctrl+c/d while in a menu is equivalent to select 'b' or 'q'.\n"

the generic CookbooksMenu help message.

Type:str
quit_answer = 'q'

answer to quit the interactive menu.

Type:str
run()[source]

Execute the menu in an interactive way (infinite loop).

run_once()[source]

Run the menu in an interactive way.

Returns:the current menu instance.
Return type:spicerack.cookbook.CookbooksMenu
show()[source]

Print the menu to stdout.

status

Getter for the menu status, returns a string representation of the status of its tasks.

Returns:the menu status message.
Return type:str
verbose_title

inherited Getter for the verbose_title property, uses the module name if there is no title.

Returns:the verbose title of the item.
Return type:str
spicerack.cookbook.argument_parser()[source]

Get the CLI argument parser.

If the COOKBOOK is passed as a path, it will be converted to a Python module syntax.

Returns:the argument parser instance.
Return type:argparse.ArgumentParser
spicerack.cookbook.cookbook_path_type(path)[source]

Convert a COOKBOOK path to module syntax, if it's in path syntax.

Parameters:path (str, None) -- the path to be converted.
Returns:the converted path in module syntax or None if None was passed.
Return type:str, None
spicerack.cookbook.execute_cookbook(config, args, cookbooks)[source]

Execute a single cookbook with its parameters.

Parameters:
Returns:

the return code, 0 on success, non-zero on cookbook failure, 98 on cookbook exception.
Return type:

int
spicerack.cookbook.import_module(module_name)[source]

Import a Python module.

Parameters:module_name (str) -- the name of the module to load.
Raises:spicerack.cookbook.CookbookError -- on failure to load the module.
spicerack.cookbook.main(argv=None)[source]

Entry point, run the tool.

Parameters:argv (list, optional) -- the list of command line arguments to parse.
Returns:the return code, zero on success, non-zero on failure.
Return type:int