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:
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 generateFilter
objects for which the name matches a certain template.