Actions
Actions are one of the two types of hooks (the other being Filters) that can be used to extend Tutor. Each action represents an event that can occur during the application life cycle. Each action has a name, and callback functions can be attached to it. When an action is triggered, these callback functions are called in sequence. Each callback function can trigger side effects, independently from one another.
- tutor.hooks.actions.get(name)
Get an existing action with the given name from the index, or create one.
- Parameters
name (str) –
- Return type
- tutor.hooks.actions.get_template(name)
Create an action with a template name.
Templated actions must be formatted with
(*args)
before being applied. For example:action_template = actions.get_template("namespace:{0}") @action_template("name").add() def my_callback(): ... action_template("name").do()
- Parameters
name (str) –
- Return type
- tutor.hooks.actions.add(name, priority=None)
Decorator to add a callback action associated to a name.
- Parameters
name (str) – name of the action. For forward compatibility, it is recommended not to hardcode any string here, but to pick a value from
tutor.hooks.Actions
instead.priority (Optional[int]) – optional order in which the action callbacks are performed. Higher values mean that they will be performed later. The default value is
DEFAULT_PRIORITY
(10). Actions that should be performed last should have a priority of 100.
- Return type
Callable[[Callable[[…], None]], Callable[[…], None]]
Usage:
from tutor import hooks @hooks.actions.add("my-action") def do_stuff(): ...
The
do_stuff
callback function will be called onhooks.actions.do("my-action")
. (seedo()
)The signature of each callback action function must match the signature of the corresponding
hooks.actions.do
call. Callback action functions are not supposed to return any value. Returned values will be ignored.
- tutor.hooks.actions.do(name, *args, context=None, **kwargs)
Run action callbacks associated to a name/context.
- Parameters
name (str) – name of the action for which callbacks will be run.
context (Optional[str]) – limit the set of callback actions to those that were declared within a certain context (see
tutor.hooks.contexts.enter()
).args (Any) –
kwargs (Any) –
- Return type
None
Extra
*args
and*kwargs
arguments will be passed as-is to callback functions.Callbacks are executed in order of priority, then FIFO. There is no error management here: a single exception will cause all following callbacks not to be run and the exception to be bubbled up.
- tutor.hooks.actions.clear(name, context=None)
Clear any previously defined action with the given name and context.
- Parameters
name (str) – name of the action callbacks to remove.
context (Optional[str]) – when defined, will clear only the actions that were created within that context.
- Return type
None
Actions will be removed from the list of callbacks and will no longer be run in
do()
calls.This function should almost certainly never be called by plugins. It is mostly useful to disable some plugins at runtime or in unit tests.
- tutor.hooks.actions.clear_all(context=None)
Clear any previously defined filter with the given context.
This will call
clear()
with all action names.- Parameters
context (Optional[str]) –
- Return type
None
- class tutor.hooks.actions.Action(name)
Each action is associated to a name and a list of callbacks, sorted by priority.
- Parameters
name (str) –
- Return type
None
- class tutor.hooks.actions.ActionTemplate(name)
Action templates are for actions for which the name needs to be formatted before the action can be applied.
- Parameters
name (str) –