Add documentation for update expressions. (#371)

Author: jpinner-lyft

docs/index.rst

@@ -30,6 +30,7 @@ Topics
    tutorial
    indexes
    batch
+   updates
    conditional
    attributes
    local

docs/release_notes.rst

@@ -2,7 +2,7 @@ Release Notes
 =============
 
 v3.2.0rc2
--------
+---------
 
 :date 2017-10-09
 
@@ -16,7 +16,7 @@ Contributors to this release:
 * @jpinner-lyft
 
 v3.2.0rc1
--------
+---------
 
 :date: 2017-09-22
 

docs/tutorial.rst

@@ -284,6 +284,7 @@ atomically updating the view count of an item + updating the value of the last p
             Thread.last_post_datetime.set(datetime.now()),
         ])
 
+Update actions use the update expression syntax (see :ref:`updates`).
 
 .. deprecated:: 2.0
 

docs/updates.rst

@@ -0,0 +1,47 @@
+Update Operations
+=================
+
+The UpdateItem DynamoDB operations allows you to create or modify attributes of an item using an update expression.
+See the `official documentation <http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html>`_
+for more details.
+
+Suppose that you have defined a `Thread` Model for the examples below.
+
+.. code-block:: python
+
+    from pynamodb.models import Model
+    from pynamodb.attributes import (
+        ListAttribute, UnicodeAttribute, UnicodeSetAttribute, NumberAttribute
+    )
+
+
+    class Thread(Model):
+        class Meta:
+            table_name = 'Thread'
+
+        forum_name = UnicodeAttribute(hash_key=True)
+        subjects = UnicodeSetAttribute(default={})
+        views = NumberAttribute(default=0)
+        notes = ListAttribute(default=[])
+
+
+.. _updates:
+
+Update Expressions
+^^^^^^^^^^^^^^^^^^
+
+PynamoDB supports creating update expressions from attributes using a mix of built-in operators and method calls.
+Any value provided will be serialized using the serializer defined for that attribute.
+
+.. csv-table::
+    :header: DynamoDB Action / Operator, PynamoDB Syntax, Example
+
+    SET, set( `value` ), Thread.views.set(10)
+    REMOVE, remove(), Thread.subjects.remove()
+    ADD, add( `value` ), "Thread.subjects.add({'A New Subject', 'Another New Subject'})"
+    DELETE, delete( `value` ), Thread.subjects.delete({'An Old Subject'})
+    `attr_or_value_1` \+ `attr_or_value_2`, `attr_or_value_1` \+ `attr_or_value_2`, Thread.views + 5
+    `attr_or_value_1` \- `attr_or_value_2`, `attr_or_value_1` \- `attr_or_value_2`, 5 - Thread.views
+    "list_append( `attr` , `value` )", append( `value` ), Thread.notes.append(['my last note'])
+    "list_append( `value` , `attr` )", prepend( `value` ), Thread.notes.prepend(['my first note'])
+    "if_not_exists( `attr`, `value` )", `attr` | `value`, Thread.forum_name | 'Default Forum Name'

examples/model.py

@@ -167,37 +167,32 @@ class Meta:
 
 # DynamoDB will update the item, by adding 1 to the views attribute,
 # if the forum_name attribute equals 'Some Forum' or the subject attribute exists
