more readme tweaks [ci skip]

.gitignore

@@ -17,4 +17,3 @@ tests/test_bugfix.py
 htmlcov/
 venv
 venv3
-scratchpad

docs/guide/connecting.rst

@@ -42,18 +42,13 @@ the :attr:`host` to
     will establish connection to ``production`` database using
     ``admin`` username and ``qwerty`` password.
 
-Replica Sets
-============
+ReplicaSets
+===========
 
-MongoEngine supports connecting to replica sets::
-
-    from mongoengine import connect
-
-    # Regular connect
-    connect('dbname', replicaset='rs-name')
-
-    # MongoDB URI-style connect
-    connect(host='mongodb://localhost/dbname?replicaSet=rs-name')
+MongoEngine supports
+:class:`~pymongo.mongo_replica_set_client.MongoReplicaSetClient`. To use them,
+please use an URI style connection and provide the ``replicaSet`` name
+in the connection kwargs.
 
 Read preferences are supported through the connection or via individual
 queries by passing the read_preference ::
@@ -64,74 +59,76 @@ queries by passing the read_preference ::
 Multiple Databases
 ==================
 
-To use multiple databases you can use :func:`~mongoengine.connect` and provide
-an `alias` name for the connection - if no `alias` is provided then "default"
-is used.
+Multiple database support was added in MongoEngine 0.6. To use multiple
+databases you can use :func:`~mongoengine.connect` and provide an `alias` name
+for the connection - if no `alias` is provided then "default" is used.
 
 In the background this uses :func:`~mongoengine.register_connection` to
 store the data and you can register all aliases up front if required.
 
 Individual documents can also support multiple databases by providing a
-`db_alias` in their meta data. This allows :class:`~pymongo.dbref.DBRef`
-objects to point across databases and collections. Below is an example schema,
-using 3 different databases to store data::
+`db_alias` in their meta data.  This allows :class:`~pymongo.dbref.DBRef` objects
+to point across databases and collections.  Below is an example schema, using
+3 different databases to store data::
 
         class User(Document):
             name = StringField()
 
-            meta = {'db_alias': 'user-db'}
+            meta = {"db_alias": "user-db"}
 
         class Book(Document):
             name = StringField()
 
-            meta = {'db_alias': 'book-db'}
+            meta = {"db_alias": "book-db"}
 
         class AuthorBooks(Document):
             author = ReferenceField(User)
             book = ReferenceField(Book)
 
-            meta = {'db_alias': 'users-books-db'}
+            meta = {"db_alias": "users-books-db"}
 
 
 Context Managers
 ================
-Sometimes you may want to switch the database or collection to query against.
+Sometimes you may want to switch the database or collection to query against
+for a class.
 For example, archiving older data into a separate database for performance
 reasons or writing functions that dynamically choose collections to write
-a document to.
+document to.
 
 Switch Database
 ---------------
 The :class:`~mongoengine.context_managers.switch_db` context manager allows
 you to change the database alias for a given class allowing quick and easy
-access to the same User document across databases::
+access the same User document across databases::
 
     from mongoengine.context_managers import switch_db
 
     class User(Document):
         name = StringField()
 
-        meta = {'db_alias': 'user-db'}
+        meta = {"db_alias": "user-db"}
 
     with switch_db(User, 'archive-user-db') as User:
-        User(name='Ross').save()  # Saves the 'archive-user-db'
+        User(name="Ross").save()  # Saves the 'archive-user-db'
 
 
 Switch Collection
 -----------------
 The :class:`~mongoengine.context_managers.switch_collection` context manager
 allows you to change the collection for a given class allowing quick and easy
-access to the same Group document across collection::
+access the same Group document across collection::
 
         from mongoengine.context_managers import switch_collection
 
         class Group(Document):
             name = StringField()
 
-        Group(name='test').save()  # Saves in the default db
+        Group(name="test").save()  # Saves in the default db
 
         with switch_collection(Group, 'group2000') as Group:
