- use consistent and descriptive language in all cases

where we refer to the "weak_identity_map" option, and add additional
exposition in the session documentation which refers to it.
fixes #3517

2 files changed, 26 insertions, 3 deletions

diff --git a/lib/sqlalchemy/orm/identity.py b/lib/sqlalchemy/orm/identity.py
index 46be2b719..b42703855 100644
--- a/lib/sqlalchemy/orm/identity.py
+++ b/lib/sqlalchemy/orm/identity.py
@@ -208,6 +208,18 @@ class WeakInstanceDict(IdentityMap):
 
 
 class StrongInstanceDict(IdentityMap):
+    """A 'strong-referencing' version of the identity map.
+
+    .. deprecated:: this object is present in order to fulfill
+       the ``weak_identity_map=False`` option of the Session.
+       This option is present to allow compatibility with older applications,
+       but it is recommended that strong references to objects
+       be maintained by the calling application
+       externally to the :class:`.Session` itself, to the degree
+       that is needed by the application.
+
+    """
+
     if util.py2k:
         def itervalues(self):
             return self._dict.itervalues()
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index b988a9230..6c3f392ba 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -630,15 +630,26 @@ class Session(_SessionClassMethods):
            ``False``, objects placed in the :class:`.Session` will be
            strongly referenced until explicitly removed or the
            :class:`.Session` is closed.  **Deprecated** - this option
-           is obsolete.
+           is present to allow compatibility with older applications, but
+           it is recommended that strong references to objects
+           be maintained by the calling application
+           externally to the :class:`.Session` itself,
+           to the extent that is required by the application.
 
         """
 
         if weak_identity_map:
             self._identity_cls = identity.WeakInstanceDict
         else:
-            util.warn_deprecated("weak_identity_map=False is deprecated.  "
-                                 "This feature is not needed.")
+            util.warn_deprecated(
+                "weak_identity_map=False is deprecated.  "
+                "It is present to allow compatibility with older "
+                "applications, but "
+                "it is recommended that strong references to "
+                "objects be maintained by the calling application "
+                "externally to the :class:`.Session` itself, "
+                "to the extent that is required by the application.")
+
             self._identity_cls = identity.StrongInstanceDict
         self.identity_map = self._identity_cls()