Querysets now return clones and are no longer edit in place

Fixes #56

Author: rozza

docs/changelog.rst

@@ -26,6 +26,7 @@ Changes in 0.8.X
 - Fix Django timezone support (#151)
 - Simplified Q objects, removed QueryTreeTransformerVisitor (#98) (#171)
 - FileFields now copyable (#198)
+- Querysets now return clones and are no longer edit in place (#56)
 
 Changes in 0.7.9
 ================

docs/upgrade.rst

@@ -56,6 +56,28 @@ you will need to declare :attr:`allow_inheritance` in the meta data like so: ::
 
         meta = {'allow_inheritance': True}
 
+Querysets
+~~~~~~~~~
+
+Querysets now return clones and should no longer be considered editable in
+place.  This brings us in line with how Django's querysets work and removes a
+long running gotcha.  If you edit your querysets inplace you will have to
+update your code like so: ::
+
+    # Old code:
+    mammals = Animal.objects(type="mammal")
+    mammals.filter(order="Carnivora")       # Returns a cloned queryset that isn't assigned to anything - so this will break in 0.8
+    [m for m in mammals]                    # This will return all mammals in 0.8 as the 2nd filter returned a new queryset
+
+    # Update example a) assign queryset after a change:
+    mammals = Animal.objects(type="mammal")
+    carnivores = mammals.filter(order="Carnivora") # Reassign the new queryset so fitler can be applied
+    [m for m in carnivores]                        # This will return all carnivores
+
+    # Update example b) chain the queryset:
+    mammals = Animal.objects(type="mammal").filter(order="Carnivora")  # The final queryset is assgined to mammals
+    [m for m in mammals]                                               # This will return all carnivores
+
 Indexes
 -------
 

mongoengine/connection.py

@@ -28,8 +28,10 @@ def register_connection(alias, name, host='localhost', port=27017,
     :param name: the name of the specific database to use
     :param host: the host name of the :program:`mongod` instance to connect to
     :param port: the port that the :program:`mongod` instance is running on
-    :param is_slave: whether the connection can act as a slave ** Depreciated pymongo 2.0.1+
-    :param read_preference: The read preference for the collection ** Added pymongo 2.1
+    :param is_slave: whether the connection can act as a slave
+      ** Depreciated pymongo 2.0.1+
+    :param read_preference: The read preference for the collection
+       ** Added pymongo 2.1
     :param slaves: a list of aliases of slave connections; each of these must
         be a registered connection that has :attr:`is_slave` set to ``True``
     :param username: username to authenticate with