allow hooks to raise SkipNode

closes #385

bundlewrap/cmdline/run.py

@@ -9,6 +9,7 @@
 from sys import exit
 
 from ..concurrency import WorkerPool
+from ..exceptions import SkipNode
 from ..utils import SkipList
 from ..utils.cmdline import get_target_nodes
 from ..utils.table import ROW_SEPARATOR, render_table
@@ -34,11 +35,19 @@ def run_on_node(node, command, skip_list):
         io.stdout(_("{x} {node}  skipped by --resume-file").format(node=bold(node.name), x=yellow("»")))
         return None
 
-    node.repo.hooks.node_run_start(
-        node.repo,
-        node,
-        command,
-    )
+    try:
+        node.repo.hooks.node_run_start(
+            node.repo,
+            node,
+            command,
+        )
+    except SkipNode as exc:
+        io.stdout(_("{x} {node}  skipped by hook ({reason})").format(
+            node=bold(node.name),
+            reason=str(exc) or _("no reason given"),
+            x=yellow("»"),
+        ))
+        return None
 
     result = node.run(
         command,

bundlewrap/exceptions.py

@@ -141,6 +141,13 @@ class PluginLocalConflict(PluginError):
     pass
 
 
+class SkipNode(UnicodeException):
+    """
+    Can be raised by hooks to skip a node.
+    """
+    pass
+
+
 class TemplateError(RepositoryError):
     """
     Raised when an error occurs while rendering a template.

bundlewrap/node.py

@@ -19,6 +19,7 @@
     NodeLockedException,
     NoSuchBundle,
     RepositoryError,
+    SkipNode,
 )
 from .group import GROUP_ATTR_DEFAULTS
 from .itemqueue import ItemQueue
@@ -568,19 +569,27 @@ def apply(
             ))
             return None
 
-        start = datetime.now()
+        try:
+            self.repo.hooks.node_apply_start(
+                self.repo,
+                self,
+                interactive=interactive,
+            )
+        except SkipNode as exc:
+            io.stdout(_("{x} {node}  skipped by hook ({reason})").format(
+                node=bold(self.name),
+                reason=str(exc) or _("no reason given"),
+                x=yellow("»"),
+            ))
+            return None
 
+        start = datetime.now()
         io.stdout(_("{x} {node}  {started} at {time}").format(
             node=bold(self.name),
             started=bold(_("started")),
             time=start.strftime("%Y-%m-%d %H:%M:%S"),
             x=blue("i"),
         ))
-        self.repo.hooks.node_apply_start(
-            self.repo,
-            self,
-            interactive=interactive,
-        )
 
         try:
             with NodeLock(self, interactive=interactive, ignore=force) as lock:

docs/content/repo/hooks.md

@@ -164,6 +164,13 @@ Called each time a `bw apply` command reaches a new node.
 
 `interactive` `True` if this is an interactive apply run.
 
+To skip a node:
+
+```
+from bundlewrap.exceptions import SkipNode
+raise SkipNode("reason goes here")
+```
+
 ---
 
 **`node_apply_end(repo, node, duration=None, interactive=False, result=None, **kwargs)`**
@@ -192,6 +199,13 @@ Called each time a `bw run` command reaches a new node.
 
 `command` The command that will be run on the node.
 
+To skip a node:
+
+```
+from bundlewrap.exceptions import SkipNode
+raise SkipNode("reason goes here")
+```
+
 ---
 
 **`node_run_end(repo, node, command, duration=None, return_code=None, stdout="", stderr="", **kwargs)`**