Python

Python API documentation for the cql2 package. Install from PyPI:

python -m pip install cql2

API

cql2.parse_file(path)

Parses CQL2 from a filesystem path.

Parameters:

• path (PathLike | str) –

  The input path

Returns:

• Expr ( Expr ) –

  The CQL2 expression

Examples:

>>> from cql2 import parse_file
>>> expr = parse_file("examples/text/example01.txt")

cql2.parse_json(s)

Parses cql2-json.

Parameters:

• s (str) –

  The cql2-json string

Returns:

• Expr ( Expr ) –

  The CQL2 expression

Raises:

• ParseError –

  Raised if the string does not parse as cql2-json

Examples:

>>> from cql2 import parse_json
>>> expr = parse_json('{"op":"=","args":[{"property":"landsat:scene_id"},"LC82030282019133LGN00"]}')

cql2.parse_text(s)

Parses cql2-text.

Parameters:

• s (str) –

  The cql2-text

Returns:

• Expr ( Expr ) –

  The CQL2 expression

Raises:

• ParseError –

  Raised if the string does not parse as cql2-text

Examples:

>>> from cql2 import parse_text
>>> expr = parse_text("landsat:scene_id = 'LC82030282019133LGN00'")

cql2.Expr(cql2)

A CQL2 expression.

The cql2 can either be a cql2-text string, a cql2-json string, or a cql2-json dictionary.

Parameters:

• cql2 (str | dict[str, Any]) –

  The input CQL2

Examples:

>>> from cql2 import Expr
>>> expr = Expr("landsat:scene_id = 'LC82030282019133LGN00'")
>>> expr = Expr({"op":"=","args":[{"property":"landsat:scene_id"},"LC82030282019133LGN00"]})

__add__(other)

Combines two cql2 expressions using the AND operator.

Parameters:

• other (Expr) –

  The other expression

Returns:

• Expr ( Expr ) –

  The combined expression

Examples:

>>> from cql2 import Expr
>>> expr1 = Expr("landsat:scene_id = 'LC82030282019133LGN00'")
>>> expr2 = Expr("landsat:cloud_cover = 10")
>>> expr = expr1 + expr2

__eq__(other)

Compares two cql2 expressions for structural equality.

Comparing against anything that is not an Expr returns False.

Parameters:

• other (object) –

  The object to compare against

Returns:

• bool ( bool ) –

  True if both are equivalent expressions, False otherwise

Examples:

>>> from cql2 import Expr
>>> Expr("landsat:cloud_cover = 10") == Expr("landsat:cloud_cover = 10")
True

__repr__()

Returns a debugging representation of this expression.

Returns:

• str ( str ) –

  The representation

Examples:

>>> from cql2 import Expr
>>> repr(Expr("landsat:cloud_cover = 10"))
'Expr(landsat:cloud_cover = 10)'

__str__()

Returns the cql2-text representation of this expression.

Returns:

• str ( str ) –

  The cql2-text

Examples:

>>> from cql2 import Expr
>>> str(Expr("landsat:cloud_cover = 10"))
'landsat:cloud_cover = 10'

matches(item)

Matches this expression against an item.

Parameters:

• item (dict[str, Any]) –

  The item to match against

Returns:

• bool ( bool ) –

  True if the expression matches the item, False otherwise

reduce(item=None)

Reduces this expression against an item.

Parameters:

• item (dict[str, Any] | None, default: None ) –

  The item to reduce against

Returns:

• Expr ( Expr ) –

  The reduced expression

Examples:

>>> from cql2 import Expr
>>> expr = Expr("true AND true").reduce()
>>> expr.to_text()
'true'

to_json()

Converts this cql2 expression to a cql2-json dictionary.

Returns:

• dict[str, Any] –

  dict[str, Any]: The cql2-json

Examples:

>>> from cql2 import Expr
>>> expr = Expr("landsat:scene_id = 'LC82030282019133LGN00'")
>>> expr.to_json()
{'op': '=', 'args': [{'property': 'landsat:scene_id'}, 'LC82030282019133LGN00']}

to_sql()

Converts this cql2 expression to a SQL query.

Returns:

• str ( str ) –

  The SQL query

Examples:

>>> from cql2 import Expr
>>> expr = Expr("landsat:scene_id = 'LC82030282019133LGN00'")
>>> expr.to_sql()
'"landsat:scene_id" = \'LC82030282019133LGN00\''

to_text()

Converts this cql2 expression to cql2-text.

Returns:

• str ( str ) –

  The cql2-text

Examples:

>>> from cql2 import Expr
>>> expr = Expr({"op":"=","args":[{"property":"landsat:scene_id"},"LC82030282019133LGN00"]})
>>> expr.to_text()
"landsat:scene_id = 'LC82030282019133LGN00'"

validate()

Validates this expression using json-schema.

Raises:

• ValidationError –

  Raised if the validation fails

Examples:

>>> from cql2 import Expr
>>> expr = Expr("landsat:scene_id = 'LC82030282019133LGN00'")
>>> expr.validate()

cql2.ParseError

Bases: Exception

An error raised when cql2 parsing fails.

cql2.ValidationError

Bases: Exception

An error raised when cql2 json-schema validation fails.