| 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 |