Merge pull request #185 from aerospike/data_conversion_documentation

Make documentation of python type to as_type more prominent

doc/client.rst

@@ -1442,6 +1442,10 @@ a cluster-tending thread.
             elements in the list will correspond to the order of the operations \
             from the input parameters.
 
+            .. warning::
+
+                Unlike :meth:`operate` this function will apply each of the operations separately, making multiple calls to the server.
+
             :param tuple key: a :ref:`aerospike_key_tuple` associated with the record.
             :param list list: a :class:`list` of one or more bin operations, each \
                 structured as the :class:`dict` \

doc/data_mapping.rst

@@ -0,0 +1,62 @@
+.. _Data_Mapping:
+
+*************************************************
+:mod:`Data_Mapping` --- Python Data Mappings
+*************************************************
+
+.. rubric:: How Python types map to server types
+
+.. note::
+
+    By default, the :py:class:`aerospike.Client` maps the supported types \
+    :py:class:`int`, :py:class:`str`, :py:class:`float`, :py:class:`bytearray`, \
+    :py:class:`list`, :py:class:`dict` to matching aerospike server \
+    `types <http://www.aerospike.com/docs/guide/data-types.html>`_ \
+    (int, string, double, blob, list, map). When an unsupported type is \
+    encountered, the module uses \
+    `cPickle <https://docs.python.org/2/library/pickle.html?highlight=cpickle#module-cPickle>`_ \
+    to serialize and deserialize the data, storing it into a blob of type \
+    `'Python' <https://www.aerospike.com/docs/udf/api/bytes.html#encoding-type>`_ \
+    (`AS_BYTES_PYTHON <http://www.aerospike.com/apidocs/c/d0/dd4/as__bytes_8h.html#a0cf2a6a1f39668f606b19711b3a98bf3>`_).
+
+    The functions :func:`~aerospike.set_serializer` and :func:`~aerospike.set_deserializer` \
+    allow for user-defined functions to handle serialization, instead. The user provided function will be run instead of cPickle. \
+    The serialized data is stored as \
+    type (\
+    `AS_BYTES_BLOB <http://www.aerospike.com/apidocs/c/d0/dd4/as__bytes_8h.html#a0cf2a6a1f39668f606b19711b3a98bf3>`_). \
+    This type allows the storage of binary data readable by Aerospike Clients in other languages. \
+    The *serialization* config param of :func:`aerospike.client` registers an \
+    instance-level pair of functions that handle serialization.
+
+    Unless a user specified serializer has been provided, all other types will be stored as Python specific bytes. Python specific bytes may not be readable by Aerospike Clients for other languages.
+
+The following table shows which Python types map directly to Aerospike server types.
+
++--------------------------+--------------+
+| Python Type              | server type  |
++==========================+==============+
+|int                       |integer       |
++--------------------------+--------------+
+|long                      |integer       |
++--------------------------+--------------+
+|str                       |string        |
++--------------------------+--------------+
+|unicode                   |string        |
++--------------------------+--------------+
+|float                     |double        |
++--------------------------+--------------+
+|dict                      |map           |
++--------------------------+--------------+
+|list                      |list          |
++--------------------------+--------------+
+|bytearray                 |blob          |
++--------------------------+--------------+
+|aerospike.GeoJSON         |GeoJSON       |
++--------------------------+--------------+
+
+It is possible to nest these datatypes. For example a list may contain a dictionary, or a dictionary may contain a list as a value.
+
+.. note::
+
+	Unless a user specified serializer has been provided, all other types will be stored as Python specific bytes. Python specific bytes may not be readable by Aerospike Clients for other languages.
+

doc/geojson.rst

@@ -55,7 +55,7 @@ GeoJSON Class --- :class:`GeoJSON`
         client.put(('test', 'pads', 'launchpad1'), bins)
 
         # Read the record.
-        (k, m, b) = client.get(('test', 'demo', 'launchpad1'))
+        (k, m, b) = client.get(('test', 'pads', 'launchpad1'))
         print(b)
         client.close()
 

doc/index.rst

@@ -12,6 +12,8 @@ the Aerospike C client.
 
 * :mod:`aerospike.exception` is a submodule containing the exception hierarchy for AerospikeError and its subclasses.
 
+* :ref:`Data_Mapping` How Python types map to Aerospike Server types
+
 .. seealso::
     The `Python Client Manual <http://www.aerospike.com/docs/client/python/>`_
     for a quick guide.
@@ -23,6 +25,7 @@ Content
     :maxdepth: 3
 
     aerospike
+    data_mapping
     client
     scan
     query

doc/llist.rst

@@ -6,11 +6,18 @@
 Large Ordered List Class --- :class:`LList`
 =============================================
 
+.. warning::
+    LDT Functionality is deprecated as of version 2.1.2 and will be removed in a future release of the Python Client
+
 :class:`LList`
 ===============
 
 .. class:: LList
 
+    .. deprecated:: 2.1.2
+        See `Blog about LDT Removal <http://www.aerospike.com/blog/aerospike-ldt>`_ \
+        for more information.
+
     Large Ordered List (LList) is a collection of elements sorted by ``key`` \
     order, which is capable of growing unbounded. There are two ways in which \
     an element is sorted and located: