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.Filter

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.FilterTemplate

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) –