API CHANGE: deprecating passing direction to ensure_index, create_index for single key - just creates an ascending index since direction doesn't matter

Author: Mike Dirolf

README.rst

@@ -51,9 +51,9 @@ ObjectId('\t6\xc6\x07\xb3\xfc\x87\xc4\x82\x04\x0f\\')
 10
 8
 11
->>> from pymongo import ASCENDING
->>> db.my_collection.create_index("x", ASCENDING)
+>>> db.my_collection.create_index("x")
 u'x_1'
+>>> from pymongo import ASCENDING
 >>> for item in db.my_collection.find().sort("x", ASCENDING):
 ... print item["x"]
 ...

examples/quick_tour.py

@@ -82,8 +82,7 @@
 for d in collection.find({"i": {"$gt": 20, "$lte": 30}}):
  print d
 
-# Finally, we can create an ascending index on i, and print out the collection's
+# Finally, we can create an index on i, and print out the collection's
 # dictionary of indexes.
-from pymongo import ASCENDING
-collection.create_index("i", ASCENDING)
+collection.create_index("i")
 print collection.index_information()

pymongo/__init__.py

@@ -48,16 +48,16 @@
  _SEEK_CUR = 1
  _SEEK_END = 2
 
-def _index_list(key_or_list, direction):
+def _index_list(key_or_list, direction=None):
  """Helper to generate a list of (key, direction) pairs.
 
- Takes such a list, or a single key and direction.
+ Takes such a list, or a single key, or a single key and direction.
  """
  if direction is not None:
  return [(key_or_list, direction)]
  else:
  if isinstance(key_or_list, types.StringTypes):
- raise TypeError("must specify a direction if using a string key")
+ return [(key_or_list, ASCENDING)]
  return key_or_list
 
 
@@ -67,7 +67,7 @@ def _index_document(index_list):
  Takes a list of (key, direction) pairs.
  """
  if not isinstance(index_list, types.ListType):
- raise TypeError("if no direction is specified, key_or_list must be an"
+ raise TypeError("if no direction is specified, key_or_list must be an "
  "instance of list")
  if not len(index_list):
  raise ValueError("key_or_list must not be the empty list")
@@ -77,7 +77,7 @@ def _index_document(index_list):
  if not isinstance(key, types.StringTypes):
  raise TypeError("first item in each key pair must be a string")
  if not isinstance(value, types.IntType):
- raise TypeError("second item in each key pair must be ASCENDING or"
+ raise TypeError("second item in each key pair must be ASCENDING or "
  "DESCENDING")
  index[key] = value
  return index

pymongo/collection.py

@@ -15,6 +15,7 @@
 """Collection level utilities for Mongo."""
 
 import types
+import warnings
 
 import pymongo
 import bson
@@ -389,16 +390,15 @@ def _gen_index_name(self, keys):
  def create_index(self, key_or_list, direction=None, unique=False, ttl=300):
  """Creates an index on this collection.
 
