Install & Compatibility
Where this runs
tested against v0.4.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 1.737s · 30.4MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 3.2s · import 1.599s · 31MB
29MB installed
● package 29MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
parse
✓ from pygeofilter.parsers.cql2_text import parse
✗ from pygeofilter.parsers.cql2 import parse
The `cql2` module was split into format-specific parsers. Use `cql2_text` for text-based CQL2 or `cql2_json` for JSON.
evaluate
✓ from pygeofilter.evaluate import evaluate
to_sqlalchemy
✓ from pygeofilter.backends.sqlalchemy import to_sqlalchemy
This quickstart demonstrates how to parse a CQL2-TEXT filter string and then evaluate it against a Python dictionary representing a data item's properties. It showcases both a successful and a failing evaluation.
from pygeofilter.parsers.cql2_text import parse
from pygeofilter.evaluate import evaluate
# Define a CQL2 filter expression
cql_filter_string = "(name = 'test-feature' AND temperature > 25) OR (id IN ('A1', 'B2'))"
# Parse the filter expression
parsed_filter = parse(cql_filter_string)
# Define a data item (dictionary representing feature properties)
data_item = {
"name": "test-feature",
"temperature": 28.5,
"id": "A1",
"timestamp": "2024-01-01T10:00:00Z"
}
# Evaluate the filter against the data item
result = evaluate(parsed_filter, data_item)
print(f"Filter expression: {cql_filter_string}")
print(f"Data item: {data_item}")
print(f"Evaluation result: {result}")
# Example with a different data item (should fail the filter)
data_item_fail = {
"name": "other-feature",
"temperature": 20.0,
"id": "C3",
"timestamp": "2024-01-01T11:00:00Z"
}
result_fail = evaluate(parsed_filter, data_item_fail)
print(f"Evaluation result for other item: {result_fail}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pygeofilter.parsers.cql2'
You are attempting to import from an old or incorrect path for CQL2 parsers. The `cql2` module was refactored into format-specific parsers.
fixUse `from pygeofilter.parsers.cql2_text import parse` for text-based CQL2 filters or `from pygeofilter.parsers.cql2_json import parse` for JSON-based CQL2 filters.
lark.exceptions.UnexpectedInput: No rule matches the current input
The filter expression provided is syntactically incorrect according to the OGC standard (e.g., CQL2-TEXT) or contains elements not supported by the parser's grammar.
fixCarefully review your filter string for typos, incorrect operators, mismatched parentheses, or unsupported functions. Ensure it strictly adheres to the specified OGC filter standard (e.g., CQL2-TEXT specification) that the parser expects.
sqlalchemy.exc.CompileError: (in _create_bind_param) Type annotation for parameter '...' must be a SQLAlchemy Type, not 'datetime'
When translating a filter to a SQLAlchemy expression, a type mismatch occurred between a Python value in your filter and what SQLAlchemy expects for a column type or bind parameter. This is common with `datetime` or other complex types.
fixEnsure the Python data types used in your filter values are compatible with the corresponding SQLAlchemy column types. For `datetime` objects, ensure consistent timezone awareness (or naivety) and proper handling during the `to_sqlalchemy` conversion, possibly by providing explicit type mappers if needed for custom types.
Upgrade
Version history
0.4.0latest on PyPI · released Jun 8, 2026
Audit
Dependencies
larkrequiredRequired for parsing filter expressions.
shapelyrequiredRequired for geometry operations in filter evaluation.
sqlalchemyoptionalRequired for generating SQLAlchemy expressions from filters, used by the 'sql' extra.
sqlmodeloptionalRequired for generating SQLModel queries from filters, used by the 'sql' extra.