Add support for native map and list attributes (#175)

Author: jmphilli

docs/attributes.rst

@@ -2,17 +2,19 @@ Custom Attributes
 ==========================
 
 Attributes in PynamoDB are classes that are serialized to and from DynamoDB attributes. PynamoDB provides attribute classes
-for all of the basic DynamoDB data types, as defined in the `DynamoDB documentation <http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DataModel.html>`_.
+for all DynamoDB data types, as defined in the `DynamoDB documentation <http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DataModel.html>`_.
 Higher level attribute types (internally stored as a DynamoDB data types) can be defined with PynamoDB. Two such types
-are included with PynamoDB for convenience: `JSONAttribute` and `UnicodeDatetimeAttribute`.
+are included with PynamoDB for convenience: ``JSONAttribute`` and ``UnicodeDatetimeAttribute``.
 
 Attribute Methods
 -----------------
 
-All `Attribute` classes must define two methods, `serialize` and `deserialize`. The `serialize` method takes a Python
-value and converts it into a format that can be stored into DynamoDB. The `deserialize` method takes a raw DynamoDB value
-and converts it back into its value in Python. Additionally, a class attribute called `attr_type` is required for PynamoDB
-to know which DynamoDB data type the attribute is stored as.
+All ``Attribute`` classes must define three methods, ``serialize``, ``deserialize`` and ``get_value``. The ``serialize`` method takes a Python
+value and converts it into a format that can be stored into DynamoDB. The ``get_value`` method reads the serialized value out of the DynamoDB record.
+This raw value is then passed to the ``deserialize`` method. The ``deserialize`` method then converts it back into its value in Python.
+Additionally, a class attribute called ``attr_type`` is required for PynamoDB to know which DynamoDB data type the attribute is stored as.
+The ``get_value`` method is provided to help when migrating from one attribute type to another, specifically with the ``BooleanAttribute`` type.
+If you're writing your own attribute and the ``attr_type`` has not changed you can simply use the base ``Attribute`` implementation of ``get_value``.
 
 
 Writing your own attribute
@@ -45,8 +47,8 @@ Custom Attribute Example
 ------------------------
 
 The example below shows how to write a custom attribute that will pickle a customized class. The attribute itself is stored
-in DynamoDB as a binary attribute. The `pickle` module is used to serialize and deserialize the attribute. In this example,
-it is not necessary to define `attr_type` because the `PickleAttribute` class is inheriting from `BinaryAttribute` which has
+in DynamoDB as a binary attribute. The ``pickle`` module is used to serialize and deserialize the attribute. In this example,
+it is not necessary to define ``attr_type`` because the ``PickleAttribute`` class is inheriting from ``BinaryAttribute`` which has
 already defined it.
 
 .. code-block:: python
@@ -107,4 +109,40 @@ Now we can use our custom attribute to round trip any object that can be pickled
 
     >>>instance = CustomAttributeModel.get('red')
     >>>print(instance.obj)
-    <Color: red>
+    <Color: red>
+
+
+List Attributes
+---------------
+
+DynamoDB list attributes are simply lists of other attributes. DynamoDB asserts no requirements about the types embedded within the list.
+DynamoDB is perfectly content with a list of ``UnicodeAttribute`` and ``NumberAttributes`` mixed together. Pynamo can provide type safety if it is required.
+When defining your model use the ``of=`` kwarg and pass in a class. Pynamo will check that all items in the list are of the type you require.
+
+.. code-block:: python
+
+    from pynamodb.attributes import ListAttribute, NumberAttribute, UnicodeAttribute
+
+    class Office(Model):
+        class Meta:
+            table_name = 'OfficeModel'
+        office_id = NumberAttribute(hash_key=True)
+        employees = ListAttribute(of=UnicodeAttribute)
+
+
+Map Attributes
+--------------
+
+DynamoDB map attributes are objects embedded inside of top level models. See the examples `here <https://github.com/jlafon/PynamoDB/tree/devel/examples/office_model.py>`_.
+When implementing your own MapAttribute you can simply extend ``MapAttribute`` and ignore writing serialization code.
+These attributes can then be used inside of Model classes just like any other attribute.
+
+.. code-block:: python
+
+    from pynamodb.attributes import MapAttribute, UnicodeAttribute
+
+    class CarInfoMap(MapAttribute):
+        make = UnicodeAttribute(null=False)
+        model = UnicodeAttribute(null=True)
+
+

examples/office_model.py

@@ -0,0 +1,33 @@
+from pynamodb.attributes import ListAttribute, MapAttribute, NumberAttribute, UnicodeAttribute
+from pynamodb.models import Model
+
+
+class Location(MapAttribute):
+
+    lat = NumberAttribute(attr_name='latitude')
+    lng = NumberAttribute(attr_name='longitude')
+    name = UnicodeAttribute()
+
+
+class Person(MapAttribute):
+
+    fname = UnicodeAttribute(attr_name='firstName')
+    lname = UnicodeAttribute()
+    age = NumberAttribute()
+
+
+class OfficeEmployeeMap(MapAttribute):
+
+    office_employee_id = NumberAttribute()
+    person = Person()
+    office_location = Location()
+
+
+class Office(Model):
+    class Meta:
+        table_name = 'OfficeModel'
+        host = "http://localhost:8000"
+
+    office_id = NumberAttribute(hash_key=True)
+    address = Location()
+    employees = ListAttribute(of=OfficeEmployeeMap)

pynamodb/__init__.py

@@ -7,4 +7,4 @@
 """
 __author__ = 'Jharrod LaFon'
 __license__ = 'MIT'
-__version__ = '1.6.0'
+__version__ = '2.0.0'

pynamodb/attribute_dict.py

@@ -0,0 +1,33 @@
+import collections
+
+
+class AttributeDict(collections.MutableMapping):
+    """
+    A dictionary that stores attributes by two keys
+    """
+    def __init__(self, *args, **kwargs):
+        self._values = {}
+        self._alt_values = {}
+        self.update(dict(*args, **kwargs))
+
+    def __getitem__(self, key):
+        if key in self._alt_values:
+            return self._alt_values[key]
+        return self._values[key]
+
+    def __setitem__(self, key, value):
+        if value.attr_name is not None:
+            self._values[value.attr_name] = value
+        self._alt_values[key] = value
+
+    def __delitem__(self, key):
+        del self._values[key]
+
+    def __iter__(self):
+        return iter(self._alt_values)
+
+    def __len__(self):
+        return len(self._values)
+
+    def aliased_attrs(self):
+        return self._alt_values.items()