Complete Expression API (#352)

jpinner-lyft · web-flow · commit 495eae28679c · 2017-09-08T19:30:36.000-07:00
diff --git a/docs/conditional.rst b/docs/conditional.rst
@@ -86,7 +86,7 @@ This example will update a `Thread` item, if the `views` attribute is less than
 
 .. code-block:: python
 
-    thread_item.update((Thread.views < 5) | (Thread.views > 10))
+    thread_item.update(condition=(Thread.views < 5) | (Thread.views > 10))
 
 
 Conditional Model.delete
diff --git a/docs/tutorial.rst b/docs/tutorial.rst
@@ -279,16 +279,10 @@ atomically updating the view count of an item + updating the value of the last p
 
 .. code-block:: python
 
-    >>> thread_item.update({
-            'views': {
-                'action': 'add',
-                'value': 1,
-            },
-            'last_post_datetime': {
-                'action': 'put',
-                'value': datetime.now(),
-            },
-        })
+    >>> thread_item.update(actions=[
+            Thread.views.set(Thread.views + 1),
+            Thread.last_post_datetime.set(datetime.now()),
+        ])
 
 
 .. deprecated:: 2.0
diff --git a/pynamodb/attributes.py b/pynamodb/attributes.py
@@ -130,6 +130,40 @@ def startswith(self, prefix):
     def contains(self, item):
         return Path(self).contains(item)
 
+    # Update Expression Support
+    def __add__(self, other):
+        return Path(self).__add__(other)
+
+    def __radd__(self, other):
+        return Path(self).__radd__(other)
+
+    def __sub__(self, other):
+        return Path(self).__sub__(other)
+
+    def __rsub__(self, other):
+        return Path(self).__rsub__(other)
+
+    def __or__(self, other):
+        return Path(self).__or__(other)
+
+    def append(self, other):
+        return Path(self).append(other)
+
+    def prepend(self, other):
+        return Path(self).prepend(other)
+
+    def set(self, value):
+        return Path(self).set(value)
+
+    def update(self, subset):
+        return Path(self).update(subset)
+
+    def difference_update(self, subset):
+        return Path(self).difference_update(subset)
+
+    def remove(self):
+        return Path(self).remove()
+
 
 class AttributeContainerMeta(type):
 
diff --git a/pynamodb/connection/base.py b/pynamodb/connection/base.py
@@ -839,6 +839,7 @@ def update_item(self,
                     table_name,
                     hash_key,
                     range_key=None,
+                    actions=None,
                     attribute_updates=None,
                     condition=None,
                     expected=None,
@@ -849,6 +850,7 @@ def update_item(self,
         """
         Performs the UpdateItem operation
         """
+        self._check_actions(actions, attribute_updates)
         self._check_condition('condition', condition, expected, conditional_operator)
 
         operation_kwargs = {TABLE_NAME: table_name}
@@ -865,10 +867,12 @@ def update_item(self,
             operation_kwargs.update(self.get_item_collection_map(return_item_collection_metrics))
         if return_values:
             operation_kwargs.update(self.get_return_values_map(return_values))
-        if not attribute_updates:
+        if not actions and not attribute_updates:
             raise ValueError("{0} cannot be empty".format(ATTR_UPDATES))
+        actions = actions or []
+        attribute_updates = attribute_updates or {}
 
-        update_expression = Update()
+        update_expression = Update(*actions)
         # We sort the keys here for determinism. This is mostly done to simplify testing.
         for key in sorted(attribute_updates.keys()):
             path = Path([key])
@@ -1438,6 +1442,14 @@ def _get_condition(self, table_name, attribute_name, operator, *values):
         ]
         return getattr(Path([attribute_name]), operator)(*values)
 
+    def _check_actions(self, actions, attribute_updates):
+        if actions is not None:
+            if attribute_updates is not None:
+                raise ValueError("Legacy attribute updates cannot be used with update actions")
+        else:
+            if attribute_updates is not None:
+                warnings.warn("Legacy attribute updates are deprecated in favor of update actions")
+
     def _check_condition(self, name, condition, expected_or_filter, conditional_operator):
         if condition is not None:
             if not isinstance(condition, Condition):
diff --git a/pynamodb/connection/table.py b/pynamodb/connection/table.py
@@ -53,6 +53,7 @@ def delete_item(self, hash_key,
     def update_item(self,
                     hash_key,
                     range_key=None,
+                    actions=None,
                     attribute_updates=None,
                     condition=None,
                     expected=None,
@@ -68,6 +69,7 @@ def update_item(self,
             self.table_name,
             hash_key,
             range_key=range_key,
+            actions=actions,
             attribute_updates=attribute_updates,
             condition=condition,
             expected=expected,
diff --git a/pynamodb/expressions/operand.py b/pynamodb/expressions/operand.py
@@ -1,5 +1,5 @@
 from pynamodb.constants import (
-    ATTR_TYPE_MAP, BINARY_SET, LIST, MAP, NUMBER_SET, NUMBER_SHORT, SHORT_ATTR_TYPES, STRING_SET, STRING_SHORT
+    ATTR_TYPE_MAP, BINARY_SET, LIST, LIST_SHORT, MAP, NUMBER_SET, NUMBER_SHORT, SHORT_ATTR_TYPES, STRING_SET, STRING_SHORT
 )
 from pynamodb.expressions.condition import (
     BeginsWith, Between, Comparison, Contains, Exists, In, IsType, NotExists
@@ -75,6 +75,36 @@ def is_in(self, *values):
         return In(self, *values)
 
 
+class _NumericOperand(_Operand):
+    """
+    A base class for Operands that can be used in the increment and decrement SET update actions.
+    """
+
+    def __add__(self, other):
+        return _Increment(self, self._to_operand(other))
+
+    def __radd__(self, other):
+        return _Increment(self._to_operand(other), self)
+
+    def __sub__(self, other):
+        return _Decrement(self, self._to_operand(other))
+
+    def __rsub__(self, other):
+        return _Decrement(self._to_operand(other), self)
+
+
+class _ListAppendOperand(_Operand):
+    """
+    A base class for Operands that can be used in the list_append function for the SET update action.
+    """
+
+    def append(self, other):
+        return _ListAppend(self, self._to_operand(other))
+
+    def prepend(self, other):
+        return _ListAppend(self._to_operand(other), self)
+
+
 class _Size(_ConditionOperand):
     """
     Size is a special operand that represents the result of calling the 'size' function on a Path operand.
@@ -93,7 +123,60 @@ def _to_operand(self, value):
         return operand
 
 
-class Value(_ConditionOperand):
+class _Increment(_Operand):
+    """
+    Increment is a special operand that represents an increment SET update action.
+    """
+    format_string = '{0} + {1}'
+    short_attr_type = NUMBER_SHORT
+
+    def __init__(self, lhs, rhs):
+        lhs._type_check(NUMBER_SHORT)
+        rhs._type_check(NUMBER_SHORT)
+        super(_Increment, self).__init__(lhs, rhs)
+
+
+class _Decrement(_Operand):
+    """
+    Decrement is a special operand that represents an decrement SET update action.
+    """
+    format_string = '{0} - {1}'
+    short_attr_type = NUMBER_SHORT
+
+    def __init__(self, lhs, rhs):
+        lhs._type_check(NUMBER_SHORT)
+        rhs._type_check(NUMBER_SHORT)
+        super(_Decrement, self).__init__(lhs, rhs)
+
+
+class _ListAppend(_Operand):
+    """
+    ListAppend is a special operand that represents the list_append function for the SET update action.
+    """
+    format_string = 'list_append ({0}, {1})'
+    short_attr_type = LIST_SHORT
+
+    def __init__(self, list1, list2):
+        list1._type_check(LIST_SHORT)
+        list2._type_check(LIST_SHORT)
+        super(_ListAppend, self).__init__(list1, list2)
+
+
+class _IfNotExists(_NumericOperand, _ListAppendOperand):
+    """
+    IfNotExists is a special operand that represents the if_not_exists function for the SET update action.
+    """
+    format_string = 'if_not_exists ({0}, {1})'
+
+    def __init__(self, path, value):
+        self.short_attr_type = path.short_attr_type or value.short_attr_type
+        if self.short_attr_type != value.short_attr_type:
+            # path and value have conflicting types -- defer any type checks to DynamoDB
+            self.short_attr_type = None
+        super(_IfNotExists, self).__init__(path, value)
+
+
+class Value(_NumericOperand, _ListAppendOperand, _ConditionOperand):
     """
     Value is an operand that represents an attribute value.
     """
@@ -103,6 +186,8 @@ def __init__(self, value, attribute=None):
         # Check to see if value is already serialized
         if isinstance(value, dict) and len(value) == 1 and list(value.keys())[0] in SHORT_ATTR_TYPES:
             (self.short_attr_type, value), = value.items()
+        elif value is None:
+            (self.short_attr_type, value) = Value.__serialize(value)
         else:
             (self.short_attr_type, value) = Value.__serialize(value, attribute)
         super(Value, self).__init__({self.short_attr_type: value})
@@ -134,7 +219,7 @@ def __serialize_based_on_type(value):
         return ATTR_TYPE_MAP[attr_class.attr_type], attr_class.serialize(value)
 
 
-class Path(_ConditionOperand):
+class Path(_NumericOperand, _ListAppendOperand, _ConditionOperand):
     """
     Path is an operand that represents either an attribute name or document path.
     """
@@ -166,6 +251,9 @@ def __getitem__(self, idx):
         element_path.path[-1] = '{0}[{1}]'.format(self.path[-1], idx)
         return element_path
 
+    def __or__(self, other):
+        return _IfNotExists(self, self._to_operand(other))
+
     def set(self, value):
         # Returns an update action that sets this attribute to the given value
         return SetAction(self, self._to_operand(value))
diff --git a/pynamodb/expressions/update.py b/pynamodb/expressions/update.py
@@ -11,6 +11,10 @@ def serialize(self, placeholder_names, expression_attribute_values):
         values = [value.serialize(placeholder_names, expression_attribute_values) for value in self.values]
         return self.format_string.format(*values)
 
+    def __repr__(self):
+        values = [str(value) for value in self.values]
+        return self.format_string.format(*values)
+
 
 class SetAction(Action):
     """
@@ -56,11 +60,13 @@ def __init__(self, path, subset):
 
 class Update(object):
 
-    def __init__(self):
+    def __init__(self, *actions):
         self.set_actions = []
         self.remove_actions = []
         self.add_actions = []
         self.delete_actions = []
+        for action in actions:
+            self.add_action(action)
 
     def add_action(self, action):
         if isinstance(action, SetAction):
diff --git a/pynamodb/models.py b/pynamodb/models.py
@@ -378,7 +378,7 @@ def update_item(self, attribute, value=None, action=None, condition=None, condit
                 setattr(self, attr_name, attr.deserialize(value.get(ATTR_TYPE_MAP[attr.attr_type])))
         return data
 
-    def update(self, attributes, condition=None, conditional_operator=None, **expected_values):
+    def update(self, attributes=None, actions=None, condition=None, conditional_operator=None, **expected_values):
         """
         Updates an item using the UpdateItem operation.
 
@@ -388,24 +388,29 @@ def update(self, attributes, condition=None, conditional_operator=None, **expect
                                 next_attr: {'value': True, 'action': 'PUT'},
                             }
         """
-        if not isinstance(attributes, dict):
+        if attributes is not None and not isinstance(attributes, dict):
             raise TypeError("the value of `attributes` is expected to be a dictionary")
+        if actions is not None and not isinstance(actions, list):
+            raise TypeError("the value of `actions` is expected to be a list")
 
         self._conditional_operator_check(conditional_operator)
         args, save_kwargs = self._get_save_args(null_check=False)
         kwargs = {
             pythonic(RETURN_VALUES):  ALL_NEW,
-            pythonic(ATTR_UPDATES): {},
             'conditional_operator': conditional_operator,
         }
 
+        if attributes:
+            kwargs[pythonic(ATTR_UPDATES)] = {}
+
         if pythonic(RANGE_KEY) in save_kwargs:
             kwargs[pythonic(RANGE_KEY)] = save_kwargs[pythonic(RANGE_KEY)]
 
         if expected_values:
             kwargs['expected'] = self._build_expected_values(expected_values, UPDATE_FILTER_OPERATOR_MAP)
 
         attrs = self._get_attributes()
+        attributes = attributes or {}
         for attr, params in attributes.items():
             attribute_cls = attrs[attr]
             action = params['action'] and params['action'].upper()
@@ -416,6 +421,7 @@ def update(self, attributes, condition=None, conditional_operator=None, **expect
             kwargs[pythonic(ATTR_UPDATES)][attribute_cls.attr_name] = attr_values
 
         kwargs.update(condition=condition)
+        kwargs.update(actions=actions)
         data = self._get_connection().update_item(*args, **kwargs)
         self._throttle.add_record(data.get(CONSUMED_CAPACITY))
         for name, value in data[ATTRIBUTES].items():
diff --git a/pynamodb/tests/test_base_connection.py b/pynamodb/tests/test_base_connection.py
diff --git a/pynamodb/tests/test_expressions.py b/pynamodb/tests/test_expressions.py
diff --git a/pynamodb/tests/test_model.py b/pynamodb/tests/test_model.py
diff --git a/pynamodb/tests/test_table_connection.py b/pynamodb/tests/test_table_connection.py
