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 |
contains | filters.StringIContainsFilter |
Contains (String, case-insensitive) | fields.String |
startswith | filters.StartsWithFilter |
Starts with | fields.String |
endswith | filters.IStartsWithFilter |
Ends with | fields.String |
istartswith | filters.EndsWithFilter |
Starts with (case-insensitive) | fields.String |
iendswith | filters.IEndsWithFilter |
Ends with (case-insensitive) | fields.String |
between | filters.DateBetweenFilter |
Ends with (case-insensitive) | 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 andContainsFilter
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 filterfoo
on fieldfield
is specified as: ?where={“field”: {“$foo”: filter-expression}}
-
op
(a, b)¶ Matches an attribute of an item
a
against a valueb
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.
-