Filters

Filter expressions

Changed in version 0.11: Meta.allowed_filters has been renamed to Meta.filters and the format for filter expressions has changed.

Meta.filters may contain an expression used to specify which properties of items belonging to a resource can be filtered, and how.

The filters expression can be a bool or a dict keyed by field names. The values of the dict can be either a bool or a list of filter names. The '*' attribute is a wildcard for any remaining field names.

For example, the following allows all filters:

filters = True

The following allows filtering on the "name" field:

filters = {
    "name": True
}

The following allows filtering by equals and not equals on the "name" field:

filters = {
    "name": ['eq', 'ne']
}

In addition it is also possible to specify custom filters this way:

filters = {
    "name": {
        "text": MyTextFilter
    },
    "*": True
}

Built-in default filters

Filters are implemented for each contributed backend individually. The following filter classes are implemented for most or all backends:

Name	Filter class	Description	Used with
—	filters.EqualFilter	Equal	fields.Boolean, fields.String, fields.Integer, fields.Number, fields.ToOne, fields.Date, fields.DateTime, fields.DateString, fields.DateTimeString
ne	filters.NotEqualFilter	Not equal	fields.Boolean, fields.String, fields.Integer, fields.Number, fields.ToOne
in	filters.InFilter	In (expects an Array)	fields.String, fields.Integer, fields.Number, fields.Date, fields.DateTime, fields.DateString, fields.DateTimeString
contains	filters.ContainsFilter	Contains	fields.Array, fields.ToMany
lt	filters.LessThanFilter	Less than	fields.String, fields.Integer, fields.Number, fields.Date, fields.DateTime, fields.DateString, fields.DateTimeString
gt	filters.GreaterThanFilter	Greater than	fields.String, fields.Integer, fields.Number, fields.Date, fields.DateTime, fields.DateString, fields.DateTimeString
lte	filters.LessThanEqualFilter	Less than or equal	fields.String, fields.Integer, fields.Number, fields.Date, fields.DateTime, fields.DateString, fields.DateTimeString
gte	filters.GreaterThanEqualFilter	Greater than or equal	fields.String, fields.Integer, fields.Number, fields.Date, fields.DateTime, fields.DateString, fields.DateTimeString
contains	filters.StringContainsFilter	Contains (String)	fields.String
icontains	filters.StringIContainsFilter	Contains (String, case-insensitive)	fields.String
startswith	filters.StartsWithFilter	Starts with	fields.String
endswith	filters.EndsWithFilter	Ends with	fields.String
istartswith	filters.IStartsWithFilter	Starts with (case-insensitive)	fields.String
iendswith	filters.IEndsWithFilter	Ends with (case-insensitive)	fields.String
between	filters.DateBetweenFilter	Date between	fields.Date, fields.DateTime, fields.DateString, fields.DateTimeString

Note

filters.EqualFilter uses both the keys 'eq' and None. This is so that you can write an equality comparison both ways:

GET /user?where={"name": "foo"}
GET /user?where={"name": {"$eq": "foo"}}

filters.BaseFilter

New in version 0.11.

class flask_potion.filters.BaseFilter(name, field=None, attribute=None)

Base-class for all filter types. Filters are specified on a field-level. Each backend implements its own filters and defaults. Custom filters can be specified using the ModelResource.Meta.filter configuration.

Named and unnamed filters:

EqualFilter is a special filter type. This is because an equality condition is can be written in the format {"property": condition}, whereas every other filter needs to be written as {"property": {"$filter": condition}}. To implement this, a filter can be either named or unnamed.

Due to the way the equality comparison is done, users need to be watchful when comparing objects. Some object comparisons can be ambiguous, e.g. {"foo": {"$foo": "bar"}}. If a condition contains an object with exactly one property, the name of the property will be matched against all valid filters for that field. If necessary, the equality filter can be declared explicitly to avoid comparing against the wrong filter, e.g. {"foo": {"$eq": {"$foo": "bar"}}}.

Multiple filters can have the same filter name so long as they are not valid for the same field types. For example, StringContainsFilter for strings and ContainsFilter for arrays.

attribute

Attribute to filter on. Defaults to field.attribute.

field

Field to filter on.

name

Name of the filter as specified in the where object in the GET request. A filter foo on field field is specified as: ?where={“field”: {“$foo”: filter-expression}}

op(a, b)

Matches an attribute of an item a against a value b provided by the user.

Parameters:

• a – item’s attribute’s value
• b – value filtered by

Returns:

True on match, False otherwise

schema()

Returns the schema for this filter.

This depends on the name of the filter. If the filter is named, it needs to be formatted as {“$name”: schema}. Usually the equality filter is unnamed and all other filters are named.