diff --git a/cassandra/util.py b/cassandra/util.py index 8400b604..1ff1fe75 100644 --- a/cassandra/util.py +++ b/cassandra/util.py @@ -563,11 +563,30 @@ from six.moves import cPickle class OrderedMap(Mapping): ''' - An ordered map that accepts non-hashable types for keys. + An ordered map that accepts non-hashable types for keys. It also maintains the + insertion order of items, behaving as OrderedDict in that regard. These maps + are constructed and read just as normal mapping types, exept that they may + contain arbitrary collections and other non-hashable items as keys:: + + >>> od = OrderedMap([({'one': 1, 'two': 2}, 'value'), + ... ({'three': 3, 'four': 4}, 'value2')]) + >>> list(od.keys()) + [{'two': 2, 'one': 1}, {'three': 3, 'four': 4}] + >>> list(od.values()) + ['value', 'value2'] + + These constructs are needed to support nested collections in Cassandra 2.1.3+, + where frozen collections can be specified as parameters to others:: + + CREATE TABLE example ( + ... + value map>, double> + ... + ) + + This class dervies from the (immutable) Mapping API. Objects in these maps + are not intended be modified. - Implemented in support of Cassandra nested collections. This class dervies from - the (immutable) Mapping API. Although clients may obtain references, keys in - the map should not be modified. ''' def __init__(self, *args, **kwargs): if len(args) > 1: diff --git a/docs/api/cassandra/util.rst b/docs/api/cassandra/util.rst new file mode 100644 index 00000000..2e79758d --- /dev/null +++ b/docs/api/cassandra/util.rst @@ -0,0 +1,7 @@ +``cassandra.util`` - Utilities +=================================== + +.. module:: cassandra.util + +.. autoclass:: OrderedMap + :members: diff --git a/docs/api/index.rst b/docs/api/index.rst index 7db7c7ee..d6555555 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -16,6 +16,7 @@ API Documentation cassandra/decoder cassandra/concurrent cassandra/connection + cassandra/util cassandra/io/asyncorereactor cassandra/io/libevreactor cassandra/io/geventreactor