- 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 (`pymongo.ASCENDING`,
+ Takes either a single key or a list of (key, direction) pairs.
+ The key(s) must be an instance of (str, unicode),
+ and the directions must be one of (`pymongo.ASCENDING`,
  `pymongo.DESCENDING`). Returns the name of the created index.
 
  :Parameters:
  - `key_or_list`: a single key or a list of (key, direction) pairs
  specifying the index to create
- - `direction` (optional): must be included if key_or_list is a single
- key, otherwise must be None
+ - `direction` (optional): DEPRECATED this option will be removed
  - `unique` (optional): should this index guarantee uniqueness?
  - `ttl` (optional): time window (in seconds) during which this index
  will be recognized by subsequent calls to `ensure_index` - see
@@ -407,8 +407,14 @@ def create_index(self, key_or_list, direction=None, unique=False, ttl=300):
  if not isinstance(key_or_list, (str, unicode, list)):
  raise TypeError("key_or_list must either be a single key or a list of (key, direction) pairs")
 
+ if direction is not None:
+ warnings.warn("specifying a direction for a single key index is "
+ "deprecated and will be removed. there is no need "
+ "for a direction on a single key index",
+ DeprecationWarning)
+
  to_save = SON()
- keys = pymongo._index_list(key_or_list, direction)
+ keys = pymongo._index_list(key_or_list)
  name = self._gen_index_name(keys)
  to_save["name"] = name
  to_save["ns"] = self.full_name()
@@ -426,8 +432,8 @@ def create_index(self, key_or_list, direction=None, unique=False, ttl=300):
  def ensure_index(self, key_or_list, direction=None, unique=False, ttl=300):
  """Ensures that an index exists on this collection.
 
- 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),
+ Takes either a single key 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 (`pymongo.ASCENDING`,
  `pymongo.DESCENDING`).
 
@@ -450,21 +456,26 @@ def ensure_index(self, key_or_list, direction=None, unique=False, ttl=300):
  :Parameters:
  - `key_or_list`: a single key or a list of (key, direction) pairs
  specifying the index to ensure
- - `direction` (optional): must be included if key_or_list is a single
- key, otherwise must be None
+ - `direction` (optional): DEPRECATED this option will be removed
  - `unique` (optional): should this index guarantee uniqueness?
  - `ttl` (optional): time window (in seconds) during which this index
  will be recognized by subsequent calls to `ensure_index`
  """
  if not isinstance(key_or_list, (str, unicode, list)):
  raise TypeError("key_or_list must either be a single key or a list of (key, direction) pairs")
 
- keys = pymongo._index_list(key_or_list, direction)
+ if direction is not None:
+ warnings.warn("specifying a direction for a single key index is "
+ "deprecated and will be removed. there is no need "
+ "for a direction on a single key index",
+ DeprecationWarning)
+
+ keys = pymongo._index_list(key_or_list)
  name = self._gen_index_name(keys)
  if self.database().connection()._cache_index(self.__database.name(),
  self.name(),
  name, ttl):
- return self.create_index(key_or_list, direction, unique, ttl)
+ return self.create_index(key_or_list, unique=unique, ttl=ttl)
  return None
 
  def drop_indexes(self):
@@ -483,8 +494,9 @@ def drop_index(self, index_or_name):
  Can be used on non-existant collections or collections with no indexes.
  Raises OperationFailure on an error. `index_or_name` can be either an
  index name (as returned by `create_index`), or an index specifier (as
- passed to `create_index`). Raises TypeError if index is not an
- instance of (str, unicode, list).
+ passed to `create_index`). An index specifier should be a list of (key,
+ direction) pairs. Raises TypeError if index is not an instance of (str,
+ unicode, list).
 
  :Parameters:
  - `index_or_name`: index (or name of index) to drop

pymongo/cursor.py

@@ -224,8 +224,8 @@ def sort(self, key_or_list, direction=None):
  :Parameters:
  - `key_or_list`: a single key or a list of (key, direction) pairs
  specifying the keys to sort on
