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:
-
-
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:
-
_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
-
-
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_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 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: Returns: (list, list) with the modified dirnames and filenames.
Return type:
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: Returns: True if the link to the parent menu should be set, False otherwise.
Return type:
-
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:
-
_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: - item (spicerack.cookbook.Cookbook, spicerack.cookbook.CookbooksMenu) -- the item to append.
- add_parent (bool, optional) -- wheter to set the parent of the new item to the current instance.
-
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
Calculate the tree lines for a given menu.
Parameters: Returns: the list of lines that represent the tree.
Return type:
-
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
-
run_once
()[source]¶ Run the menu in an interactive way.
Returns: the current menu instance. Return type: spicerack.cookbook.CookbooksMenu
-
-
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: - config (dict) -- the configuration dictionary.
- args (argparse.Namespace) -- the parsed arguments.
- cookbooks (spicerack.cookbook.Cookbooks) -- the collected cookbooks.
Returns: the return code, 0 on success, non-zero on cookbook failure, 98 on cookbook exception.
Return type:
-
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.