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(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().

  2. Add callbacks with method add().

  3. Call the action callbacks with method 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.

Parameters

name (str) –

Return type

None

add(priority=None)

Decorator to add a callback to an action.

Parameters

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.

Usage:

@my_action.add("my-action")
def do_stuff(my_arg):
    ...

The do_stuff callback function will be called on my_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 (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.

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

classmethod get(name)

Get an existing action with the given name from the index, or create one.

Parameters

name (str) –

Return type

tutor.core.hooks.actions.Action[(typing.Any,)]

class tutor.core.hooks.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.

Templated actions must be formatted with (*args) before being applied. For example:

action_template = ActionTemplate("namespace:{0}")

# Return the action named "namespace:name"
my_action = action_template("name")

@my_action.add()
def my_callback():
    ...

my_action.do()
Parameters

name (str) –

class tutor.core.hooks.actions.T
class tutor.types.Config