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.

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

Create an action with method get().
Add callbacks with method add().
Call the filter callbacks with method 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.

add(priority=None)

Decorator to add a filter callback.

Callbacks are added by increasing priority. Highest priority score are called last.

Parameters:: 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 must be called last should have a priority of 100.
Return type:: Callable[[Callable[[tutor.core.hooks.filters.T1, tutor.core.hooks.filters.T2], tutor.core.hooks.filters.T1]], Callable[[tutor.core.hooks.filters.T1, tutor.core.hooks.filters.T2], tutor.core.hooks.filters.T1]]

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

Usage:

@my_filter.add()
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:

final_value = my_filter.apply(initial_value, some_other_argument_value)

add_item(item, priority=None)

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

This method is only valid for filters that return list of items.

Parameters:

item (object) – item that will be appended to the resulting list.
priority (int) – see Filter.add.
self (Filter[list[L], T2]) –

Return type:

None

Usage:

my_filter.add_item("item1")
my_filter.add_item("item2")

assert ["item1", "item2"] == my_filter.apply([])

add_items(items, priority=None)

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

This method is only valid for filters that return list of items.

This is a similar method to Filter.add_item except that it can be used to add multiple items at the same time. If you find yourself calling add_item multiple times on the same filter, then you probably want to use a single call to add_items instead.

Parameters:

name – filter name.
items (list[object]) – items that will be appended to the resulting list.
self (Filter[list[L], T2]) –
priority (t.Optional[int]) –

Return type:

None

Usage:

my_filter.add_items(["item1", "item2"])
my_filter.add_items(["item3", "item4"])

assert ["item1", "item2", "item3", "item4"] == my_filter.apply([])

The following are equivalent:

# Single call to add_items
my_filter.add_items(["item1", "item2"])

# Multiple calls to add_item
my_filter.add_item("item1")
my_filter.add_item("item2")

apply(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:

value (object) –
args (T2.args) –
kwargs (T2.kwargs) –

apply_from_context(context, value, *args, **kwargs)

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

If context is None then it is ignored.

Parameters:

context (t.Optional[str]) –
value (T1) –
args (T2.args) –
kwargs (T2.kwargs) –

Return type:

T1

clear(context=None)

Clear any previously defined filter with the given context.

Parameters:: context (Optional[str]) –
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:: Filter[t.Any, t.Any]

iterate(*args, **kwargs)

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

This method is only valid for filters that return list of items.

This pieces of code are equivalent:

for value in my_filter.apply([], *args, **kwargs):
    ...

for value in my_filter.iterate(*args, **kwargs):
    ...

Rtype iterator[T]:

iterator over the list of items from the filter

Parameters:

self (Filter[list[L], T2]) –
args (T2.args) –
kwargs (T2.kwargs) –

iterate_from_context(context, *args, **kwargs)

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

Parameters:

self (Filter[list[L], T2]) –
context (t.Optional[str]) –
args (T2.args) –
kwargs (T2.kwargs) –

Return type:

t.Iterator[L]

class tutor.core.hooks.FilterTemplate(name)

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

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

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

filter_template = FilterTemplate("namespace:{0}")
named_filter = filter_template("name")

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

named_filter.apply(42)

class tutor.core.hooks.filters.T1

class tutor.core.hooks.filters.T2

class tutor.core.hooks.filters.L