PYTHON-690 - Various fixes to indexing docstrings.

doc/api/pymongo/collection.rst

@@ -10,6 +10,7 @@
    .. autodata:: pymongo.GEOHAYSTACK
    .. autodata:: pymongo.GEOSPHERE
    .. autodata:: pymongo.HASHED
+   .. autodata:: pymongo.TEXT
 
    .. autoclass:: pymongo.collection.Collection(database, name[, create=False[, **kwargs]]])
 

pymongo/__init__.py

@@ -26,7 +26,7 @@ GEO2D = "2d"
 
 .. note:: Geo-spatial indexing requires server version **>= 1.3.3**.
 
-.. _geospatial index: http://docs.mongodb.org/manual/core/geospatial-indexes/
+.. _geospatial index: http://docs.mongodb.org/manual/core/2d/
 """
 
 GEOHAYSTACK = "geoHaystack"
@@ -36,7 +36,7 @@ GEOHAYSTACK = "geoHaystack"
 
 .. note:: Geo-spatial indexing requires server version **>= 1.5.6**.
 
-.. _haystack index: http://docs.mongodb.org/manual/core/geospatial-indexes/#haystack-indexes
+.. _haystack index: http://docs.mongodb.org/manual/core/geohaystack/
 """
 
 GEOSPHERE = "2dsphere"
@@ -46,7 +46,7 @@ GEOSPHERE = "2dsphere"
 
 .. note:: 2dsphere indexing requires server version **>= 2.4.0**.
 
-.. _spherical geospatial index: http://docs.mongodb.org/manual/release-notes/2.4/#new-geospatial-indexes-with-geojson-and-improved-spherical-geometry
+.. _spherical geospatial index: http://docs.mongodb.org/manual/core/2dsphere/
 """
 
 HASHED = "hashed"
@@ -56,7 +56,17 @@ HASHED = "hashed"
 
 .. note:: hashed indexing requires server version **>= 2.4.0**.
 
-.. _hashed index: http://docs.mongodb.org/manual/release-notes/2.4/#new-hashed-index-and-sharding-with-a-hashed-shard-key
+.. _hashed index: http://docs.mongodb.org/manual/core/index-hashed/
+"""
+
+TEXT = "text"
+"""Index specifier for a `text index`_.
+
+.. versionadded:: 2.7.1
+
+.. note:: text search requires server version **>= 2.4.0**.
+
+.. _text index: http://docs.mongodb.org/manual/core/index-text/
 """
 
 OFF = 0

pymongo/collection.py

@@ -953,29 +953,36 @@ class Collection(common.BaseObject):
         (:class:`str` in python 3), and the direction(s) must be one of
         (:data:`~pymongo.ASCENDING`, :data:`~pymongo.DESCENDING`,
         :data:`~pymongo.GEO2D`, :data:`~pymongo.GEOHAYSTACK`,
-        :data:`~pymongo.GEOSPHERE`, :data:`~pymongo.HASHED`).
+        :data:`~pymongo.GEOSPHERE`, :data:`~pymongo.HASHED`,
+        :data:`~pymongo.TEXT`).
 
-        To create a single key index on the key ``'mike'`` we just use
-        a string argument:
+        To create a single key ascending index on the key ``'mike'`` we just
+        use a string argument::
 
-        >>> my_collection.create_index("mike")
+          >>> my_collection.create_index("mike")
 
         For a compound index on ``'mike'`` descending and ``'eliot'``
-        ascending we need to use a list of tuples:
+        ascending we need to use a list of tuples::
 
-        >>> my_collection.create_index([("mike", pymongo.DESCENDING),
-        ...                             ("eliot", pymongo.ASCENDING)])
+          >>> my_collection.create_index([("mike", pymongo.DESCENDING),
+          ...                             ("eliot", pymongo.ASCENDING)])
 
         All optional index creation parameters should be passed as
-        keyword arguments to this method. Valid options include:
+        keyword arguments to this method. For example::
+
+          >>> my_collection.create_index([("mike", pymongo.DESCENDING)],
+          ...                            background=True)
+
+        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
-          - `background`: if this index should be created in the
+          - `unique`: if ``True`` creates a uniqueness constraint on the index
+          - `dropDups` or `drop_dups`: if ``True`` duplicate values are dropped
+            during index creation when creating a unique index
+          - `background`: if ``True`` this index should be created in the
             background
-          - `sparse`: if True, omit from the index any documents that lack
+          - `sparse`: if ``True``, omit from the index any documents that lack
             the indexed field
           - `bucketSize` or `bucket_size`: for use with geoHaystack indexes.
             Number of documents to group together within a certain proximity
@@ -1071,8 +1078,10 @@ class Collection(common.BaseObject):
         (:class:`str` in python 3), and the direction(s) must be one of
         (:data:`~pymongo.ASCENDING`, :data:`~pymongo.DESCENDING`,
         :data:`~pymongo.GEO2D`, :data:`~pymongo.GEOHAYSTACK`,
-        :data:`~pymongo.GEOSPHERE`, :data:`~pymongo.HASHED`).
-        See :meth:`create_index` for a detailed example.
+        :data:`~pymongo.GEOSPHERE`, :data:`~pymongo.HASHED`,
+        :data:`pymongo.TEXT`).
+
+        See :meth:`create_index` for detailed examples.
 
         Unlike :meth:`create_index`, which attempts to create an index
         unconditionally, :meth:`ensure_index` takes advantage of some
@@ -1098,12 +1107,12 @@ class Collection(common.BaseObject):
 
           - `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
+          - `unique`: if ``True`` creates a uniqueness constraint on the index
+          - `dropDups` or `drop_dups`: if ``True`` duplicate values are dropped
+            during index creation when creating a unique index
+          - `background`: if ``True`` this index should be created in the
             background
-          - `sparse`: if True, omit from the index any documents that lack
+          - `sparse`: if ``True``, omit from the index any documents that lack
             the indexed field
           - `bucketSize` or `bucket_size`: for use with geoHaystack indexes.
             Number of documents to group together within a certain proximity

test/test_collection.py

@@ -34,7 +34,7 @@ from bson.objectid import ObjectId
 from bson.py3compat import u, itervalues
 from bson.son import SON, RE_TYPE
 from pymongo import (ASCENDING, DESCENDING, GEO2D,
-                     GEOHAYSTACK, GEOSPHERE, HASHED)
+                     GEOHAYSTACK, GEOSPHERE, HASHED, TEXT)
 from pymongo import message as message_module
 from pymongo.collection import Collection
 from pymongo.command_cursor import CommandCursor
@@ -404,7 +404,7 @@ class TestCollection(unittest.TestCase):
 
         db = self.db
         db.test.drop_indexes()
-        self.assertEqual("t_text", db.test.create_index([("t", "text")]))
+        self.assertEqual("t_text", db.test.create_index([("t", TEXT)]))
         index_info = db.test.index_information()["t_text"]
         self.assertTrue("weights" in index_info)