def sort(self, key_or_list, direction=None):
"""Sorts this cursor's results.
Takes either a single key and a direction, or a list of (key,
direction) pairs. The key(s) must be an instance of ``(str,
unicode)``, and the direction(s) must be one of
(:data:`~apymongo.ASCENDING`,
:data:`~apymongo.DESCENDING`). Raises
:class:`~apymongo.errors.InvalidOperation` if this cursor has
already been used. Only the last :meth:`sort` applied to this
cursor has any effect.
:Parameters:
- `key_or_list`: a single key or a list of (key, direction)
pairs specifying the keys to sort on
- `direction` (optional): only used if `key_or_list` is a single
key, if not given :data:`~apymongo.ASCENDING` is assumed
"""
self.__check_okay_to_chain()
keys = helpers._index_list(key_or_list, direction)
self.__ordering = helpers._index_document(keys)
return self
def sort(self, key_or_list, direction=None):
"""Sorts this cursor's results.
Takes either a single key and a direction, or a list of (key,
direction) pairs. The key(s) must be an instance of ``(str,
unicode)``, and the direction(s) must be one of
(:data:`~pymongo.ASCENDING`,
:data:`~pymongo.DESCENDING`). Raises
:class:`~pymongo.errors.InvalidOperation` if this cursor has
already been used. Only the last :meth:`sort` applied to this
cursor has any effect.
:Parameters:
- `key_or_list`: a single key or a list of (key, direction)
pairs specifying the keys to sort on
- `direction` (optional): only used if `key_or_list` is a single
key, if not given :data:`~pymongo.ASCENDING` is assumed
"""
self.__check_okay_to_chain()
keys = helpers._index_list(key_or_list, direction)
self.__ordering = helpers._index_document(keys)
return self
def ensure_index(self, key_or_list, callback=None,deprecated_unique=None,
ttl=300, **kwargs):
"""Ensures that an index exists on this collection.
Takes either a single key or a list of (key, direction) pairs.
The key(s) must be an instance of :class:`basestring`, and the
direction(s) must be one of (:data:`~pymongo.ASCENDING`,
:data:`~pymongo.DESCENDING`, :data:`~pymongo.GEO2D`). See
:meth:`create_index` for a detailed example.
Unlike :meth:`create_index`, which attempts to create an index
unconditionally, :meth:`ensure_index` takes advantage of some
caching within the driver such that it only attempts to create
indexes that might not already exist. When an index is created
(or ensured) by PyMongo it is "remembered" for `ttl`
seconds. Repeated calls to :meth:`ensure_index` within that
time limit will be lightweight - they will not attempt to
actually create the index.
Care must be taken when the database is being accessed through
multiple connections at once. If an index is created using
APyMongo and then deleted using another connection any call to
:meth:`ensure_index` within the cache window will fail to
re-create the missing index.
Passes the name of the created index to the callback if an index is actually
created. Passes ``None`` if the index already exists. Otherwise, passes
whatever errors are encountered.
All optional index creation paramaters should be passed as
keyword arguments to this method. Valid options include:
- `name`: custom name to use for this index - if none is
given, a name will be generated
- `unique`: should this index guarantee uniqueness?
- `dropDups` or `drop_dups`: should we drop duplicates
during index creation when creating a unique index?
- `background`: if this index should be created in the
background
- `min`: minimum value for keys in a :data:`~pymongo.GEO2D`
index
- `max`: maximum value for keys in a :data:`~pymongo.GEO2D`
index
:Parameters:
- `key_or_list`: a single key or a list of (key, direction)
pairs specifying the index to create
- `deprecated_unique`: DEPRECATED - use `unique` as a kwarg
- `ttl` (optional): time window (in seconds) during which
this index will be recognized by subsequent calls to
:meth:`ensure_index`
- `**kwargs` (optional): any additional index creation
options (see the above list) should be passed as keyword
arguments
.. seealso:: :meth:`create_index`
"""
if "name" in kwargs:
name = kwargs["name"]
else:
keys = helpers._index_list(key_or_list)
name = kwargs["name"] = _gen_index_name(keys)
if self.__database.connection._cache_index(self.__database.name,
self.__name, name, ttl):
self.create_index(key_or_list, deprecated_unique = deprecated_unique,
ttl = ttl, callback = callback, **kwargs)
elif callback:
callback(None)
def create_index(self, key_or_list, deprecated_unique=None,
ttl=300, callback = None, **kwargs):
"""Creates an index on this collection.
Takes either a single key or a list of (key, direction) pairs.
The key(s) must be an instance of :class:`basestring`, and the
directions must be one of (:data:`~apymongo.ASCENDING`,
:data:`~apymongo.DESCENDING`, :data:`~apymongo.GEO2D`). Returns
the name of the created index.
To create a single key index on the key ``'mike'`` we just use
a string argument:
>>> my_collection.create_index("mike")
For a compound index on ``'mike'`` descending and ``'eliot'``
ascending we need to use a list of tuples:
>>> my_collection.create_index([("mike", pymongo.DESCENDING),
... ("eliot", pymongo.ASCENDING)])
All optional index creation paramaters should be passed as
keyword arguments to this method. Valid options include:
- `name`: custom name to use for this index - if none is
given, a name will be generated
- `unique`: should this index guarantee uniqueness?
- `dropDups` or `drop_dups`: should we drop duplicates
during index creation when creating a unique index?
- `min`: minimum value for keys in a :data:`~pymongo.GEO2D`
index
- `max`: maximum value for keys in a :data:`~pymongo.GEO2D`
index
:Parameters:
- `key_or_list`: a single key or a list of (key, direction)
pairs specifying the index to create
- `deprecated_unique`: DEPRECATED - use `unique` as a kwarg
- `ttl` (optional): time window (in seconds) during which
this index will be recognized by subsequent calls to
:meth:`ensure_index` - see documentation for
:meth:`ensure_index` for details
- `**kwargs` (optional): any additional index creation
options (see the above list) should be passed as keyword
arguments
.. seealso:: :meth:`ensure_index`
.. mongodoc:: indexes
"""
keys = helpers._index_list(key_or_list)
index_doc = helpers._index_document(keys)
index = {"key": index_doc, "ns": self.__full_name}
if deprecated_unique is not None:
warnings.warn("using a positional arg to specify unique is "
"deprecated, please use kwargs",
DeprecationWarning)
index["unique"] = deprecated_unique
name = "name" in kwargs and kwargs["name"] or _gen_index_name(keys)
index["name"] = name
if "drop_dups" in kwargs:
kwargs["dropDups"] = kwargs.pop("drop_dups")
index.update(kwargs)
def mod_callback(resp):
if not isinstance(resp,Exception):
self.__database.connection._cache_index(self.__database.name,
self.__name, name, ttl)
if callback:
callback(name)
else:
if callback:
callback(resp)
else:
raise resp
self.__database.system.indexes.insert(index, manipulate=False,
check_keys=False,
safe=True,callback = mod_callback)