-            Group(name='hello Group 2000 collection!').save()  # Saves in group2000 collection
+            Group(name="hello Group 2000 collection!").save()  # Saves in group2000 collection
+
 
 
 .. note:: Make sure any aliases have been registered with

docs/guide/installing.rst

@@ -2,13 +2,13 @@
 Installing MongoEngine
 ======================
 
-To use MongoEngine, you will need to download `MongoDB <http://mongodb.com/>`_
+To use MongoEngine, you will need to download `MongoDB <http://mongodb.org/>`_
 and ensure it is running in an accessible location. You will also need
 `PyMongo <http://api.mongodb.org/python>`_ to use MongoEngine, but if you
 install MongoEngine using setuptools, then the dependencies will be handled for
 you.
 
-MongoEngine is available on PyPI, so you can use :program:`pip`:
+MongoEngine is available on PyPI, so to use it you can use :program:`pip`:
 
 .. code-block:: console
 

docs/tutorial.rst

@@ -3,10 +3,11 @@ Tutorial
 ========
 
 This tutorial introduces **MongoEngine** by means of example --- we will walk
-through how to create a simple **Tumblelog** application. A tumblelog is a
-blog that supports mixed media content, including text, images, links, video,
-audio, etc. For simplicity's sake, we'll stick to text, image, and link
-entries. As the purpose of this tutorial is to introduce MongoEngine, we'll
+through how to create a simple **Tumblelog** application. A Tumblelog is a type
+of blog where posts are not constrained to being conventional text-based posts.
+As well as text-based entries, users may post images, links, videos, etc. For
+simplicity's sake, we'll stick to text, image and link entries in our
+application. As the purpose of this tutorial is to introduce MongoEngine, we'll
 focus on the data-modelling side of the application, leaving out a user
 interface.
 
@@ -15,14 +16,14 @@ Getting started
 
 Before we start, make sure that a copy of MongoDB is running in an accessible
 location --- running it locally will be easier, but if that is not an option
-then it may be run on a remote server. If you haven't installed MongoEngine,
+then it may be run on a remote server. If you haven't installed mongoengine,
 simply use pip to install it like so::
 
     $ pip install mongoengine
 
 Before we can start using MongoEngine, we need to tell it how to connect to our
 instance of :program:`mongod`. For this we use the :func:`~mongoengine.connect`
-function. If running locally, the only argument we need to provide is the name
+function. If running locally the only argument we need to provide is the name
 of the MongoDB database to use::
 
     from mongoengine import *
@@ -38,18 +39,18 @@ Defining our documents
 MongoDB is *schemaless*, which means that no schema is enforced by the database
 --- we may add and remove fields however we want and MongoDB won't complain.
 This makes life a lot easier in many regards, especially when there is a change
-to the data model. However, defining schemas for our documents can help to iron
-out bugs involving incorrect types or missing fields, and also allow us to
+to the data model. However, defining schemata for our documents can help to
+iron out bugs involving incorrect types or missing fields, and also allow us to
 define utility methods on our documents in the same way that traditional
 :abbr:`ORMs (Object-Relational Mappers)` do.
 
 In our Tumblelog application we need to store several different types of
-information. We will need to have a collection of **users**, so that we may
+information.  We will need to have a collection of **users**, so that we may
 link posts to an individual. We also need to store our different types of
 **posts** (eg: text, image and link) in the database. To aid navigation of our
 Tumblelog, posts may have **tags** associated with them, so that the list of
 posts shown to the user may be limited to posts that have been assigned a
-specific tag. Finally, it would be nice if **comments** could be added to
+specific tag.  Finally, it would be nice if **comments** could be added to
 posts. We'll start with **users**, as the other document models are slightly
 more involved.
 
@@ -77,7 +78,7 @@ Now we'll think about how to store the rest of the information. If we were
 using a relational database, we would most likely have a table of **posts**, a
 table of **comments** and a table of **tags**.  To associate the comments with
 individual posts, we would put a column in the comments table that contained a
