From 682ed95a89dafbb803d81d2a072228d78588523f Mon Sep 17 00:00:00 2001 From: Mike Dirolf Date: Wed, 2 Sep 2009 17:38:35 -0400 Subject: [PATCH] API CHANGE: deprecating passing direction to ensure_index, create_index for single key - just creates an ascending index since direction doesn't matter --- README.rst | 4 +-- examples/quick_tour.py | 5 ++- pymongo/__init__.py | 10 +++--- pymongo/collection.py | 40 ++++++++++++++-------- pymongo/cursor.py | 4 +-- test/test_collection.py | 75 +++++++++++++++++++---------------------- test/test_cursor.py | 5 +-- tools/driver_tests.py | 4 +-- 8 files changed, 76 insertions(+), 71 deletions(-) diff --git a/README.rst b/README.rst index 8699bbf2e..c38c4da08 100644 --- a/README.rst +++ b/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"] ... diff --git a/examples/quick_tour.py b/examples/quick_tour.py index 3fe822d99..793deece7 100644 --- a/examples/quick_tour.py +++ b/examples/quick_tour.py @@ -82,8 +82,7 @@ for d in collection.find({"i": {"$gt": 50}}): 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() diff --git a/pymongo/__init__.py b/pymongo/__init__.py index e942c8c55..1b9a8b801 100644 --- a/pymongo/__init__.py +++ b/pymongo/__init__.py @@ -48,16 +48,16 @@ except AttributeError: # before 2.5 _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 diff --git a/pymongo/collection.py b/pymongo/collection.py index 316591569..3abca35e1 100644 --- a/pymongo/collection.py +++ b/pymongo/collection.py @@ -15,6 +15,7 @@ """Collection level utilities for Mongo.""" import types +import warnings import pymongo import bson @@ -389,16 +390,15 @@ class Collection(object): 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 @@ class Collection(object): 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 @@ class Collection(object): 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,8 +456,7 @@ class Collection(object): :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` @@ -459,12 +464,18 @@ class Collection(object): 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 @@ class Collection(object): 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 diff --git a/pymongo/cursor.py b/pymongo/cursor.py index f3fe1aa07..7a323a9c4 100644 --- a/pymongo/cursor.py +++ b/pymongo/cursor.py @@ -224,8 +224,8 @@ class Cursor(object): :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) diff --git a/test/test_collection.py b/test/test_collection.py index ccf01bb6a..ab4cf25dd 100644 --- a/test/test_collection.py +++ b/test/test_collection.py @@ -64,18 +64,13 @@ class TestCollection(unittest.TestCase): 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 @@ class TestCollection(unittest.TestCase): 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 @@ class TestCollection(unittest.TestCase): 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 @@ class TestCollection(unittest.TestCase): 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 @@ class TestCollection(unittest.TestCase): .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 @@ class TestCollection(unittest.TestCase): 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,7 +414,7 @@ class TestCollection(unittest.TestCase): 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"}) @@ -429,7 +422,7 @@ class TestCollection(unittest.TestCase): 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 @@ class TestCollection(unittest.TestCase): 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 @@ class TestCollection(unittest.TestCase): 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 @@ class TestCollection(unittest.TestCase): 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"}) diff --git a/test/test_cursor.py b/test/test_cursor.py index 05c9acbda..faa7e46a5 100644 --- a/test/test_cursor.py +++ b/test/test_cursor.py @@ -60,7 +60,7 @@ class TestCursor(unittest.TestCase): 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 @@ class TestCursor(unittest.TestCase): 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 @@ class TestCursor(unittest.TestCase): 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)) diff --git a/tools/driver_tests.py b/tools/driver_tests.py index 3a78cf1b4..eb6998ffa 100755 --- a/tools/driver_tests.py +++ b/tools/driver_tests.py @@ -112,7 +112,7 @@ def indices(db, out): db.y.create_index([("a", ASCENDING), ("b", ASCENDING), ("c", ASCENDING)]) - db.y.create_index("d", ASCENDING) + db.y.create_index("d") for name in sorted(db.y.index_information().keys()): print >>out, name @@ -137,7 +137,7 @@ def stress1(db, out): x["subarray"] = "foo" + str(i) db.stress1.save(x) - db.stress1.create_index("date", ASCENDING) + db.stress1.create_index("date") def test1(db, out): for i in range(100):