Filtration
A library for parsing arbitrary filters provided by a UI or as a Query String
Features
Compatible with Python 3
Parses human readable filters
Get Filtration
pip install git+https://github.com/HurricaneLabs/filtration.gitRun the tests
You must install nose2, then run:
git clone https://github.com/HurricaneLabs/filtration.git
cd filtration
nose2Usage
Filtration is used to parse “filter expressions” made up of one or more “statements”. Each statement is comprised of a “left hand side” (LHS), and optionally an operator and a “right hand side” (RHS). When no operator and RHS are specified, a special “LHS exists” syntax is assumed. See “Expression Evaluation” for more details.
Statements are joined together using “AND” or “OR” to form an expression. Parentheses may be used when joining statements together to enforce precedence. For example:
>>> from filtration import Expression
>>> Expression.parseString("a and b or c")
((a and b) or c)
>>> Expression.parseString("a and (b or c)")
(a and (b or c))
>>>Filtration can also be used to parse query string syntax. See below for more information.
Expression Format
Operators
These operators control comparison of the LHS to the RHS. If the operator is omitted (and thus the RHS is also omitted), the statement returns True IF the symbol in the LHS exists at all.
Equal (“==”)
Not equal (“!=”)
Less than (“<”)
Less than or equal (“<=”)
Greater than (“>”)
Greater than or equal (“>=”)
- Contains (“in”)
RHS must be a list or a Subnet
- Regular expression (“=~”)
RHS must be a regex token
Tokens
These tokens are used in the LHS or RHS of a statement.
Regex
A regular expression must be wrapped in “/” and may contain the characters “i”, “m” or “s” after the closing “/” to represent the corresponding regex flags. Examples:
/abc/ /^abc/i /^abc$/ms
Subnet
A subnet is an IPv4 subnet in CIDR notation:
127.0.0.0/8 192.168.0.0/24
Symbol
A symbol is represented as a bare, unquoted string. It begins with a letter or underscore, and can be followed by any number of letters, numbers, dots (“.”) or underscores. Dots have special meaning and are used to indicate dictionary traversal (see Expression Evaluation below).
Value
A value can be a date, time, date/time, quoted string, or an integer. A date is represented in YYYY-MM-DD format (not quoted), and is interpreted to mean midnight on that date. A time is represented in HH:MM:SS format (also not quoted), and is interpreted to mean that time on whatever day the filter is evaluated. A date/time is represented in YYYY-MM-DDTHH:MM:SS format, where the “T” is optional and could instead be represented by a space. This format is roughly ISO 8601, but is lacking microseconds.
List
A list is two-or-more Value tokens separated by commas.
Expression Evaluation
Expression objects are callable, with a single “context” argument. When used in this way, either true or false is returned, based on whether the “context” matches the filter. For example, given this context:
>>> c = {"a": 1, "b": 2, "c": 3}and this expression:
>>> expr = Expression.parseString("a == 1 and b == 2")calling the expression would return True:
>>> expr(c)
True
>>>whereas this expression would return False:
>>> expr = Expression.parseString("a == 2 and b == 2")
>>> expr(c)
False
>>>When no operator/RHS is provided, the statement resolves to true if the LHS key exists in the context. For example:
>>> c = {"a": 1, "b": 2, "c": 3}
>>> expr = Expression.parseString("a")
>>> expr(c)
True
>>> expr = Expression.parseString("d")
>>> expr(c)
False
>>>Dictionary Traversal
Symbols are able to traverse nested dictionaries in the context. Given this context:
>>> c = {"a": {"b": {"c": 1}}}This expression will return true:
>>> expr = Expression.parseString("a.b.c == 1")
>>> expr(c)
True
>>>2 maintainers
Metadata
2 maintainers
Release files for filtration 2.3.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| filtration-2.3.2.tar.gz | 6.6 kB | With provenance | Details for filtration-2.3.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| filtration-2.3.2-py3-none-any.whl | Python 3 | none | any | Details for filtration-2.3.2-py3-none-any.whl |
Total release size: 11.5 kB
Release files / filtration-2.3.2.tar.gz
| Download URL | filtration-2.3.2.tar.gz |
|---|---|
| Size | 6.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4046329684f53653a042c7168dda9f46d7e6b4a59aa6f7ab20566976ea1fc3ef
|
|
BLAKE2b-256 checksum How to use checksums |
538b225d12a29ce327df9930312ef40658aca7eed9723f5249ec2e9b62a747fc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 5, 2025.
Transparency logRelease files / filtration-2.3.2-py3-none-any.whl
| Download URL | filtration-2.3.2-py3-none-any.whl |
|---|---|
| Size | 4.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cd30680cfce84eb50f54738c1f9cc9b90fef7fe4b3eb576d00eeccd47577b59e
|
|
BLAKE2b-256 checksum How to use checksums |
ed7c291cb1fa36ba57a8a16cb9e7af3389bb6103c08e6619fc7d93b39c611403
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.9
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 5, 2025.
Transparency logSecurity for filtration 2.3.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for filtration-2.3.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 5, 2025.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