-foreign key to the posts table. We'd also need a link table to provide the
+foreign key to the posts table.  We'd also need a link table to provide the
 many-to-many relationship between posts and tags. Then we'd need to address the
 problem of storing the specialised post-types (text, image and link). There are
 several ways we can achieve this, but each of them have their problems --- none
@@ -95,7 +96,7 @@ using* the new fields we need to support video posts. This fits with the
 Object-Oriented principle of *inheritance* nicely. We can think of
 :class:`Post` as a base class, and :class:`TextPost`, :class:`ImagePost` and
 :class:`LinkPost` as subclasses of :class:`Post`. In fact, MongoEngine supports
-this kind of modeling out of the box --- all you need do is turn on inheritance
+this kind of modelling out of the box --- all you need do is turn on inheritance
 by setting :attr:`allow_inheritance` to True in the :attr:`meta`::
 
     class Post(Document):
@@ -127,8 +128,8 @@ link table, we can just store a list of tags in each post. So, for both
 efficiency and simplicity's sake, we'll store the tags as strings directly
 within the post, rather than storing references to tags in a separate
 collection. Especially as tags are generally very short (often even shorter
-than a document's id), this denormalization won't impact the size of the
-database very strongly. Let's take a look at the code of our modified
+than a document's id), this denormalisation won't impact very strongly on the
+size of our database. So let's take a look that the code our modified
 :class:`Post` class::
 
     class Post(Document):
@@ -140,7 +141,7 @@ The :class:`~mongoengine.fields.ListField` object that is used to define a Post'
 takes a field object as its first argument --- this means that you can have
 lists of any type of field (including lists).
 
-.. note:: We don't need to modify the specialized post types as they all
+.. note:: We don't need to modify the specialised post types as they all
     inherit from :class:`Post`.
 
 Comments
@@ -148,7 +149,7 @@ Comments
 
 A comment is typically associated with *one* post. In a relational database, to
 display a post with its comments, we would have to retrieve the post from the
-database and then query the database again for the comments associated with the
+database, then query the database again for the comments associated with the
 post. This works, but there is no real reason to be storing the comments
 separately from their associated posts, other than to work around the
 relational model. Using MongoDB we can store the comments as a list of
@@ -218,8 +219,8 @@ Now that we've got our user in the database, let's add a couple of posts::
     post2.tags = ['mongoengine']
     post2.save()
 
-.. note:: If you change a field on an object that has already been saved and
-    then call :meth:`save` again, the document will be updated.
+.. note:: If you change a field on a object that has already been saved, then
+    call :meth:`save` again, the document will be updated.
 
 Accessing our data
 ==================
@@ -231,17 +232,17 @@ used to access the documents in the database collection associated with that
 class. So let's see how we can get our posts' titles::
 
     for post in Post.objects:
-        print(post.title)
+        print post.title
 
 Retrieving type-specific information
 ------------------------------------
 
-This will print the titles of our posts, one on each line. But what if we want
+This will print the titles of our posts, one on each line. But What if we want
 to access the type-specific data (link_url, content, etc.)? One way is simply
 to use the :attr:`objects` attribute of a subclass of :class:`Post`::
 
     for post in TextPost.objects:
-        print(post.content)
+        print post.content
 
 Using TextPost's :attr:`objects` attribute only returns documents that were
 created using :class:`TextPost`. Actually, there is a more general rule here:
@@ -258,14 +259,16 @@ instances of :class:`Post` --- they were instances of the subclass of
 practice::
 
     for post in Post.objects:
-        print(post.title)
-        print('=' * len(post.title))
+        print post.title
+        print '=' * len(post.title)
 
         if isinstance(post, TextPost):
-            print(post.content)
+            print post.content
 
         if isinstance(post, LinkPost):
-            print('Link: {}'.format(post.link_url))
+            print 'Link:', post.link_url
+
+        print
 
 This would print the title of each post, followed by the content if it was a
 text post, and "Link: <url>" if it was a link post.
@@ -280,7 +283,7 @@ your query.  Let's adjust our query so that only posts with the tag "mongodb"
 are returned::
 
     for post in Post.objects(tags='mongodb'):
-        print(post.title)
+        print post.title
 
 There are also methods available on :class:`~mongoengine.queryset.QuerySet`
 objects that allow different results to be returned, for example, calling
@@ -289,11 +292,11 @@ the first matched by the query you provide. Aggregation functions may also be
 used on :class:`~mongoengine.queryset.QuerySet` objects::
 
     num_posts = Post.objects(tags='mongodb').count()
-    print('Found {} posts with tag "mongodb"'.format(num_posts))
+    print 'Found %d posts with tag "mongodb"' % num_posts
 
-Learning more about MongoEngine
+Learning more about mongoengine
 -------------------------------
 
-If you got this far you've made a great start, so well done! The next step on
-your MongoEngine journey is the `full user guide <guide/index.html>`_, where
-you can learn in-depth about how to use MongoEngine and MongoDB.
+If you got this far you've made a great start, so well done!  The next step on
+your mongoengine journey is the `full user guide <guide/index.html>`_, where you
+can learn indepth about how to use mongoengine and mongodb.

mongoengine/queryset/base.py

@@ -286,7 +286,7 @@ class BaseQuerySet(object):
 
         .. versionadded:: 0.4
         """
-        return self._document(**kwargs).save(force_insert=True)
+        return self._document(**kwargs).save()
 
     def first(self):
         """Retrieve the first object matching the query."""

tests/document/indexes.py

@@ -412,6 +412,7 @@ class IndexesTest(unittest.TestCase):
         User.ensure_indexes()
         info = User.objects._collection.index_information()
         self.assertEqual(sorted(info.keys()), ['_cls_1_user_guid_1', '_id_'])
+        User.drop_collection()
 
     def test_embedded_document_index(self):
         """Tests settings an index on an embedded document
@@ -433,6 +434,7 @@ class IndexesTest(unittest.TestCase):
 
         info = BlogPost.objects._collection.index_information()
         self.assertEqual(sorted(info.keys()), ['_id_', 'date.yr_-1'])
+        BlogPost.drop_collection()
 
     def test_list_embedded_document_index(self):
         """Ensure list embedded documents can be indexed
@@ -459,6 +461,7 @@ class IndexesTest(unittest.TestCase):
         post1 = BlogPost(title="Embedded Indexes tests in place",
                          tags=[Tag(name="about"), Tag(name="time")])
         post1.save()
+        BlogPost.drop_collection()
 
     def test_recursive_embedded_objects_dont_break_indexes(self):
 
@@ -619,6 +622,8 @@ class IndexesTest(unittest.TestCase):
         post3 = BlogPost(title='test3', date=Date(year=2010), slug='test')
         self.assertRaises(OperationError, post3.save)
 
+        BlogPost.drop_collection()
+
     def test_unique_embedded_document(self):
         """Ensure that uniqueness constraints are applied to fields on embedded documents.
         """
@@ -646,6 +651,8 @@ class IndexesTest(unittest.TestCase):
                          sub=SubDocument(year=2010, slug='test'))
         self.assertRaises(NotUniqueError, post3.save)
 
+        BlogPost.drop_collection()
+
     def test_unique_embedded_document_in_list(self):
         """
         Ensure that the uniqueness constraints are applied to fields in
@@ -676,6 +683,8 @@ class IndexesTest(unittest.TestCase):
 
         self.assertRaises(NotUniqueError, post2.save)
 
+        BlogPost.drop_collection()
+
     def test_unique_with_embedded_document_and_embedded_unique(self):
         """Ensure that uniqueness constraints are applied to fields on
         embedded documents.  And work with unique_with as well.
@@ -709,6 +718,8 @@ class IndexesTest(unittest.TestCase):
                          sub=SubDocument(year=2009, slug='test-1'))
         self.assertRaises(NotUniqueError, post3.save)
 
+        BlogPost.drop_collection()
+
     def test_ttl_indexes(self):
 
         class Log(Document):
@@ -748,11 +759,13 @@ class IndexesTest(unittest.TestCase):
             raise AssertionError("We saved a dupe!")
         except NotUniqueError:
             pass
+        Customer.drop_collection()
 
     def test_unique_and_primary(self):
         """If you set a field as primary, then unexpected behaviour can occur.
         You won't create a duplicate but you will update an existing document.
         """
+
         class User(Document):
             name = StringField(primary_key=True, unique=True)
             password = StringField()
@@ -768,23 +781,8 @@ class IndexesTest(unittest.TestCase):
         self.assertEqual(User.objects.count(), 1)
         self.assertEqual(User.objects.get().password, 'secret2')
 
-    def test_unique_and_primary_create(self):
-        """Create a new record with a duplicate primary key
-        throws an exception
-        """
-        class User(Document):
-            name = StringField(primary_key=True)
-            password = StringField()
-
         User.drop_collection()
 
-        User.objects.create(name='huangz', password='secret')
-        with self.assertRaises(NotUniqueError):
-            User.objects.create(name='huangz', password='secret2')
-
-        self.assertEqual(User.objects.count(), 1)
-        self.assertEqual(User.objects.get().password, 'secret')
-
     def test_index_with_pk(self):
         """Ensure you can use `pk` as part of a query"""
 

tests/test_connection.py

@@ -198,6 +198,19 @@ class ConnectionTest(unittest.TestCase):
         self.assertTrue(isinstance(db, pymongo.database.Database))
         self.assertEqual(db.name, 'test')
 
+    def test_connect_uri_with_replicaset(self):
+        """Ensure connect() works when specifying a replicaSet."""
+        if IS_PYMONGO_3:
+            c = connect(host='mongodb://localhost/test?replicaSet=local-rs')
+            db = get_db()
+            self.assertTrue(isinstance(db, pymongo.database.Database))
+            self.assertEqual(db.name, 'test')
+        else:
+            # PyMongo < v3.x raises an exception:
+            # "localhost:27017 is not a member of replica set local-rs"
+            with self.assertRaises(MongoEngineConnectionError):
+                c = connect(host='mongodb://localhost/test?replicaSet=local-rs')
+
     def test_uri_without_credentials_doesnt_override_conn_settings(self):
         """Ensure connect() uses the username & password params if the URI
         doesn't explicitly specify them.
@@ -319,38 +332,6 @@ class ConnectionTest(unittest.TestCase):
             self.assertEqual(dict(conn1.write_concern), {'w': 1, 'j': True})
             self.assertEqual(dict(conn2.write_concern), {'w': 1, 'j': True})
 
-    def test_connect_with_replicaset_via_uri(self):
-        """Ensure connect() works when specifying a replicaSet via the
-        MongoDB URI.
-        """
-        if IS_PYMONGO_3:
-            c = connect(host='mongodb://localhost/test?replicaSet=local-rs')
-            db = get_db()
-            self.assertTrue(isinstance(db, pymongo.database.Database))
-            self.assertEqual(db.name, 'test')
-        else:
-            # PyMongo < v3.x raises an exception:
-            # "localhost:27017 is not a member of replica set local-rs"
-            with self.assertRaises(MongoEngineConnectionError):
-                c = connect(host='mongodb://localhost/test?replicaSet=local-rs')
-
-    def test_connect_with_replicaset_via_kwargs(self):
-        """Ensure connect() works when specifying a replicaSet via the
-        connection kwargs
-        """
-        if IS_PYMONGO_3:
-            c = connect(replicaset='local-rs')
-            self.assertEqual(c._MongoClient__options.replica_set_name,
-                             'local-rs')
-            db = get_db()
-            self.assertTrue(isinstance(db, pymongo.database.Database))
-            self.assertEqual(db.name, 'test')
-        else:
-            # PyMongo < v3.x raises an exception:
-            # "localhost:27017 is not a member of replica set local-rs"
-            with self.assertRaises(MongoEngineConnectionError):
-                c = connect(replicaset='local-rs')
-
     def test_datetime(self):
         connect('mongoenginetest', tz_aware=True)
         d = datetime.datetime(2010, 5, 5, tzinfo=utc)