Update docs for pycassa.types and CFMap

doc/assorted/column_family_map.rst

@@ -3,93 +3,77 @@ Class Mapping with Column Family Map
 You can map existing classes to column families using
 :class:`~pycassa.columnfamilymap.ColumnFamilyMap`.
 
+To specify the fields to be persisted, use any of the
+subclasses of :class:`pycassa.types.CassandraType` available
+in :mod:`pycassa.types`.
+
 .. code-block:: python
 
-  >>> class Test(object):
-  ...     string_column       = pycassa.String(default='Your Default')
-  ...     int_str_column      = pycassa.IntString(default=5)
-  ...     float_str_column    = pycassa.FloatString(default=8.0)
-  ...     float_column        = pycassa.Float64(default=0.0)
-  ...     datetime_str_column = pycassa.DateTimeString() # default=None
+  >>> from pycassa.types import *
+  >>> class User(object):
+  ...     key = LexicalUUIDType()
+  ...     name = Utf8Type()
+  ...     age = IntegerType()
+  ...     height = FloatType()
+  ...     score = DoubleType(default=0.0)
+  ...     joined = DateType()
 
 The defaults will be filled in whenever you retrieve instances from the
 Cassandra server and the column doesn't exist. If you want to add a
 column in the future, you can simply add the relevant attribute to the class
 and the default value will be used when you get old instances.
 
-:class:`~pycassa.types.IntString`, :class:`~pycassa.types.FloatString`, and
-:class:`~pycassa.types.DateTimeString` all use string representations for
-storage. :class:`~pycassa.types.Float64` is stored as a double and is
-native-endian. Be aware of any endian issues if you use it on different
-architectures, or perhaps make your own column type.
-
 .. code-block:: python
 
-  >>> pool = pycassa.ConnectionPool('Keyspace1')
-  >>> cf = pycassa.ColumnFamily(pool, 'Standard1', autopack_names=False, autopack_values=False)
-  >>> Test.objects = pycassa.ColumnFamilyMap(Test, cf)
+  >>> from pycassa.pool import ConnectionPool
+  >>> from pycassa.columnfamilymap import ColumnFamilyMap
+  >>>
+  >>> pool = ConnectionPool('Keyspace1')
+  >>> cfmap = ColumnFamilyMap(pool, User, 'users')
 
-.. note:: As shown in the example, `autopack_names` and `autopack_values` should
-          be set to ``False`` when a ColumnFamily is used with a ColumnFamilyMap.
-
-All the functions are exactly the same, except that they return
-instances of the supplied class when possible.
+All the functions are exactly the same as for :class:`ColumnFamily`,
+except that they return instances of the supplied class when possible.
 
 .. code-block:: python
 
-  >>> t = Test()
-  >>> t.key = 'maptest'
-  >>> t.string_column = 'string test'
-  >>> t.int_str_column = 18
-  >>> t.float_column = t.float_str_column = 35.8
   >>> from datetime import datetime
-  >>> t.datetime_str_column = datetime.now()
-  >>> Test.objects.insert(t)
+  >>> import uuid
+  >>>
+  >>> key = uuid.uuid4()
+  >>>
+  >>> user = User()
+  >>> user.key = key
+  >>> user.name = 'John'
+  >>> user.age = 18
+  >>> user.height = 5.9
+  >>> user.joined = datetime.now()
+  >>> cfmap.insert(user)
   1261395560186855
 
 .. code-block:: python
 
-  >>> Test.objects.get(t.key).string_column
-  'string test'
-  >>> Test.objects.get(t.key).int_str_column
+  >>> user = cfmap.get(key)
+  >>> user.name
+  "John"
+  >>> user.age
   18
-  >>> Test.objects.get(t.key).float_column
-  35.799999999999997
-  >>> Test.objects.get(t.key).datetime_str_column
-  datetime.datetime(2009, 12, 23, 17, 6, 3)
 
 .. code-block:: python
 
