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
- 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(): ... named_filter.do()
- Parameters
name (str) –
- Return type
- tutor.hooks.filters.add(name)
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.
- Return type
Callable[[Callable[[…], Any]], Callable[[…], Any]]
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)
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.
- 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)
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.
- 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, context=None, **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) –
context (Optional[str]) –
kwargs (Any) –
- tutor.hooks.filters.iterate(name, *args, context=None, **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) –
context (Optional[str]) –
kwargs (Any) –
- 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)
Each filter is associated to a name and a list of callbacks.
- Parameters
name (str) –
- Return type
None
- 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.
- Parameters
name (str) –