Filters

Filters are one of the two types of hooks (the other being Actions) that can be used to extend Tutor. Filters allow one to modify the application behavior by transforming data. Each filter has a name, and callback functions can be attached to it. When a filter is applied, these callback functions are called in sequence; the result of each callback function is passed as the first argument to the next callback function. The result of the final callback function is returned to the application as the filter’s output.

tutor.hooks.filters.get(name)

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

Parameters

name (str) –

Return type

Filter[t.Any, t.Any]

tutor.hooks.filters.get_template(name)

Create a filter with a template name.

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

filter_template = filters.get_template("namespace:{0}")
named_filter = filter_template("name")

@named_filter.add()
def my_callback(x: int) -> int:
    ...

named_filter.apply(42)
Parameters

name (str) –

Return type

FilterTemplate[Any, Any]

tutor.hooks.filters.add(name, priority=None)

Decorator for functions that will be applied to a single named filter.

Parameters

  • name (str) – name of the filter to which the decorated function should be added.

  • priority (int) – optional order in which the filter callbacks are called. Higher values mean that they will be performed later. The default value is priorities.DEFAULT (10). Filters that should be called last should have a priority of 100.

Return type

Callable[[Callable[[T, P], T]], Callable[[T, P], T]]

The return value of each filter function callback will be passed as the first argument to the next one.

Usage:

from tutor import hooks

@hooks.filters.add("my-filter")
def my_func(value, some_other_arg):
    # Do something with `value`
    ...
    return value

# After filters have been created, the result of calling all filter callbacks is obtained by running:
hooks.filters.apply("my-filter", initial_value, some_other_argument_value)
tutor.hooks.filters.add_item(name, item, priority=None)

Convenience function to add a single item to a filter that returns a list of items.

Parameters

  • name (str) – filter name.

  • item (object) – item that will be appended to the resulting list.

  • priority (int) – see add.

Return type

None

Usage:

from tutor import hooks

hooks.filters.add_item("my-filter", "item1")
hooks.filters.add_item("my-filter", "item2")

assert ["item1", "item2"] == hooks.filters.apply("my-filter", [])
tutor.hooks.filters.add_items(name, items, priority=None)

Convenience function to add multiple item to a filter that returns a list of items.

Parameters

  • name (str) – filter name.

  • items (list[object]) – items that will be appended to the resulting list.

  • priority (t.Optional[int]) –

Return type

None

Usage:

from tutor import hooks

hooks.filters.add_items("my-filter", ["item1", "item2"])

assert ["item1", "item2"] == hooks.filters.apply("my-filter", [])
tutor.hooks.filters.apply(name, value, *args, **kwargs)

Apply all declared filters to a single value, passing along the additional arguments.

The return value of every filter is passed as the first argument to the next callback.

Usage:

results = filters.apply("my-filter", ["item0"])
Return type

same as the type of value.

Parameters

  • name (str) –

  • value (object) –

  • args (Any) –

  • kwargs (Any) –

tutor.hooks.filters.apply_from_context(context, name, value, *args, **kwargs)

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

Parameters

  • context (t.Optional[str]) –

  • name (str) –

  • value (T) –

  • args (P.args) –

  • kwargs (P.kwargs) –

Return type

T

tutor.hooks.filters.iterate(name, *args, **kwargs)

Convenient function to iterate over the results of a filter result list.

This pieces of code are equivalent:

for value in filters.apply("my-filter", [], *args, **kwargs):
    ...

for value in filters.iterate("my-filter", *args, **kwargs):
    ...
Rtype iterator[T]

iterator over the list items from the filter with the same name.

Parameters

  • name (str) –

  • args (Any) –

  • kwargs (Any) –

tutor.hooks.filters.iterate_from_context(context, name, *args, **kwargs)

Same as iterate() but apply only callbacks from a given context.

Parameters

  • context (Optional[str]) –

  • name (str) –

  • args (Any) –

  • kwargs (Any) –

Return type

Iterator[T]

tutor.hooks.filters.clear(name, context=None)

Clear any previously defined filter with the given name and context.

Parameters

  • name (str) –

  • context (Optional[str]) –

Return type

None

tutor.hooks.filters.clear_all(context=None)

Clear any previously defined filter with the given context.

Parameters

context (Optional[str]) –

Return type

None

class tutor.hooks.filters.Filter(name)

Filter hooks have callbacks that are triggered as a chain.

Several filters are defined across the codebase. Each filters is given a unique name. To each filter are associated zero or more callbacks, sorted by priority.

This is the typical filter lifecycle:

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

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

  3. Call the filter callbacks with method apply() (or function apply()).

The result of each callback is passed as the first argument to the next one. Thus, the type of the first argument must match the callback return type.

The T and P type parameters of the Filter class correspond to the expected signature of the filter callbacks. T is the type of the first argument (and thus the return value type as well) and P is the signature of the other arguments.

For instance, Filter[str, [int]] means that the filter callbacks are expected to take two arguments: one string and one integer. Each callback must then return a string.

This strong typing makes it easier for plugin developers to quickly check whether they are adding and calling filter callbacks correctly.

class tutor.hooks.filters.FilterTemplate(name)

Filter templates are for filters for which the name needs to be formatted before the filter can be applied.

Similar to tutor.hooks.actions.ActionTemplate, filter templates are used to generate Filter objects for which the name matches a certain template.