cql2 0.3.7

Parse, validate, and convert Common Query Language (CQL2) text and JSON
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176

from typing import Any
from os import PathLike

def parse_file(path: PathLike | str) -> Expr:
    """Parses CQL2 from a filesystem path.

    Args:
        path (PathLike | str): The input path

    Returns:
        Expr: The CQL2 expression

    Examples:
        >>> from cql2 import Expr
        >>> expr = Expr.parse_file("fixtures/text/example01.txt")
    """

def parse_text(s: str) -> Expr:
    """Parses cql2-text.

    Args:
        s (str): The cql2-text

    Returns:
        Expr: The CQL2 expression

    Raises:
        ParseError: Raised if the string does not parse as cql2-text

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

def parse_json(s: str) -> Expr:
    """Parses cql2-json.

    Args:
        s (str): The cql2-json string

    Returns:
        Expr: The CQL2 expression

    Raises:
        ParseError: Raised if the string does not parse as cql2-json

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

class Expr:
    def __init__(self, cql2: str | dict[str, Any]) -> None:
        """A CQL2 expression.

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

        Args:
            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"]})
        """

    def validate(self) -> None:
        """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()
        """

    def matches(self, item: dict[str, Any]) -> bool:
        """Matches this expression against an item.

        Args:
            item (dict[str, Any]): The item to match against

        Returns:
            bool: True if the expression matches the item, False otherwise
        """

    def reduce(self, item: dict[str, Any] | None = None) -> Expr:
        """Reduces this expression against an item.

        Args:
            item (dict[str, Any] | None): The item to reduce against

        Returns:
            Expr: The reduced expression

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

    def to_json(self) -> dict[str, Any]:
        """Converts this cql2 expression to a cql2-json dictionary.

        Returns:
            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']}
        """

    def to_text(self) -> str:
        """Converts this cql2 expression to cql2-text.

        Returns:
            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\')'
        """

    def to_sql(self) -> SqlQuery:
        """Converts this cql2 expression to a SQL query.

        Returns:
            SqlQuery: The SQL query and parameters

        Examples:
            >>> from cql2 import Expr
            >>> expr = Expr("landsat:scene_id = 'LC82030282019133LGN00'")
            >>> q.query
            '("landsat:scene_id" = $1)'
            >>> q.params
            ['LC82030282019133LGN00']
        """

    def __add__(self, other: Expr) -> Expr:
        """Combines two cql2 expressions using the AND operator.

        Args:
            other (Expr): The other expression

        Returns:
            Expr: The combined expression

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

class SqlQuery:
    """A SQL query"""

    query: str
    """The query, with parameterized fields."""

    params: list[str]
    """The parameters, to use for binding."""

class ParseError(Exception):
    """An error raised when cql2 parsing fails."""

class ValidationError(Exception):
    """An error raised when cql2 json-schema validation fails."""