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.Action

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.ActionTemplate

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 on hooks.actions.do("my-action"). (see do())

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) –