Coverage for pyodmongo/queries/operators.py: 100%
32 statements
« prev ^ index » next coverage.py v7.6.10, created at 2025-01-16 15:08 +0000
1from ..models.query_operators import (
2 ComparisonOperator,
3 LogicalOperator,
4 ElemMatchOperator,
5)
6from ..models.sort_operators import SortOperator
7from ..models.db_field_info import DbField
8from typing import Any
11def eq(field: DbField, value: Any) -> ComparisonOperator:
12 """
13 Creates a ComparisonOperator for the equality ('$eq') operation.
15 Args:
16 field (DbField): The database field to compare.
17 value (Any): The value to compare the field against.
19 Returns:
20 ComparisonOperator: The comparison operator for the equality operation.
21 """
22 return field.comparison_operator(operator="$eq", value=value)
25def gt(field: DbField, value: Any) -> ComparisonOperator:
26 """
27 Creates a ComparisonOperator for the greater than ('$gt') operation.
29 Args:
30 field (DbField): The database field to compare.
31 value (Any): The value to compare the field against.
33 Returns:
34 ComparisonOperator: The comparison operator for the greater than operation.
35 """
36 return field.comparison_operator(operator="$gt", value=value)
39def gte(field: DbField, value: Any) -> ComparisonOperator:
40 """
41 Creates a ComparisonOperator for the greater than or equal ('$gte') operation.
43 Args:
44 field (DbField): The database field to compare.
45 value (Any): The value to compare the field against.
47 Returns:
48 ComparisonOperator: The comparison operator for the greater than or equal operation.
49 """
50 return field.comparison_operator(operator="$gte", value=value)
53def in_(field: DbField, value: list[Any]) -> ComparisonOperator:
54 """
55 Creates a ComparisonOperator for the in ('$in') operation.
57 Args:
58 field (DbField): The database field to compare.
59 value (list[Any]): The list of values to compare the field against.
61 Returns:
62 ComparisonOperator: The comparison operator for the in operation.
63 """
64 return field.comparison_operator(operator="$in", value=value)
67def lt(field: DbField, value: Any) -> ComparisonOperator:
68 """
69 Creates a ComparisonOperator for the less than ('$lt') operation.
71 Args:
72 field (DbField): The database field to compare.
73 value (Any): The value to compare the field against.
75 Returns:
76 ComparisonOperator: The comparison operator for the less than operation.
77 """
78 return field.comparison_operator(operator="$lt", value=value)
81def lte(field: DbField, value: Any) -> ComparisonOperator:
82 """
83 Creates a ComparisonOperator for the less than or equal ('$lte') operation.
85 Args:
86 field (DbField): The database field to compare.
87 value (Any): The value to compare the field against.
89 Returns:
90 ComparisonOperator: The comparison operator for the less than or equal operation.
91 """
92 return field.comparison_operator(operator="$lte", value=value)
95def ne(field: DbField, value: Any) -> ComparisonOperator:
96 """
97 Creates a ComparisonOperator for the not equal ('$ne') operation.
99 Args:
100 field (DbField): The database field to compare.
101 value (Any): The value to compare the field against.
103 Returns:
104 ComparisonOperator: The comparison operator for the not equal operation.
105 """
106 return field.comparison_operator(operator="$ne", value=value)
109def nin(field: DbField, value: list[Any]) -> ComparisonOperator:
110 """
111 Creates a ComparisonOperator for the not in ('$nin') operation.
113 Args:
114 field (DbField): The database field to compare.
115 value (list[Any]): The list of values to compare the field against.
117 Returns:
118 ComparisonOperator: The comparison operator for the not in operation.
119 """
120 return field.comparison_operator(operator="$nin", value=value)
123def text(value: Any) -> ComparisonOperator:
124 """
125 Creates a ComparisonOperator for the text search ('$text' with '$search') operation.
127 Args:
128 value (Any): The value to search for in the text search.
130 Returns:
131 ComparisonOperator: The comparison operator for the text search operation.
132 """
133 return ComparisonOperator(path_str="$text", operator="$search", value=f'"{value}"')
136def and_(*operators: ComparisonOperator | LogicalOperator) -> LogicalOperator:
137 """
138 Creates a LogicalOperator for the logical AND ('$and') operation.
140 Args:
141 *operators (ComparisonOperator | LogicalOperator): Variable length argument list
142 of comparison or logical operators to be combined with logical AND.
144 Returns:
145 LogicalOperator: The logical operator for the AND operation.
146 """
147 return LogicalOperator(operator="$and", operators=operators)
150def or_(*operators: ComparisonOperator | LogicalOperator) -> LogicalOperator:
151 """
152 Creates a LogicalOperator for the logical OR ('$or') operation.
154 Args:
155 *operators (ComparisonOperator | LogicalOperator): Variable length argument list
156 of comparison or logical operators to be combined with logical OR.
158 Returns:
159 LogicalOperator: The logical operator for the OR operation.
160 """
161 return LogicalOperator(operator="$or", operators=operators)
164def nor(*operators: ComparisonOperator | LogicalOperator) -> LogicalOperator:
165 """
166 Creates a LogicalOperator for the logical NOR ('$nor') operation.
168 Args:
169 *operators (ComparisonOperator | LogicalOperator): Variable length argument list
170 of comparison or logical operators to be combined with logical NOR.
172 Returns:
173 LogicalOperator: The logical operator for the NOR operation.
174 """
175 return LogicalOperator(operator="$nor", operators=operators)
178def elem_match(
179 *operators: ComparisonOperator | LogicalOperator,
180 field: DbField,
181) -> ElemMatchOperator:
182 """
183 Creates an ElemMatchOperator for the '$elemMatch' operation, used to match
184 documents that contain an array field with at least one element that matches
185 the specified criteria.
187 Args:
188 *operators (ComparisonOperator | LogicalOperator): Variable length argument list
189 of comparison or logical operators defining the matching criteria.
190 field (DbField): The field to which the elemMatch operation applies.
192 Returns:
193 ElemMatchOperator: The operator for the elemMatch operation.
194 """
195 return ElemMatchOperator(field=field, operators=operators)
198def sort(*operators: tuple[DbField, int]) -> SortOperator:
199 """
200 Creates a SortOperator object for MongoDB queries that specifies the sorting order of documents.
202 Args:
203 *operators (tuple[DbField, int]): Variable length argument list where each tuple contains
204 a DbField and an integer. The DbField specifies the field to sort by, and the integer
205 specifies the direction (1 for ascending, -1 for descending).
207 Returns:
208 SortOperator: An object encapsulating the sorting criteria for MongoDB queries.
210 Description:
211 This function takes one or more sorting criteria represented by tuples of DbField and direction.
212 It constructs a SortOperator that is used to define the order in which documents should be returned
213 in a query, aligning with MongoDB's sorting syntax. This operator can be used in database operations
214 to sort query results according to specified fields and directions.
215 """
216 return SortOperator(operators=operators)