API Documentation

class filters.base.BaseFilter

Base functionality for all Filters, macros, etc.

CODE_EXCEPTION = 'exception'
apply(value: Any) → T | None

Applies the filter to a value.

property harness: FilterHarness | None

Returns the harness in which this filter is running (if applicable).

property key: str

Returns the key associated with this filter.

property parent: BaseFilter[Any] | None

Returns the parent Filter.

classmethod resolve(the_filter: BaseFilter | Callable[[], BaseFilter] | None, parent: BaseFilter[Any] | None = None, key: str | None = None) → BaseFilter

Converts a filter-compatible value into a consistent type.

sub_key(sub_key: str) → str

Returns a copy of this filter’s key with an additional subkey appended.

templates: dict[str, str] = {'exception': 'An error occurred while processing this value.'}
exception filters.base.BaseFilterError(filter_: BaseFilter[Any], value: Any, code: str, context: Mapping[str, Any] | None = None)

Base class for errors that occur when filtering values.

Parameters:

  • filter – The filter that raised the error.

  • value – The value provided to the filter.

  • code – Corresponding error code. Should match one of the keys in filter_.templates.

  • context – Additional values that could be useful for troubleshooting cases where the filter is incorrectly rejecting values.

class filters.base.FilterChain(start_filter: BaseFilter | None = None)

Allows chaining multiple filters together so that they are treated as a single filter.

templates: dict[str, str] = {'exception': 'An error occurred while processing this value.'}
exception filters.base.FilterError(filter_: BaseFilter[Any], value: Any, code: str, context: Mapping[str, Any] | None = None, template_vars: Mapping[str, str] | None = None)

Indicates that a given value could not be filtered because it failed validation or was otherwise invalid, rather than because of a problem with the filter code itself.

Think of a FilterError like an HTTP 400 response.

Parameters:

  • filter – The filter that raised the error.

  • value – The value provided to the filter.

  • code – Corresponding error code. Should match one of the keys in filter_.templates.

  • context – Additional values that could be useful for troubleshooting cases where the filter is incorrectly rejecting values.

  • template_vars – If reason contains interpolation placeholders, this parameter contains the corresponding values to insert.

class filters.base.FilterHarness

Runs filters within a harness, so that it can catch and handle errors.

handle_exception(e: UncaughtException) → Any

Handles an uncaught exception that occurred when the filter ran.

Returns:

Replacement value that the filter should return (usually None).

abstract handle_filter_error(e: BaseFilterError) → Any

Handles a filter error (i.e. invalid incoming value).

Returns:

Replacement value that the filter should return (usually None).

class filters.base.NoOp

Filter that does nothing, used when you need a placeholder Filter in a FilterChain.

templates: dict[str, str] = {'exception': 'An error occurred while processing this value.'}
class filters.base.Type(allowed_types: type | tuple[type, ...], allow_subclass: bool = True)

Checks the type of the incoming value.

Parameters:

  • allowed_types – The type (or types) that incoming values are allowed to have.

  • allow_subclass – Whether to allow subclasses when checking for type matches.

CODE_WRONG_TYPE = 'wrong_type'
static get_type_name(type_: type) → str

Returns the name of the specified type.

templates: dict[str, str] = {'exception': 'An error occurred while processing this value.', 'wrong_type': '{incoming} is not valid (allowed types: {allowed}).'}
exception filters.base.UncaughtException(filter_: BaseFilter[Any], value: Any, e: Exception, context: Mapping[str, Any] | None = None)

Indicates that a given value could not be filtered because of a problem with the filter code itself.

Thin of UncaughtException like an HTTP 500 response.

Parameters:

  • filter – The filter that raised the error.

  • value – The value provided to the filter.

  • e – The exception object.

  • context – Additional values that could be useful for troubleshooting the error.