-print(thread_item.update_item(
-    'views',
-    1,
-    action='add',
-    condition=((Thread.forum_name == 'Some Forum') | Thread.subject.exists())
+print(thread_item.update(
+    actions=[
+        Thread.views.add(1)
+    ],
+    condition=(
+        (Thread.forum_name == 'Some Forum') | Thread.subject.exists()
+    )
 ))
 
 # DynamoDB will atomically update the attributes `replies` (increase value by 1),
 # and `last_post_datetime` (set value to the current datetime)
-print(thread_item.update({
-    'replies': {
-        'action': 'add',
-        'value': 1,
-    },
-    'last_post_datetime': {
-        'action': 'put',
-        'value': datetime.now(),
-    },
-}))
+print(thread_item.update(actions=[
+    Thread.replies.add(1),
+    Thread.last_post_datetime.set(datetime.now()),
+]))
 
 # DynamoDB will delete the item, only if the views attribute is equal to one
 try:
     print(thread_item.delete(Thread.views == 1))
 except:
     pass
 
-# Delete an item's attribute
-print(thread_item.update_item(
-    'tags',
-    action='delete'
-))
+# Remove an item's attribute
+print(thread_item.update(actions=[
+    Thread.tags.remove()
+]))
 
 # Backup/restore example
 # Print the size of the table

pynamodb/attributes.py

@@ -159,15 +159,15 @@ def prepend(self, 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()
 
+    def add(self, value):
+        return Path(self).add(value)
+
+    def delete(self, value):
+        return Path(self).delete(value)
+
 
 class AttributeContainerMeta(type):
 

pynamodb/connection/base.py

@@ -886,12 +886,11 @@ def update_item(self,
                 attr_type = self.get_attribute_type(table_name, key, value)
             value = {attr_type: value}
             if action == DELETE:
-                action = path.remove() if attr_type is None else path.difference_update(value)
+                action = path.remove() if attr_type is None else path.delete(value)
             elif action == PUT:
                 action = path.set(value)
             else:
-                # right now update() returns an AddAction
-                action = path.update(value)
+                action = path.add(value)
             update_expression.add_action(action)
         operation_kwargs[UPDATE_EXPRESSION] = update_expression.serialize(name_placeholders, expression_attribute_values)
 

pynamodb/expressions/operand.py

@@ -271,18 +271,18 @@ def set(self, value):
         # Returns an update action that sets this attribute to the given value
         return SetAction(self, self._to_operand(value))
 
-    def update(self, subset):
-        # Returns an update action that adds the subset to this set attribute
-        return AddAction(self, self._to_operand(subset))
-
-    def difference_update(self, subset):
-        # Returns an update action that deletes the subset from this set attribute
-        return DeleteAction(self, self._to_operand(subset))
-
     def remove(self):
         # Returns an update action that removes this attribute from the item
         return RemoveAction(self)
 
+    def add(self, value):
+        # Returns an update action that appends the given value to a set or mathematically adds it to a number
+        return AddAction(self, self._to_operand(value))
+
+    def delete(self, value):
+        # Returns an update action that removes the given value from a set attribute
+        return DeleteAction(self, self._to_operand(value))
+
     def exists(self):
         return Exists(self)
 

pynamodb/tests/test_expressions.py

@@ -467,15 +467,15 @@ def test_remove_action(self):
         assert expression_attribute_values == {}
 
     def test_add_action(self):
-        action = Path('foo').update(0)
+        action = Path('foo').add(0)
         placeholder_names, expression_attribute_values = {}, {}
         expression = action.serialize(placeholder_names, expression_attribute_values)
         assert expression == "#0 :0"
         assert placeholder_names == {'foo': '#0'}
         assert expression_attribute_values == {':0': {'N': '0'}}
 
     def test_add_action_set(self):
-        action = NumberSetAttribute(attr_name='foo').update({'NS': ['0']})
+        action = NumberSetAttribute(attr_name='foo').add({'NS': ['0']})
         placeholder_names, expression_attribute_values = {}, {}
         expression = action.serialize(placeholder_names, expression_attribute_values)
         assert expression == "#0 :0"
@@ -484,10 +484,10 @@ def test_add_action_set(self):
 
     def test_add_action_list(self):
         with self.assertRaises(ValueError):
-            Path('foo').update({'L': [{'N': '0'}]})
+            Path('foo').add({'L': [{'N': '0'}]})
 
     def test_delete_action(self):
-        action = NumberSetAttribute(attr_name='foo').difference_update({'NS': ['0']})
+        action = NumberSetAttribute(attr_name='foo').delete({'NS': ['0']})
         placeholder_names, expression_attribute_values = {}, {}
         expression = action.serialize(placeholder_names, expression_attribute_values)
         assert expression == "#0 :0"
@@ -496,14 +496,14 @@ def test_delete_action(self):
 
     def test_delete_action_non_set(self):
         with self.assertRaises(ValueError):
-            Path('foo').difference_update({'N': '0'})
+            Path('foo').delete({'N': '0'})
 
     def test_update(self):
         update = Update(
             self.attribute.set({'S': 'bar'}),
             self.attribute.remove(),
-            self.attribute.update({'N': '0'}),
-            self.attribute.difference_update({'NS': ['0']})
+            self.attribute.add({'N': '0'}),
+            self.attribute.delete({'NS': ['0']})
         )
         placeholder_names, expression_attribute_values = {}, {}
         expression = update.serialize(placeholder_names, expression_attribute_values)