Fixed #25550 -- Deprecated direct assignment to the reverse side of a related set.

10 files changed, 48 insertions, 42 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index 39daa0c002..6b5eb95ad0 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -109,6 +109,9 @@ details on these changes.
 
 * The ``makemigrations --exit`` option will be removed.
 
+* Support for direct assignment to a reverse foreign key or many-to-many
+  relation will be removed.
+
 .. _deprecation-removed-in-1.10:
 
 1.10
diff --git a/docs/ref/contrib/auth.txt b/docs/ref/contrib/auth.txt
index 217bd432b5..6cbfd88ac6 100644
--- a/docs/ref/contrib/auth.txt
+++ b/docs/ref/contrib/auth.txt
@@ -337,7 +337,7 @@ Fields
 
         Many-to-many field to :class:`~django.contrib.auth.models.Permission`::
 
-            group.permissions = [permission_list]
+            group.permissions.set([permission_list])
             group.permissions.add(permission, permission, ...)
             group.permissions.remove(permission, permission, ...)
             group.permissions.clear()
diff --git a/docs/ref/models/relations.txt b/docs/ref/models/relations.txt
index e89355679a..8671d83d51 100644
--- a/docs/ref/models/relations.txt
+++ b/docs/ref/models/relations.txt
@@ -179,8 +179,6 @@ Related objects reference
        <intermediary-manytomany>` for a many-to-many relationship, some of the
        related manager's methods are disabled.
 
-.. _direct-assignment:
-
 Direct Assignment
 -----------------
 
@@ -200,3 +198,12 @@ added to the existing related object set.
     In earlier versions, direct assignment used to perform ``clear()`` followed
     by ``add()``. It now performs a ``set()`` with the keyword argument
     ``clear=False``.
+
+.. deprecated:: 1.10
+
+    Direct assignment is deprecated in favor of the
+    :meth:`~django.db.models.fields.related.RelatedManager.set` method::
+
+        >>> e.related_set.set([obj1, obj2, obj3])
+
+    This prevents confusion about an assignment resulting in an implicit save.
diff --git a/docs/releases/1.10.txt b/docs/releases/1.10.txt
index 16e7d2ea28..602e34a6f9 100644
--- a/docs/releases/1.10.txt
+++ b/docs/releases/1.10.txt
@@ -269,6 +269,21 @@ Miscellaneous
 Features deprecated in 1.10
 ===========================
 
+Direct assignment to a reverse foreign key or many-to-many relation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Instead of assigning related objects using direct assignment::
+
+    >>> new_list = [obj1, obj2, obj3]
+    >>> e.related_set = new_list
+
+Use the :meth:`~django.db.models.fields.related.RelatedManager.set` method
+added in Django 1.9::
+
+        >>> e.related_set.set([obj1, obj2, obj3])
+
+This prevents confusion about an assignment resulting in an implicit save.
+
 Miscellaneous
 ~~~~~~~~~~~~~
 
diff --git a/docs/releases/1.8.txt b/docs/releases/1.8.txt
index b73106a670..eb2260aa91 100644
--- a/docs/releases/1.8.txt
+++ b/docs/releases/1.8.txt
@@ -673,13 +673,12 @@ Related object operations are run in a transaction
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Some operations on related objects such as
-:meth:`~django.db.models.fields.related.RelatedManager.add()` or
-:ref:`direct assignment<direct-assignment>` ran multiple data modifying
-queries without wrapping them in transactions. To reduce the risk of data
-corruption, all data modifying methods that affect multiple related objects
-(i.e. ``add()``, ``remove()``, ``clear()``, and :ref:`direct assignment
-<direct-assignment>`) now perform their data modifying queries from within a
-transaction, provided your database supports transactions.
+:meth:`~django.db.models.fields.related.RelatedManager.add()` or direct
+assignment ran multiple data modifying queries without wrapping them in
+transactions. To reduce the risk of data corruption, all data modifying methods
+that affect multiple related objects (i.e. ``add()``, ``remove()``,
+``clear()``, and direct assignment) now perform their data modifying queries
+from within a transaction, provided your database supports transactions.
 
 This has one backwards incompatible side effect, signal handlers triggered from
 these methods are now executed within the method's transaction and any
diff --git a/docs/releases/1.9.txt b/docs/releases/1.9.txt
index 22b55dd9bc..c526825174 100644
--- a/docs/releases/1.9.txt
+++ b/docs/releases/1.9.txt
@@ -747,11 +747,10 @@ setuptools is not installed.
 Related set direct assignment
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-:ref:`Direct assignment <direct-assignment>` of related objects in the ORM used
-to perform a ``clear()`` followed by a call to ``add()``. This caused
-needlessly large data changes and prevented using the
-:data:`~django.db.models.signals.m2m_changed` signal to track individual
-changes in many-to-many relations.
+Direct assignment of related objects in the ORM used to perform a ``clear()``
+followed by a call to ``add()``. This caused needlessly large data changes and
+prevented using the :data:`~django.db.models.signals.m2m_changed` signal to
+track individual changes in many-to-many relations.
 
 Direct assignment now relies on the the new
 :meth:`~django.db.models.fields.related.RelatedManager.set` method on related
diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt
index 15098f6517..5cef47589d 100644
--- a/docs/topics/auth/default.txt
+++ b/docs/topics/auth/default.txt
@@ -181,11 +181,11 @@ fields: ``groups`` and ``user_permissions``.
 objects in the same way as any other :doc:`Django model
 </topics/db/models>`::
 
-    myuser.groups = [group_list]
+    myuser.groups.set([group_list])
     myuser.groups.add(group, group, ...)
     myuser.groups.remove(group, group, ...)
     myuser.groups.clear()
-    myuser.user_permissions = [permission_list]
+    myuser.user_permissions.set([permission_list])
     myuser.user_permissions.add(permission, permission, ...)
     myuser.user_permissions.remove(permission, permission, ...)
     myuser.user_permissions.clear()
diff --git a/docs/topics/db/examples/many_to_many.txt b/docs/topics/db/examples/many_to_many.txt
index cbf8da99e2..4966ff9272 100644
--- a/docs/topics/db/examples/many_to_many.txt
+++ b/docs/topics/db/examples/many_to_many.txt
@@ -221,11 +221,11 @@ And from the other end::
     >>> a5.publications.all()
     <QuerySet []>
 
-Relation sets can be assigned. Assignment clears any existing set members::
+Relation sets can be set::
 
     >>> a4.publications.all()
     <QuerySet [<Publication: Science News>]>
-    >>> a4.publications = [p3]
+    >>> a4.publications.set([p3])
     >>> a4.publications.all()
     <QuerySet [<Publication: Science Weekly>]>
 
@@ -282,18 +282,3 @@ referenced objects should be gone::
     <QuerySet []>
     >>> p1.article_set.all()
     <QuerySet [<Article: NASA uses Python>]>
-
-An alternate to calling
-:meth:`~django.db.models.fields.related.RelatedManager.clear` is to assign the
-empty set::
-
-    >>> p1.article_set = []
-    >>> p1.article_set.all()
-    <QuerySet []>
-
-    >>> a2.publications = [p1, new_publication]
-    >>> a2.publications.all()
-    <QuerySet [<Publication: Highlights for Children>, <Publication: The Python Journal>]>
-    >>> a2.publications = []
-    >>> a2.publications.all()
-    <QuerySet []>
diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt
index 586ec66927..ab6268b485 100644
--- a/docs/topics/db/models.txt
+++ b/docs/topics/db/models.txt
@@ -510,15 +510,15 @@ the intermediate model::
     >>> beatles.members.all()
     <QuerySet [<Person: Ringo Starr>, <Person: Paul McCartney>]>
 
-Unlike normal many-to-many fields, you *can't* use ``add``, ``create``,
-or assignment (i.e., ``beatles.members = [...]``) to create relationships::
+Unlike normal many-to-many fields, you *can't* use ``add()``, ``create()``,
+or ``set()`` to create relationships::
 
     # THIS WILL NOT WORK
     >>> beatles.members.add(john)
     # NEITHER WILL THIS
     >>> beatles.members.create(name="George Harrison")
     # AND NEITHER WILL THIS
-    >>> beatles.members = [john, paul, ringo, george]
+    >>> beatles.members.set([john, paul, ringo, george])
 
 Why? You can't just create a relationship between a ``Person`` and a ``Group``
 - you need to specify all the detail for the relationship required by the
@@ -575,7 +575,6 @@ Another way to access the same information is by querying the
     >>> ringos_membership.invite_reason
     'Needed a new drummer.'
 
-
 One-to-one relationships
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/topics/db/queries.txt b/docs/topics/db/queries.txt
index 956baa7975..ba026c8c58 100644
--- a/docs/topics/db/queries.txt
+++ b/docs/topics/db/queries.txt
@@ -1223,12 +1223,11 @@ be found in the :doc:`related objects reference </ref/models/relations>`.
 ``set(objs)``
     Replace the set of related objects.
 
-To assign the members of a related set in one fell swoop, just assign to it
-from any iterable object. The iterable can contain object instances, or just
-a list of primary key values. For example::
+To assign the members of a related set, use the ``set()`` method with an
+iterable of object instances or a list of primary key values. For example::
 
     b = Blog.objects.get(id=1)
-    b.entry_set = [e1, e2]
+    b.entry_set.set([e1, e2]
 
 In this example, ``e1`` and ``e2`` can be full Entry instances, or integer
 primary key values.