Debian Codegraph @

boto3/dynamodb/conditions.py

raw
1 # Copyright 2015 Amazon.com, Inc. or its affiliates. All Rights Reserved.
2 #
3 # Licensed under the Apache License, Version 2.0 (the "License"). You
4 # may not use this file except in compliance with the License. A copy of
5 # the License is located at
6 #
7 # https://aws.amazon.com/apache2.0/
8 #
9 # or in the "license" file accompanying this file. This file is
10 # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
11 # ANY KIND, either express or implied. See the License for the specific
12 # language governing permissions and limitations under the License.
13 import re
14 from collections import namedtuple
15
16 from boto3.exceptions import (
17 DynamoDBNeedsConditionError,
18 DynamoDBNeedsKeyConditionError,
19 DynamoDBOperationNotSupportedError,
20 )
21
22 ATTR_NAME_REGEX = re.compile(r'[^.\[\]]+(?![^\[]*\])')
23
24
25 class ConditionBase:
26 expression_format = ''
27 expression_operator = ''
28 has_grouped_values = False
29
30 def __init__(self, *values):
31 self._values = values
32
33 def __and__(self, other):
34 if not isinstance(other, ConditionBase):
35 raise DynamoDBOperationNotSupportedError('AND', other)
36 return And(self, other)
37
38 def __or__(self, other):
39 if not isinstance(other, ConditionBase):
40 raise DynamoDBOperationNotSupportedError('OR', other)
41 return Or(self, other)
42
43 def __invert__(self):
44 return Not(self)
45
46 def get_expression(self):
47 return {
48 'format': self.expression_format,
49 'operator': self.expression_operator,
50 'values': self._values,
51 }
52
53 def __eq__(self, other):
54 if isinstance(other, type(self)):
55 if self._values == other._values:
56 return True
57 return False
58
59 def __ne__(self, other):
60 return not self.__eq__(other)
61
62
63 class AttributeBase:
64 def __init__(self, name):
65 self.name = name
66
67 def __and__(self, value):
68 raise DynamoDBOperationNotSupportedError('AND', self)
69
70 def __or__(self, value):
71 raise DynamoDBOperationNotSupportedError('OR', self)
72
73 def __invert__(self):
74 raise DynamoDBOperationNotSupportedError('NOT', self)
75
76 def eq(self, value):
77 """Creates a condition where the attribute is equal to the value.
78
79 :param value: The value that the attribute is equal to.
80 """
81 return Equals(self, value)
82
83 def lt(self, value):
84 """Creates a condition where the attribute is less than the value.
85
86 :param value: The value that the attribute is less than.
87 """
88 return LessThan(self, value)
89
90 def lte(self, value):
91 """Creates a condition where the attribute is less than or equal to the
92 value.
93
94 :param value: The value that the attribute is less than or equal to.
95 """
96 return LessThanEquals(self, value)
97
98 def gt(self, value):
99 """Creates a condition where the attribute is greater than the value.
100
101 :param value: The value that the attribute is greater than.
102 """
103 return GreaterThan(self, value)
104
105 def gte(self, value):
106 """Creates a condition where the attribute is greater than or equal to
107 the value.
108
109 :param value: The value that the attribute is greater than or equal to.
110 """
111 return GreaterThanEquals(self, value)
112
113 def begins_with(self, value):
114 """Creates a condition where the attribute begins with the value.
115
116 :param value: The value that the attribute begins with.
117 """
118 return BeginsWith(self, value)
119
120 def between(self, low_value, high_value):
121 """Creates a condition where the attribute is greater than or equal
122 to the low value and less than or equal to the high value.
123
124 :param low_value: The value that the attribute is greater than or equal to.
125 :param high_value: The value that the attribute is less than or equal to.
126 """
127 return Between(self, low_value, high_value)
128
129 def __eq__(self, other):
130 return isinstance(other, type(self)) and self.name == other.name
131
132 def __ne__(self, other):
133 return not self.__eq__(other)
134
135
136 class ConditionAttributeBase(ConditionBase, AttributeBase):
137 """This base class is for conditions that can have attribute methods.
138
139 One example is the Size condition. To complete a condition, you need
140 to apply another AttributeBase method like eq().
141 """
142
143 def __init__(self, *values):
144 ConditionBase.__init__(self, *values)
145 # This is assuming the first value to the condition is the attribute
146 # in which can be used to generate its attribute base.
147 AttributeBase.__init__(self, values[0].name)
148
149 def __eq__(self, other):
150 return ConditionBase.__eq__(self, other) and AttributeBase.__eq__(
151 self, other
152 )
153
154 def __ne__(self, other):
155 return not self.__eq__(other)
156
157
158 class ComparisonCondition(ConditionBase):
159 expression_format = '{0} {operator} {1}'
160
161
162 class Equals(ComparisonCondition):
163 expression_operator = '='
164
165
166 class NotEquals(ComparisonCondition):
167 expression_operator = '<>'
168
169
170 class LessThan(ComparisonCondition):
171 expression_operator = '<'
172
173
174 class LessThanEquals(ComparisonCondition):
175 expression_operator = '<='
176
177
178 class GreaterThan(ComparisonCondition):
179 expression_operator = '>'
180
181
182 class GreaterThanEquals(ComparisonCondition):
183 expression_operator = '>='
184
185
186 class In(ComparisonCondition):
187 expression_operator = 'IN'
188 has_grouped_values = True
189
190
191 class Between(ConditionBase):
192 expression_operator = 'BETWEEN'
193 expression_format = '{0} {operator} {1} AND {2}'
194
195
196 class BeginsWith(ConditionBase):
197 expression_operator = 'begins_with'
198 expression_format = '{operator}({0}, {1})'
199
200
201 class Contains(ConditionBase):
202 expression_operator = 'contains'
203 expression_format = '{operator}({0}, {1})'
204
205
206 class Size(ConditionAttributeBase):
207 expression_operator = 'size'
208 expression_format = '{operator}({0})'
209
210
211 class AttributeType(ConditionBase):
212 expression_operator = 'attribute_type'
213 expression_format = '{operator}({0}, {1})'
214
215
216 class AttributeExists(ConditionBase):
217 expression_operator = 'attribute_exists'
218 expression_format = '{operator}({0})'
219
220
221 class AttributeNotExists(ConditionBase):
222 expression_operator = 'attribute_not_exists'
223 expression_format = '{operator}({0})'
224
225
226 class And(ConditionBase):
227 expression_operator = 'AND'
228 expression_format = '({0} {operator} {1})'
229
230
231 class Or(ConditionBase):
232 expression_operator = 'OR'
233 expression_format = '({0} {operator} {1})'
234
235
236 class Not(ConditionBase):
237 expression_operator = 'NOT'
238 expression_format = '({operator} {0})'
239
240
241 class Key(AttributeBase):
242 pass
243
244
245 class Attr(AttributeBase):
246 """Represents an DynamoDB item's attribute."""
247
248 def ne(self, value):
249 """Creates a condition where the attribute is not equal to the value
250
251 :param value: The value that the attribute is not equal to.
252 """
253 return NotEquals(self, value)
254
255 def is_in(self, value):
256 """Creates a condition where the attribute is in the value,
257
258 :type value: list
259 :param value: The value that the attribute is in.
260 """
261 return In(self, value)
262
263 def exists(self):
264 """Creates a condition where the attribute exists."""
265 return AttributeExists(self)
266
267 def not_exists(self):
268 """Creates a condition where the attribute does not exist."""
269 return AttributeNotExists(self)
270
271 def contains(self, value):
272 """Creates a condition where the attribute contains the value.
273
274 :param value: The value the attribute contains.
275 """
276 return Contains(self, value)
277
278 def size(self):
279 """Creates a condition for the attribute size.
280
281 Note another AttributeBase method must be called on the returned
282 size condition to be a valid DynamoDB condition.
283 """
284 return Size(self)
285
286 def attribute_type(self, value):
287 """Creates a condition for the attribute type.
288
289 :param value: The type of the attribute.
290 """
291 return AttributeType(self, value)
292
293
294 BuiltConditionExpression = namedtuple(
295 'BuiltConditionExpression',
296 [
297 'condition_expression',
298 'attribute_name_placeholders',
299 'attribute_value_placeholders',
300 ],
301 )
302
303
304 class ConditionExpressionBuilder:
305 """This class is used to build condition expressions with placeholders"""
306
307 def __init__(self):
308 self._name_count = 0
309 self._value_count = 0
310 self._name_placeholder = 'n'
311 self._value_placeholder = 'v'
312
313 def _get_name_placeholder(self):
314 return '#' + self._name_placeholder + str(self._name_count)
315
316 def _get_value_placeholder(self):
317 return ':' + self._value_placeholder + str(self._value_count)
318
319 def reset(self):
320 """Resets the placeholder name and values"""
321 self._name_count = 0
322 self._value_count = 0
323
324 def build_expression(self, condition, is_key_condition=False):
325 """Builds the condition expression and the dictionary of placeholders.
326
327 :type condition: ConditionBase
328 :param condition: A condition to be built into a condition expression
329 string with any necessary placeholders.
330
331 :type is_key_condition: Boolean
332 :param is_key_condition: True if the expression is for a
333 KeyConditionExpression. False otherwise.
334
335 :rtype: (string, dict, dict)
336 :returns: Will return a string representing the condition with
337 placeholders inserted where necessary, a dictionary of
338 placeholders for attribute names, and a dictionary of
339 placeholders for attribute values. Here is a sample return value:
340
341 ('#n0 = :v0', {'#n0': 'myattribute'}, {':v1': 'myvalue'})
342 """
343 if not isinstance(condition, ConditionBase):
344 raise DynamoDBNeedsConditionError(condition)
345 attribute_name_placeholders = {}
346 attribute_value_placeholders = {}
347 condition_expression = self._build_expression(
348 condition,
349 attribute_name_placeholders,
350 attribute_value_placeholders,
351 is_key_condition=is_key_condition,
352 )
353 return BuiltConditionExpression(
354 condition_expression=condition_expression,
355 attribute_name_placeholders=attribute_name_placeholders,
356 attribute_value_placeholders=attribute_value_placeholders,
357 )
358
359 def _build_expression(
360 self,
361 condition,
362 attribute_name_placeholders,
363 attribute_value_placeholders,
364 is_key_condition,
365 ):
366 expression_dict = condition.get_expression()
367 replaced_values = []
368 for value in expression_dict['values']:
369 # Build the necessary placeholders for that value.
370 # Placeholders are built for both attribute names and values.
371 replaced_value = self._build_expression_component(
372 value,
373 attribute_name_placeholders,
374 attribute_value_placeholders,
375 condition.has_grouped_values,
376 is_key_condition,
377 )
378 replaced_values.append(replaced_value)
379 # Fill out the expression using the operator and the
380 # values that have been replaced with placeholders.
381 return expression_dict['format'].format(
382 *replaced_values, operator=expression_dict['operator']
383 )
384
385 def _build_expression_component(
386 self,
387 value,
388 attribute_name_placeholders,
389 attribute_value_placeholders,
390 has_grouped_values,
391 is_key_condition,
392 ):
393 # Continue to recurse if the value is a ConditionBase in order
394 # to extract out all parts of the expression.
395 if isinstance(value, ConditionBase):
396 return self._build_expression(
397 value,
398 attribute_name_placeholders,
399 attribute_value_placeholders,
400 is_key_condition,
401 )
402 # If it is not a ConditionBase, we can recurse no further.
403 # So we check if it is an attribute and add placeholders for
404 # its name
405 elif isinstance(value, AttributeBase):
406 if is_key_condition and not isinstance(value, Key):
407 raise DynamoDBNeedsKeyConditionError(
408 f'Attribute object {value.name} is of type {type(value)}. '
409 f'KeyConditionExpression only supports Attribute objects '
410 f'of type Key'
411 )
412 return self._build_name_placeholder(
413 value, attribute_name_placeholders
414 )
415 # If it is anything else, we treat it as a value and thus placeholders
416 # are needed for the value.
417 else:
418 return self._build_value_placeholder(
419 value, attribute_value_placeholders, has_grouped_values
420 )
421
422 def _build_name_placeholder(self, value, attribute_name_placeholders):
423 attribute_name = value.name
424 # Figure out which parts of the attribute name that needs replacement.
425 attribute_name_parts = ATTR_NAME_REGEX.findall(attribute_name)
426
427 # Add a temporary placeholder for each of these parts.
428 placeholder_format = ATTR_NAME_REGEX.sub('%s', attribute_name)
429 str_format_args = []
430 for part in attribute_name_parts:
431 name_placeholder = self._get_name_placeholder()
432 self._name_count += 1
433 str_format_args.append(name_placeholder)
434 # Add the placeholder and value to dictionary of name placeholders.
435 attribute_name_placeholders[name_placeholder] = part
436 # Replace the temporary placeholders with the designated placeholders.
437 return placeholder_format % tuple(str_format_args)
438
439 def _build_value_placeholder(
440 self, value, attribute_value_placeholders, has_grouped_values=False
441 ):
442 # If the values are grouped, we need to add a placeholder for
443 # each element inside of the actual value.
444 if has_grouped_values:
445 placeholder_list = []
446 for v in value:
447 value_placeholder = self._get_value_placeholder()
448 self._value_count += 1
449 placeholder_list.append(value_placeholder)
450 attribute_value_placeholders[value_placeholder] = v
451 # Assuming the values are grouped by parenthesis.
452 # IN is the currently the only one that uses this so it maybe
453 # needed to be changed in future.
454 return '(' + ', '.join(placeholder_list) + ')'
455 # Otherwise, treat the value as a single value that needs only
456 # one placeholder.
457 else:
458 value_placeholder = self._get_value_placeholder()
459 self._value_count += 1
460 attribute_value_placeholders[value_placeholder] = value
461 return value_placeholder