A list with built in filtering syntax.
Project description
filterablelist
A subclass of Python's built in list
, with two additional methods inspired by the filter
and exclude
methods from the Django queryset. These methods allows for complex list filtering with a very simple syntax.
Use examples
Create an example list:
from filterablelist import FilterableList
class MyClass:
def __init__(self, x, y, z):
self.x = x
self.y = y
self.z = z
def __repr__(self) -> str:
return f"(x:{self.x}, y:{self.y}, z:{self.z})"
fl = FilterableList([
MyClass(1, 1, 1),
MyClass(1, 1, 2),
MyClass(2, 1, 3),
{"x": 1, "y": 2, "z": 1}
])
Make new lists with simple queries:
print(fl.filter(x=1))
print(fl.filter(x=1, y=1))
print(fl.filter(x=1, y=1, require_all=False))
print(fl.filter(y__in=[2,5,7]))
print(fl.exclude(x=1))
print(fl.exclude(x=1, y=1))
print(fl.exclude(x=1, y=1, require_all=False))
print(fl.exclude(y__in=[2,5,7]))
# Output
>>> [(x:1, y:1, z:1), (x:1, y:1, z:2), {'x': 1, 'y': 2, 'z': 1}]
>>> [(x:1, y:1, z:1), (x:1, y:1, z:2)]
>>> [(x:1, y:1, z:1), (x:1, y:1, z:2), (x:2, y:1, z:3), {'x': 1, 'y': 2, 'z': 1}]
>>> [{'x': 1, 'y': 2, 'z': 1}]
>>> [(x:2, y:1, z:3)]
>>> [(x:2, y:1, z:3), {'x': 1, 'y': 2, 'z': 1}]
>>> []
>>> [(x:1, y:1, z:1), (x:1, y:1, z:2), (x:2, y:1, z:3)]
Use comparison operator postfixes to make more complex queries:
print(fl.filter(z__lte=2))
print(fl.exclude(x__lt=2))
print(fl.filter(x__ne=1))
# Output
>>> [(x:1, y:1, z:1), (x:1, y:1, z:2), {'x': 1, 'y': 2, 'z': 1}]
>>> [(x:2, y:1, z:3)]
>>> [(x:2, y:1, z:3)]
Methods
Note: All methods and properties of the built-in list
are also available.
filter(check_subscriptable=True
, require_all=True
, **kwargs
)
Arguments
check_subscriptable
: Boolean, True by default. If True, the filter will match against subscriptable indexes where available, as well as object properties. Set to False to only match against object properties.
require_all
: Boolean, True by Default. When True, only objects that match all arguments will be included in the new list (similar to using AND
in an SQL query.) When set to False, all objects that match any of the arguments will be included in the new list (similar to using OR
in an SQL query.)
**kwargs
: Any number of key-value pairs that you wish to filter the list by.
Description
The filter
method takes any number of key-value pairs as arguments and returns a new FilterableList containing only the matching objects. By default, all arguments have to match for an object to be included, and both object properties and subscriptable indexes will be used to try to match objects. This default behaviour can be changed by setting require_all
and/or check_subscriptable
to False
per your requirements.
exclude(check_subscriptable=True
, require_all=True
, **kwargs
)
Arguments
check_subscriptable
: Boolean, True by default. If True, exclude will match against subscriptable indexes where available, as well as object properties. Set to False to only match against object properties.
require_all
: Boolean, True by Default. When True, only objects that match all arguments will be excluded in the new list (similar to using AND
in an SQL query.) When set to False, all objects that match any of the arguments will be excluded in the new list (similar to using OR
in an SQL query.)
**kwargs
: Any number of key-value pairs that you want to use to exclude objects from the new list.
Description
Basically the same as filter
except that items that match the query will be excluded from the new list, rather than included.
Comparison Operators
By default, both filter
and exclude
will match object properties to arguments using the equality operator ´==´, but by adding a comparison postfix to the keys in your query, you can create more complex filters. The comparison operators available are:
- __gt : (Greater than) Uses Python's
>
operator for comparison. - __gte : (Greater than or equal to) Uses Python's
>=
operator for comparison. - __lt : (Less than) Uses Python's
<
operator for comparison. - __lte : (Less than or equal to) Uses Python's
<=
operator for comparison. - __ne : (Not equal to) Uses Python's
!=
operator for comparison. - __in : (Not equal to) Uses Python's
in
operator for comparison.
Examples
# name is equal to "Isaac" (default comparison without postfix)
.filter(name="Isaac")
# count is greater than 5
.filter(count__gt=5)
# age is greater than or equal to 111
.filter(age__gte=111)
# clicks is less than 19
.filter(clicks__lt=19)
# score is less than or equal to 1200
.filter(score__lte=1200)
# state is not equal to None
.filter(state__ne=None)
# id is in [12, 13, 14]
.filter(id__in=[12, 13, 14])
Query Chaining
Both filter
and exclude
returns a new FilterableList, making it possible to chain queries together if needed.
from filterablelist import FilterableList
fl = FilterableList([
{"a": 1, "b": False, "c": None},
{"a": 2, "b": False, "c": None},
{"a": 1, "b": False, "c": 5},
{"a": 1, "b": False, "c": True},
{"a": 1, "d": []}
])
new_fl = fl.filter(a=1).exclude(c__bte=4).filter(c__ne=True)
print(new_fl)
# Output
# [{'a': 1, 'b': False, 'c': None}, {'a': 1, 'b': False, 'c': 5}]
Performance
Most normal list operations have no performance drop at all compared to a regular list. Only the operations that return a new list, such as slice
and copy
will have any drop in performance, but even in those cases it's very negligible (on the scale of 20%-ish.)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for filterablelist-0.1.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ba9296c9123ab7bb0c0b78a5d7f1a69c1f739584cd06ed3006f2ab58eba45852 |
|
MD5 | cc815494de7c1ef5156de4bcbc97e114 |
|
BLAKE2b-256 | 94ee7060449188541be993b08e44282e7d7baab62086b8514c1cceeaaa96adca |