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.
- class tutor.core.hooks.Action
Action hooks have callbacks that are triggered independently from one another.
Several actions are defined across the codebase. Each action is given a unique name. To each action are associated zero or more callbacks, sorted by priority.
This is the typical action lifecycle:
The
T
type parameter of the Action class corresponds to the expected signature of the action callbacks. For instance,Action[[str, int]]
means that the action callbacks are expected to take two arguments: one string and one integer.This strong typing makes it easier for plugin developers to quickly check whether they are adding and calling action callbacks correctly.
- add(priority=None)
Decorator to add a callback to an action.
- Parameters:
priority (int | None) – optional order in which the action callbacks are performed. Higher values mean that they will be performed later. The default value is
priorities.DEFAULT
(10). Actions that should be performed last should have a priority of 100.- Return type:
Callable[[Callable[[tutor.core.hooks.actions.T], None]], Callable[[tutor.core.hooks.actions.T], None]]
Usage:
@my_action.add("my-action") def do_stuff(my_arg): ...
The
do_stuff
callback function will be called onmy_action.do(some_arg)
.The signature of each callback action function must match the signature of the corresponding
do()
method. Callback action functions are not supposed to return any value. Returned values will be ignored.
- clear(context=None)
Clear all or part of the callbacks associated to an action
- Parameters:
name – name of the action callbacks to remove.
context (str | None) – 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.
- classmethod clear_all(context=None)
Clear any previously defined action with the given context.
- Parameters:
context (str | None) –
- Return type:
None
- do(*args, **kwargs)
Run the action callbacks in sequence.
- Parameters:
name – name of the action for which callbacks will be run.
args (T.args) –
kwargs (T.kwargs) –
- 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 will be bubbled up.
- do_from_context(context, *args, **kwargs)
Same as
do()
but only run the callbacks from a given context.- Parameters:
name – name of the action for which callbacks will be run.
context (t.Optional[str]) – limit the set of callback actions to those that were declared within a certain context (see
tutor.core.hooks.contexts.enter()
).args (T.args) –
kwargs (T.kwargs) –
- Return type:
None
- class tutor.core.hooks.actions.T
- class tutor.types.Config