Execution hooks (core features)

changelog.txt

@@ -5,6 +5,16 @@ Changelog
 The **signac-flow** package follows `semantic versioning <https://semver.org/>`_.
 The numbers in brackets denote the related GitHub issue and/or pull request.
 
+Version 0.18
+
+[0.18.0] -- 2022-xx-xx
+----------------------
+
+Added
++++++
+
+- Feature to install execution hooks for the automated execution of functions with operations (#28, #189, #508).
+
 Version 0.17
 ============
 

doc/api.rst

@@ -35,6 +35,11 @@ The FlowProject
     FlowProject.make_group
     FlowProject.operation
     FlowProject.operation.with_directives
+    FlowProject.operation_hooks
+    FlowProject.operation_hooks.on_fail
+    FlowProject.operation_hooks.on_finish
+    FlowProject.operation_hooks.on_start
+    FlowProject.operation_hooks.on_success
     FlowProject.operations
     FlowProject.post
     FlowProject.post.copy_from
@@ -52,6 +57,7 @@ The FlowProject
     FlowProject.pre.not_
     FlowProject.pre.true
     FlowProject.print_status
+    FlowProject.project_hooks
     FlowProject.run
     FlowProject.scheduler_jobs
     FlowProject.submit
@@ -60,12 +66,22 @@ The FlowProject
 .. autoclass:: FlowProject
     :show-inheritance:
     :members:
-    :exclude-members: pre,post,operation
+    :exclude-members: pre,post,operation,operation_hooks
 
 .. automethod:: flow.FlowProject.operation(func, name=None)
 
 .. automethod:: flow.FlowProject.operation.with_directives(directives, name=None)
 
+.. automethod:: flow.FlowProject.operation_hooks(hook_func, trigger)
+
+.. automethod:: flow.FlowProject.operation_hooks.on_fail
+
+.. automethod:: flow.FlowProject.operation_hooks.on_finish
+
+.. automethod:: flow.FlowProject.operation_hooks.on_start
+
+.. automethod:: flow.FlowProject.operation_hooks.on_success
+
 .. automethod:: flow.FlowProject.post
 
 .. automethod:: flow.FlowProject.post.copy_from

flow/__init__.py

@@ -8,7 +8,7 @@
 
 .. _signac: https://signac.io/
 """
-from . import environment, errors, scheduling, testing
+from . import environment, errors, hooks, scheduling, testing
 from .aggregates import aggregator, get_aggregate_id
 from .environment import get_environment
 from .operations import cmd, directives, with_job
@@ -24,6 +24,7 @@
 __all__ = [
     "environment",
     "errors",
+    "hooks",
     "scheduling",
     "testing",
     "aggregator",

flow/hooks/__init__.py

@@ -0,0 +1,7 @@
+# Copyright (c) 2018 The Regents of the University of Michigan
+# All rights reserved.
+# This software is licensed under the BSD 3-Clause License.
+"""Operation hooks."""
+from .hooks import _Hooks
+
+__all__ = ["_Hooks"]

flow/hooks/hooks.py

@@ -0,0 +1,108 @@
+# Copyright (c) 2018 The Regents of the University of Michigan
+# All rights reserved.
+# This software is licensed under the BSD 3-Clause License.
+"""Operation hooks."""
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class _HooksList(list):
+    def __call__(self, *args, **kwargs):
+        """Call all hook functions as part of this list."""
+        for hook in self:
+            logger.debug(f"Executing hook function '{hook}'.")
+            try:
+                hook(*args, **kwargs)
+            except Exception as error:
+                logger.error(
+                    "Error occurred during execution of "
+                    "hook '{}': {}.".format(hook, error)
+                )
+                raise
+
+
+class _Hooks:
+    """:class:`~._Hooks` execute an action or set of actions at specific stages of operation execution.
+
+    :class:`~._Hooks` can execute a user defined function when an operation
+    starts, succeeds, fails, or finishes (regardless of whether the operation
+    executed successfully or failed).
+
+    Hooks can be installed at the operation level as decorators, or on an
+    instance of :class:`~.FlowProject` through
+    :meth:`~.FlowProject.project_hooks`.
+
+    Examples
+    --------
+    The example below shows an operation level decorator that prints the
+    operation name and job id at the start of the operation execution.
+
+    .. code-block:: python
+
+        def start_hook(operation_name, job):
+            print(f"Starting operation {operation_name} on job {job.id}.")
+
+        @FlowProject.operation
+        @FlowProject.operation_hook.on_start(start_hook)
+        def foo(job):
+            pass
+
+    Parameters
+    ----------
+    on_start : list of callables
+        Function(s) to execute before the operation begins execution.
+    on_finish : list of callables
+        Function(s) to execute after the operation exits, with or without errors.
+    on_success : list of callables
+        Function(s) to execute after the operation exits without error.
+    on_fail : list of callables
+        Function(s) to execute after the operation exits with an error.
+
+    """
+
+    _hook_triggers = [
+        "on_start",
+        "on_finish",
+        "on_success",
+        "on_fail",
+    ]
+
+    def __init__(self, *, on_start=None, on_finish=None, on_success=None, on_fail=None):
+        def set_hooks(self, trigger_name, trigger_value):
+            if trigger_value is None:
+                trigger_value = []
+            setattr(self, trigger_name, _HooksList(trigger_value))
+
+        set_hooks(self, "on_start", on_start)
+        set_hooks(self, "on_finish", on_finish)
+        set_hooks(self, "on_success", on_success)
+        set_hooks(self, "on_fail", on_fail)
+
+    def __setattr__(self, name, value):
+        """Convert to _HooksList when setting a hook trigger attribute."""
+        if name in self._hook_triggers:
+            super().__setattr__(name, _HooksList(value))
+        else:
+            super().__setattr__(name, value)
+
+    def update(self, other):
+        """Update this instance with hooks from another instance."""
+        for hook_trigger in self._hook_triggers:
+            getattr(self, hook_trigger).extend(getattr(other, hook_trigger))
+
+    def __str__(self):
+        """Return a string representation of all hooks."""
+        return "{}({})".format(
+            type(self).__name__,
+            ", ".join(
+                f"{hook_trigger}={getattr(self, hook_trigger)}"
+                for hook_trigger in self._hook_triggers
+            ),
+        )
+
+    def __bool__(self):
+        """Return True if hooks are defined."""
+        return any(
+            getattr(self, hook_trigger, None) for hook_trigger in self._hook_triggers
+        )