diff --git a/cassandra/encoder.py b/cassandra/encoder.py index 7c0afd66..6058d5da 100644 --- a/cassandra/encoder.py +++ b/cassandra/encoder.py @@ -11,6 +11,11 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. +""" +These functions are used to convert Python objects into CQL strings. +When non-prepared statements are executed, these encoder functions are +called on each query parameter. +""" import logging log = logging.getLogger(__name__) @@ -45,14 +50,23 @@ def cql_quote(term): def cql_encode_none(val): + """ + Converts :const:`None` to the string 'NULL'. + """ return 'NULL' def cql_encode_unicode(val): + """ + Converts :class:`unicode` objects to UTF-8 encoded strings with quote escaping. + """ return cql_quote(val.encode('utf-8')) def cql_encode_str(val): + """ + Escapes quotes in :class:`str` objects. + """ return cql_quote(val) @@ -69,25 +83,51 @@ else: def cql_encode_object(val): + """ + Default encoder for all objects that do not have a specific encoder function + registered. This function simply calls :meth:`str()` on the object. + """ return str(val) def cql_encode_datetime(val): + """ + Converts a :class:`datetime.datetime` object to a (string) integer timestamp + with millisecond precision. + """ timestamp = calendar.timegm(val.utctimetuple()) return str(long(timestamp * 1e3 + getattr(val, 'microsecond', 0) / 1e3)) def cql_encode_date(val): + """ + Converts a :class:`datetime.date` object to a string with format + ``YYYY-MM-DD-0000``. + """ return "'%s'" % val.strftime('%Y-%m-%d-0000') def cql_encode_sequence(val): + """ + Converts a sequence to a string of the form ``(item1, item2, ...)``. This + is suitable for ``IN`` value lists. + """ return '( %s )' % ' , '.join(cql_encoders.get(type(v), cql_encode_object)(v) for v in val) + + cql_encode_tuple = cql_encode_sequence +""" +Converts a sequence to a string of the form ``(item1, item2, ...)``. This +is suitable for ``tuple`` type columns. +""" def cql_encode_map_collection(val): + """ + Converts a dict into a string of the form ``{key1: val1, key2: val2, ...}``. + This is suitable for ``map`` type columns. + """ return '{ %s }' % ' , '.join('%s : %s' % ( cql_encode_all_types(k), cql_encode_all_types(v) @@ -95,14 +135,26 @@ def cql_encode_map_collection(val): def cql_encode_list_collection(val): + """ + Converts a sequence to a string of the form ``[item1, item2, ...]``. This + is suitable for ``list`` type columns. + """ return '[ %s ]' % ' , '.join(map(cql_encode_all_types, val)) def cql_encode_set_collection(val): + """ + Converts a sequence to a string of the form ``{item1, item2, ...}``. This + is suitable for ``set`` type columns. + """ return '{ %s }' % ' , '.join(map(cql_encode_all_types, val)) def cql_encode_all_types(val): + """ + Converts any type into a CQL string, defaulting to ``cql_encode_object`` + if :attr:`~.cql_encoders` does not contain an entry for the type. + """ return cql_encoders.get(type(val), cql_encode_object)(val) @@ -122,6 +174,9 @@ cql_encoders = { frozenset: cql_encode_set_collection, types.GeneratorType: cql_encode_list_collection } +""" +A map of python types to encoder functions. +""" if six.PY2: cql_encoders.update({ diff --git a/docs/api/cassandra/encoder.rst b/docs/api/cassandra/encoder.rst new file mode 100644 index 00000000..9507f929 --- /dev/null +++ b/docs/api/cassandra/encoder.rst @@ -0,0 +1,43 @@ +``cassandra.encoder`` - Encoders for non-prepared Statements +============================================================ + +.. module:: cassandra.encoder + +.. data:: cql_encoders + + A map of python types to encoder functions. + +.. autofunction:: cql_encode_none () + +.. autofunction:: cql_encode_object () + +.. autofunction:: cql_encode_all_types () + +.. autofunction:: cql_encode_sequence () + +String Types +------------ + +.. autofunction:: cql_encode_str () + +.. autofunction:: cql_encode_unicode () + +.. autofunction:: cql_encode_bytes () + +Date Types +---------- + +.. autofunction:: cql_encode_datetime () + +.. autofunction:: cql_encode_date () + +Collection Types +---------------- + +.. autofunction:: cql_encode_map_collection () + +.. autofunction:: cql_encode_list_collection () + +.. autofunction:: cql_encode_set_collection () + +.. autofunction:: cql_encode_tuple () diff --git a/docs/api/cassandra/metrics.rst b/docs/api/cassandra/metrics.rst index 755ab429..0df7f8b5 100644 --- a/docs/api/cassandra/metrics.rst +++ b/docs/api/cassandra/metrics.rst @@ -2,7 +2,6 @@ =========================================== .. module:: cassandra.metrics - :members: .. autoclass:: cassandra.metrics.Metrics () :members: diff --git a/docs/api/index.rst b/docs/api/index.rst index 65545028..fc083c6a 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -12,6 +12,7 @@ API Documentation cassandra/metrics cassandra/query cassandra/pool + cassandra/encoder cassandra/decoder cassandra/concurrent cassandra/connection