- 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

(cherry picked from commit 956907a4b15f6dcc492582a7ad03706ff62d96fb)

diff --git a/doc/build/orm/session_state_management.rst b/doc/build/orm/session_state_management.rst
index 1ca7ca2e431b4633d78f31474f37403541a379d0..1a8bb3dee0025bf8b904587e6ab685d8dd8e33b0 100644 (file)
--- a/doc/build/orm/session_state_management.rst
+++ b/doc/build/orm/session_state_management.rst
@@ -55,7 +55,6 @@ the :func:`.inspect` system::
 
     :attr:`.InstanceState.detached`
 
-
 Session Attributes
 ------------------
 
@@ -92,17 +91,38 @@ all objects which have had changes since they were last loaded or saved (i.e.
 (Documentation: :attr:`.Session.new`, :attr:`.Session.dirty`,
 :attr:`.Session.deleted`, :attr:`.Session.identity_map`).
 
-Note that objects within the session are by default *weakly referenced*. This
+Note that objects within the session are *weakly referenced*. This
 means that when they are dereferenced in the outside application, they fall
 out of scope from within the :class:`~sqlalchemy.orm.session.Session` as well
 and are subject to garbage collection by the Python interpreter. The
 exceptions to this include objects which are pending, objects which are marked
 as deleted, or persistent objects which have pending changes on them. After a
 full flush, these collections are all empty, and all objects are again weakly
-referenced. To disable the weak referencing behavior and force all objects
-within the session to remain until explicitly expunged, configure
-:class:`.sessionmaker` with the ``weak_identity_map=False``
-setting.
+referenced.
+
+.. note::
+
+  To disable the weak referencing behavior and force all objects
+  within the session to remain until explicitly expunged, configure
+  :class:`.sessionmaker` with the ``weak_identity_map=False``
+  setting.   However note that this option is **deprecated**;
+  it is present only to allow compatibility with older
+  applications, typically those that were made back before SQLAlchemy
+  had the ability to effectively weak-reference all objects.
+  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.
+  This eliminates the
+  :class:`.Session` as a possible source of unbounded memory growth in the case
+  where large numbers of objects are being loaded and/or persisted.
+
+  Simple examples of externally managed strong-referencing behavior
+  include loading objects into a local dictionary keyed to their primary key,
+  or into lists or sets for the span of time that they need to remain referenced.
+  These collections can be associated with a :class:`.Session`, if desired,
+  by placing them into the :attr:`.Session.info` dictionary.  Events such
+  as the :meth:`.SessionEvents.after_attach` event may also be of use for
+  intercepting objects as they are associated with a :class:`.Session`.
 
 .. _unitofwork_merging:
 

diff --git a/lib/sqlalchemy/orm/identity.py b/lib/sqlalchemy/orm/identity.py
index 46be2b7196c09581a4c189e9f3810a5701f84aa4..b42703855d984b0121e8576f720bd84da2af19ad 100644 (file)
--- 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 b988a9230a9984a65cbb018f3161a598c1baab17..6c3f392bac15b4884d233e8ddfe3d7e749e91b52 100644 (file)
--- 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()