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

Action[t.Any]

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

ActionTemplate[Any]

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 priorities.DEFAULT (10). Actions that should be performed last should have a priority of 100.

Return type

Callable[[Callable[[P], None]], Callable[[P], 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, **kwargs)

Run action callbacks associated to a name/context.

Parameters

  • name (str) – name of the action for which callbacks will be run.

  • args (P.args) –

  • kwargs (P.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 to be bubbled up.

tutor.hooks.actions.do_from_context(context, name, *args, **kwargs)

Same as do() but only run the callbacks that were created in a given context.

Parameters

  • name (str) – name of the action for which callbacks will be run.

  • context (str) – limit the set of callback actions to those that were declared within a certain context (see tutor.hooks.contexts.enter()).

  • args (P.args) –

  • kwargs (P.kwargs) –

Return type

None

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)

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:

  1. Create an action with method get() (or function get()).

  2. Add callbacks with method add() (or function add()).

  3. Call the action callbacks with method do() (or function do()).

The P 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.

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.

Action templates can generate different Action objects for which the name matches a certain template.