Hooks

Hooks enable you to execute custom code at certain points during a BundleWrap run. This is useful for integrating with other systems e.g. for team notifications, logging or statistics.

To use hooks, you need to create a subdirectory in your repo called hooks. In that directory you can place an arbitrary number of Python source files. If those source files define certain functions, these functions will be called at the appropriate time.

Example

hooks/my_awesome_notification.py:

from my_awesome_notification_system import post_message

def node_apply_start(repo, node, interactive=False, **kwargs):
    post_message("Starting apply on {}, everything is gonna be OK!".format(node.name))

Note

Always define your hooks with **kwargs so we can pass in more information in future updates without breaking your hook.


Functions

This is a list of all functions a hook file may implement.


action_run_start(repo, node, action, **kwargs)

Called each time a bw apply command reaches a new action.

Parameters:


action_run_end(repo, node, action, duration=None, status=None, **kwargs)

Called each time a bw apply command completes processing an action.

Parameters:
  • repo (Repository) – The current repository (instance of bundlewrap.repo.Repository).
  • node (Node) – The current node (instance of bundlewrap.node.Node).
  • item (Item) – The current action.
  • duration (timedelta) – How long the action was running.
  • status (ItemStatus) – An object with these attributes: correct, skipped.


apply_start(repo, target, nodes, interactive=False, **kwargs)

Called when you start a bw apply command.

Parameters:
  • repo (Repository) – The current repository (instance of bundlewrap.repo.Repository).
  • target (str) – The group or node name you gave on the command line.
  • nodes (list) – A list of node objects affected (list of bundlewrap.node.Node instances).
  • interactive (bool) – Indicates whether the apply is interactive or not.


apply_end(repo, target, nodes, duration=None, **kwargs)

Called when a bw apply command completes.

Parameters:
  • repo (Repository) – The current repository (instance of bundlewrap.repo.Repository).
  • target (str) – The group or node name you gave on the command line.
  • nodes (list) – A list of node objects affected (list of bundlewrap.node.Node instances).
  • duration (timedelta) – How long the apply took.


item_apply_start(repo, node, item, **kwargs)

Called each time a bw apply command reaches a new item.

Parameters:


item_apply_end(repo, node, item, duration=None, status_before=None, status_after=None, **kwargs)

Called each time a bw apply command completes processing an item.

Parameters:
  • repo (Repository) – The current repository (instance of bundlewrap.repo.Repository).
  • node (Node) – The current node (instance of bundlewrap.node.Node).
  • item (Item) – The current item.
  • duration (timedelta) – How long the apply took.
  • status_before (ItemStatus) – An object with these attributes: correct, info, skipped.
  • status_after (ItemStatus) – See status_before.


node_apply_start(repo, node, interactive=False, **kwargs)

Called each time a bw apply command reaches a new node.

Parameters:


node_apply_end(repo, node, duration=None, interactive=False, result=None, **kwargs)

Called each time a bw apply command finishes processing a node.

Parameters:
  • repo (Repository) – The current repository (instance of bundlewrap.repo.Repository).
  • node (Node) – The current node (instance of bundlewrap.node.Node).
  • duration (timedelta) – How long the apply took.
  • interactive (bool) – True if this was an interactive apply run.
  • result (ApplyResult) – An object with these attributes: correct, failed, fixed, skipped.


node_run_start(repo, node, command, **kwargs)

Called each time a bw run command reaches a new node.

Parameters:


node_run_end(repo, node, command, duration=None, return_code=None, stdout="", stderr="", **kwargs)

Called each time a bw run command finishes on a node.

Parameters:
  • repo (Repository) – The current repository (instance of bundlewrap.repo.Repository).
  • node (Node) – The current node (instance of bundlewrap.node.Node).
  • command (str) – The command that was run on the node.
  • duration (timedelta) – How long it took to run the command.
  • return_code (int) – Return code of the remote command.
  • stdout (str) – The captured stdout stream of the remote command.
  • stderr (str) – The captured stderr stream of the remote command.


run_start(repo, target, nodes, command, **kwargs)

Called each time a bw run command starts.

Parameters:
  • repo (Repository) – The current repository (instance of bundlewrap.repo.Repository).
  • target (str) – The group or node name you gave on the command line.
  • nodes (list) – A list of node objects affected (list of bundlewrap.node.Node instances).
  • command (str) – The command that will be run on the node.


run_end(repo, target, nodes, command, duration=None, **kwargs)

Called each time a bw run command finishes.

Parameters:
  • repo (Repository) – The current repository (instance of bundlewrap.repo.Repository).
  • target (str) – The group or node name you gave on the command line.
  • nodes (list) – A list of node objects affected (list of bundlewrap.node.Node instances).
  • command (str) – The command that was run.
  • duration (timedelta) – How long it took to run the command on all nodes.