- - `direction` (optional): must be included if key_or_list is a single
- key, otherwise must be None
+ - `direction` (optional): only used if key_or_list is a single
+ key, if not given ASCENDING is assumed
  """
  self.__check_okay_to_chain()
  keys = pymongo._index_list(key_or_list, direction)

test/test_collection.py

@@ -64,18 +64,13 @@ def test_create_index(self):
 
  self.assertRaises(TypeError, db.test.create_index, 5)
  self.assertRaises(TypeError, db.test.create_index, {"hello": 1})
- self.assertRaises(TypeError, db.test.create_index, "hello")
  self.assertRaises(ValueError, db.test.create_index, [])
- self.assertRaises(TypeError, db.test.create_index, [], ASCENDING)
- self.assertRaises(TypeError, db.test.create_index,
- [("hello", DESCENDING)], DESCENDING)
- self.assertRaises(TypeError, db.test.create_index, "hello", "world")
 
  db.test.drop_indexes()
  self.assertEqual(db.system.indexes.find({"ns": u"pymongo_test.test"})
  .count(), 1)
 
- db.test.create_index("hello", ASCENDING)
+ db.test.create_index("hello")
  db.test.create_index([("hello", DESCENDING), ("world", ASCENDING)])
 
  count = 0
@@ -86,7 +81,7 @@ def test_create_index(self):
  db.test.drop_indexes()
  self.assertEqual(db.system.indexes.find({"ns": u"pymongo_test.test"})
  .count(), 1)
- db.test.create_index("hello", ASCENDING)
+ db.test.create_index("hello")
  self.assert_(SON([(u"name", u"hello_1"),
  (u"unique", False),
  (u"ns", u"pymongo_test.test"),
@@ -112,54 +107,52 @@ def test_ensure_index(self):
  self.assertRaises(TypeError, db.test.ensure_index, {"hello": 1})
 
  db.test.drop_indexes()
- self.assertEqual("hello_1", db.test.create_index("hello", ASCENDING))
- self.assertEqual("hello_1", db.test.create_index("hello", ASCENDING))
+ self.assertEqual("hello_1", db.test.create_index("hello"))
+ self.assertEqual("hello_1", db.test.create_index("hello"))
 
  self.assertEqual("goodbye_1",
- db.test.ensure_index("goodbye", ASCENDING))
- self.assertEqual(None, db.test.ensure_index("goodbye", ASCENDING))
+ db.test.ensure_index("goodbye"))
+ self.assertEqual(None, db.test.ensure_index("goodbye"))
 
  db.test.drop_indexes()
  self.assertEqual("goodbye_1",
- db.test.ensure_index("goodbye", ASCENDING))
- self.assertEqual(None, db.test.ensure_index("goodbye", ASCENDING))
+ db.test.ensure_index("goodbye"))
+ self.assertEqual(None, db.test.ensure_index("goodbye"))
 
  db.test.drop_index("goodbye_1")
  self.assertEqual("goodbye_1",
- db.test.ensure_index("goodbye", ASCENDING))
- self.assertEqual(None, db.test.ensure_index("goodbye", ASCENDING))
+ db.test.ensure_index("goodbye"))
+ self.assertEqual(None, db.test.ensure_index("goodbye"))
 
  db.drop_collection("test")
  self.assertEqual("goodbye_1",
- db.test.ensure_index("goodbye", ASCENDING))
- self.assertEqual(None, db.test.ensure_index("goodbye", ASCENDING))
+ db.test.ensure_index("goodbye"))
+ self.assertEqual(None, db.test.ensure_index("goodbye"))
 
  db_name = self.db.name()
  self.connection.drop_database(self.db.name())
  self.assertEqual("goodbye_1",
- db.test.ensure_index("goodbye", ASCENDING))
- self.assertEqual(None, db.test.ensure_index("goodbye", ASCENDING))
+ db.test.ensure_index("goodbye"))
+ self.assertEqual(None, db.test.ensure_index("goodbye"))
 
  db.test.drop_index("goodbye_1")
  self.assertEqual("goodbye_1",
- db.test.create_index("goodbye", ASCENDING))
- self.assertEqual(None, db.test.ensure_index("goodbye", ASCENDING))
+ db.test.create_index("goodbye"))
+ self.assertEqual(None, db.test.ensure_index("goodbye"))
 
  db.test.drop_index("goodbye_1")
  self.assertEqual("goodbye_1",
- db.test.ensure_index("goodbye", ASCENDING,
- ttl=1))
+ db.test.ensure_index("goodbye", ttl=1))
  time.sleep(1.1)
  self.assertEqual("goodbye_1",
- db.test.ensure_index("goodbye", ASCENDING))
+ db.test.ensure_index("goodbye"))
 
  db.test.drop_index("goodbye_1")
  self.assertEqual("goodbye_1",
- db.test.create_index("goodbye", ASCENDING,
- ttl=1))
+ db.test.create_index("goodbye", ttl=1))
  time.sleep(1.1)
  self.assertEqual("goodbye_1",
- db.test.ensure_index("goodbye", ASCENDING))
+ db.test.ensure_index("goodbye"))
 
  def test_index_on_binary(self):
  db = self.db
@@ -171,19 +164,19 @@ def test_index_on_binary(self):
  self.assertEqual(db.test.find({"bin": Binary("abc")})
  .explain()["nscanned"], 3)
 
- db.test.create_index("bin", ASCENDING)
+ db.test.create_index("bin")
  self.assertEqual(db.test.find({"bin": Binary("abc")})
  .explain()["nscanned"], 1)
 
  def test_drop_index(self):
  db = self.db
  db.test.drop_indexes()
- db.test.create_index("hello", ASCENDING)
- name = db.test.create_index("goodbye", DESCENDING)
+ db.test.create_index("hello")
+ name = db.test.create_index("goodbye")
 
  self.assertEqual(db.system.indexes.find({"ns": u"pymongo_test.test"})
  .count(), 3)
- self.assertEqual(name, "goodbye_-1")
+ self.assertEqual(name, "goodbye_1")
  db.test.drop_index(name)
  self.assertEqual(db.system.indexes.find({"ns": u"pymongo_test.test"})
  .count(), 2)
@@ -195,13 +188,13 @@ def test_drop_index(self):
  .find({"ns": u"pymongo_test.test"})))
 
  db.test.drop_indexes()
- db.test.create_index("hello", ASCENDING)
- name = db.test.create_index("goodbye", DESCENDING)
+ db.test.create_index("hello")
+ name = db.test.create_index("goodbye")
 
  self.assertEqual(db.system.indexes.find({"ns": u"pymongo_test.test"})
  .count(), 3)
- self.assertEqual(name, "goodbye_-1")
- db.test.drop_index([("goodbye", DESCENDING)])
+ self.assertEqual(name, "goodbye_1")
+ db.test.drop_index([("goodbye", ASCENDING)])
  self.assertEqual(db.system.indexes.find({"ns": u"pymongo_test.test"})
  .count(), 2)
  self.assert_(SON([(u"name", u"hello_1"),
@@ -217,7 +210,7 @@ def test_index_info(self):
  self.assertEqual(len(db.test.index_information()), 1)
  self.assert_("_id_" in db.test.index_information())
 
- db.test.create_index("hello", ASCENDING)
+ db.test.create_index("hello")
  self.assertEqual(len(db.test.index_information()), 2)
  self.assertEqual(db.test.index_information()["hello_1"],
  [("hello", ASCENDING)])
@@ -421,15 +414,15 @@ def test_unique_index(self):
  db = self.db
 
  db.drop_collection("test")
- db.test.create_index("hello", ASCENDING)
+ db.test.create_index("hello")
 
  db.test.save({"hello": "world"})
  db.test.save({"hello": "mike"})
  db.test.save({"hello": "world"})
  self.failIf(db.error())
 
  db.drop_collection("test")
- db.test.create_index("hello", ASCENDING, unique=True)
+ db.test.create_index("hello", unique=True)
 
  db.test.save({"hello": "world"})
  db.test.save({"hello": "mike"})
@@ -446,7 +439,7 @@ def test_index_on_subfield(self):
  self.failIf(db.error())
 
  db.drop_collection("test")
- db.test.create_index("hello.a", ASCENDING, unique=True)
+ db.test.create_index("hello.a", unique=True)
 
  db.test.insert({"hello": {"a": 4, "b": 5}})
  db.test.insert({"hello": {"a": 7, "b": 2}})
@@ -490,7 +483,7 @@ def test_upsert(self):
  def test_safe_update(self):
  db = self.db
  db.drop_collection("test")
- db.test.create_index("x", ASCENDING)
+ db.test.create_index("x")
 
  a = {"x": 5}
  db.test.insert(a)
@@ -504,7 +497,7 @@ def test_safe_update(self):
  def test_safe_save(self):
  db = self.db
  db.drop_collection("test")
- db.test.create_index("hello", ASCENDING, unique=True)
+ db.test.create_index("hello", unique=True)
 
  db.test.save({"hello": "world"})
  db.test.save({"hello": "world"})

test/test_cursor.py

@@ -60,7 +60,7 @@ def test_hint(self):
  db.test.find({"num": 17, "foo": 17})
  .hint([("foo", ASCENDING)]).explain)
 
- index = db.test.create_index("num", ASCENDING)
+ index = db.test.create_index("num")
 
  spec = [("num", ASCENDING)]
  self.assertEqual(db.test.find({}).explain()["cursor"], "BasicCursor")
@@ -192,7 +192,6 @@ def test_sort(self):
  db = self.db
 
  self.assertRaises(TypeError, db.test.find().sort, 5)
- self.assertRaises(TypeError, db.test.find().sort, "hello")
  self.assertRaises(ValueError, db.test.find().sort, [])
  self.assertRaises(TypeError, db.test.find().sort, [], ASCENDING)
  self.assertRaises(TypeError, db.test.find().sort,
@@ -209,6 +208,8 @@ def test_sort(self):
 
  asc = [i["x"] for i in db.test.find().sort("x", ASCENDING)]
  self.assertEqual(asc, range(10))
+ asc = [i["x"] for i in db.test.find().sort("x")]
+ self.assertEqual(asc, range(10))
  asc = [i["x"] for i in db.test.find().sort([("x", ASCENDING)])]
  self.assertEqual(asc, range(10))