CQL2 JSON Pydantic

Pydantic v2 models for building CQL2 JSON filters.

Quick start

pip install cql2json-pydantic

from cql2json_pydantic import BinaryComparisonPredicate, BinaryComparisonPredicateOp, PropertyRef

query = BinaryComparisonPredicate(
    op=BinaryComparisonPredicateOp.EQUAL,
    args=[PropertyRef(property="city"), "Toronto"],
)
print(query.model_dump_json(exclude_none=True))

Output:

{"op":"=","args":[{"property":"city"},"Toronto"]}

Use model_dump_json(indent=2, exclude_none=True) for formatted JSON, or model_dump(mode="json", exclude_none=True) for a JSON-compatible Python dictionary.

See more filter examples and their JSON output.

GeoJSON models accept coordinates directly as lists or tuples:

import cql2json_pydantic as cql

point = cql.Point((-115.81, 37.24))
line = cql.Linestring(((0, 0), (1, 1)))
polygon = cql.Polygon([[(0, 0), (1, 0), (1, 1), (0, 0)]])
points = cql.Multipoint(((0, 0), (1, 1)))
lines = cql.Multilinestring([[(0, 0), (1, 1)]])
polygons = cql.Multipolygon([[[(0, 0), (1, 0), (1, 1), (0, 0)]]])
collection = cql.Geometrycollection((point, line))

Keyword construction such as cql.Point(coordinates=[-115.81, 37.24]) remains supported, as do existing coordinate wrapper models. Additional fields are keyword arguments, for example cql.Point((0, 0), bbox=[-1, -1, 1, 1]). These remain Pydantic models with the same validation and serialization methods.

Project conventions

This project is templated a Hatch-based Python package with:

• Apache-2.0 license
• Keep a Changelog-compatible CHANGELOG.md
• Diátaxis documentation under docs/
• top-level mkdocs.yaml
• Taskfile integration with Terradue/taskfile-utils
• GitHub Actions CI

Documentation

Project documentation: https://terradue.github.io/cql2json-pydantic/

Contribute

Submit a Github issue if you have comments or suggestions.

Local quality checks

Install Hatch and Taskfiles then install the Git hook:

task quality:pre-commit:install

Every commit runs Ruff (including the configured McCabe complexity limit), Ruff formatting, strict mypy checks, and the pytest suite.

Run the complete hook explicitly with:

task quality:pre-commit:run

License