From 1ca9e95d4e9ec5922ce6aee6c143006b6c551e48 Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee <russell@keith-magee.com>
Date: Sun, 16 Jan 2011 06:44:23 +0000
Subject: [PATCH] =?UTF-8?q?Fixed=20#15062=20--=20Documented=20the=20fact?=
=?UTF-8?q?=20that=20managers=20must=20be=20able=20to=20be=20shallow=20cop?=
=?UTF-8?q?ied.=20Thanks=20to=20Ian=20Clelland=20for=20the=20report,=20and?=
=?UTF-8?q?=20=C5=81ukasz=20Rekucki=20for=20the=20help=20diagnosing=20the?=
=?UTF-8?q?=20problem.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
git-svn-id: http://code.djangoproject.com/svn/django/trunk@15220 bcc190cf-cafb-0310-a4f2-bffc1f526a37
---
docs/topics/db/managers.txt | 22 ++++++++++++++++++++++
1 file changed, 22 insertions(+)
diff --git a/docs/topics/db/managers.txt b/docs/topics/db/managers.txt
index 9c5ed620ab..d9a144bd62 100644
--- a/docs/topics/db/managers.txt
+++ b/docs/topics/db/managers.txt
@@ -274,6 +274,28 @@ it into the inheritance hierarchy *after* the defaults::
# Default manager is CustomManager, but OtherManager is
# also available via the "extra_manager" attribute.
+Implementation concerns
+-----------------------
+
+Whatever features you add to your custom ``Manager``, it must be
+possible to make a shallow copy of a ``Manager`` instance; i.e., the
+following code must work::
+
+ >>> import copy
+ >>> manager = MyManager()
+ >>> my_copy = copy.copy(manager)
+
+Django makes shallow copies of manager objects during certain queries;
+if your Manager cannot be copied, those queries will fail.
+
+This won't be an issue for most custom managers. If you are just
+adding simple methods to your ``Manager``, it is unlikely that you
+will inadvertently make instances of your ``Manager`` uncopyable.
+However, if you're overriding ``__getattr__`` or some other private
+method of your ``Manager`` object that controls object state, you
+should ensure that you don't affect the ability of your ``Manager`` to
+be copied.
+
.. _manager-types:
Controlling automatic Manager types