Improved queryset handling and docs for (Single|Multiple)ObjectMixin.

2 files changed, 16 insertions, 0 deletions

diff --git a/docs/ref/class-based-views/mixins-multiple-object.txt b/docs/ref/class-based-views/mixins-multiple-object.txt
index b28bd11a71..67ca5429fa 100644
--- a/docs/ref/class-based-views/mixins-multiple-object.txt
+++ b/docs/ref/class-based-views/mixins-multiple-object.txt
@@ -63,6 +63,14 @@ MultipleObjectMixin
         A ``QuerySet`` that represents the objects. If provided, the value of
         ``queryset`` supersedes the value provided for :attr:`model`.
 
+        .. warning::
+
+            ``queryset`` is a class attribute with a *mutable* value so care
+            must be taken when using it directly. Before using it, either call
+            its :meth:`~django.db.models.query.QuerySet.all` method or
+            retrieve it with :meth:`get_queryset` which takes care of the
+            cloning behind the scenes.
+
     .. attribute:: paginate_by
 
         An integer specifying how many objects should be displayed per page. If
diff --git a/docs/ref/class-based-views/mixins-single-object.txt b/docs/ref/class-based-views/mixins-single-object.txt
index bbe930d79e..1fce24acc5 100644
--- a/docs/ref/class-based-views/mixins-single-object.txt
+++ b/docs/ref/class-based-views/mixins-single-object.txt
@@ -23,6 +23,14 @@ SingleObjectMixin
         A ``QuerySet`` that represents the objects. If provided, the value of
         ``queryset`` supersedes the value provided for :attr:`model`.
 
+        .. warning::
+
+            ``queryset`` is a class attribute with a *mutable* value so care
+            must be taken when using it directly. Before using it, either call
+            its :meth:`~django.db.models.query.QuerySet.all` method or
+            retrieve it with :meth:`get_queryset` which takes care of the
+            cloning behind the scenes.
+
     .. attribute:: slug_field
 
         The name of the field on the model that contains the slug. By default,