-  >>> Test.objects.multiget([t.key])
-  {'maptest': <__main__.Test object at 0x7f8ddde0b9d0>}
-  >>> list(Test.objects.get_range())
-  [<__main__.Test object at 0x7f8ddde0b710>]
-  >>> Test.objects.get_count(t.key)
-  5
+  >>> users = cfmap.multiget([key1, key2])
+  >>> print users[0].name
+  "John"
+  >>> for user in cfmap.get_range():
+  ...    print user.name
+  "John"
+  "Bob"
+  "Alex"
 
 .. code-block:: python
 
-  >>> Test.objects.remove(t)
+  >>> cfmap.remove(user)
   1261395603906864
-  >>> Test.objects.get(t.key)
+  >>> cfmap.get(user.key)
   Traceback (most recent call last):
   ...
   cassandra.ttypes.NotFoundException: NotFoundException()
-
-You may also use a ColumnFamilyMap with super columns:
-
-.. code-block:: python
-
-  >>> Test.objects = pycassa.ColumnFamilyMap(Test, cf)
-  >>> t = Test()
-  >>> t.key = 'key1'
-  >>> t.super_column = 'super1'
-  >>> t.string_column = 'foobar'
-  >>> t.int_str_column = 5
-  >>> t.float_column = t.float_str_column = 35.8
-  >>> t.datetime_str_column = datetime.now()
-  >>> Test.objects.insert(t)
-  >>> Test.objects.get(t.key)
-  {'super1': <__main__.Test object at 0x20ab350>}
-  >>> Test.objects.multiget([t.key])
-  {'key1': {'super1': <__main__.Test object at 0x20ab550>}}

pycassa/types.py

@@ -3,6 +3,23 @@
 class CassandraType(object):
 
     def __init__(self, reversed=False, default=None):
+        """
+        A data type that Cassandra is aware of and knows
+        how to validate and sort.
+
+        If `reversed` is true and this is used as a column comparator,
+        the columns will be sorted in reverse order.
+
+        This is also used to specify fields to be persisted when
+        a class is used with :class:`~.ColumnFamilyMap`.
+
+        The `default` parameter only applies to use of this
+        with ColumnFamilyMap, where `default` is used if a row
+        does not contain a column corresponding to this item.
+
+        .. versionadded:: 1.2.0
+
+        """
         self.reversed = reversed
         self.default = default
         self.pack = marshal.packer_for(self.__class__.__name__)
@@ -25,6 +42,11 @@ class IntegerType(CassandraType):
     is a more compact format for storing small integers
     than :class:`~.LongType`, and the limits
     on the size of the integer are much higher.
+
+    .. versionchanged:: 1.2.0
+        Prior to 1.2.0, this was always stored as a 4 byte
+        integer.
+
     """
     pass
 
@@ -49,22 +71,40 @@ class CounterColumnType(CassandraType):
     pass
 
 class DoubleType(CassandraType):
-    """ Stores data as an 8 byte double """
+    """
+    Stores data as an 8 byte double.
+
+    .. versionadded:: 1.2.0
+
+    """
     pass
 
 class FloatType(CassandraType):
-    """ Stores data as an 4 byte float """
+    """
+    Stores data as an 4 byte float.
+
+    .. versionadded:: 1.2.0
+
+    """
     pass
 
 class BooleanType(CassandraType):
-    """ Stores data as a 1 byte boolean """
+    """
+    Stores data as a 1 byte boolean.
+
+    .. versionadded:: 1.2.0
+
+    """
     pass
 
 class DateType(CassandraType):
     """
     An 8 byte timestamp. This will be returned
     as a :class:`datetime.datetime` instance by pycassa. Either
     :class:`datetime` instances or timestamps will be accepted.
+
+    .. versionadded:: 1.2.0
+
     """
     pass
 
@@ -79,6 +119,9 @@ class CompositeType(CassandraType):
     a subclass of :class:`CassandraType`.
 
     .. seealso:: :ref:`composite-types`
+
+    .. versionadded:: 1.2.0
+
     """
 
     def __init__(self, *components):