From 956907a4b15f6dcc492582a7ad03706ff62d96fb Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Thu, 27 Aug 2015 23:38:14 -0400 Subject: - 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 --- doc/build/orm/session_state_management.rst | 32 ++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) (limited to 'doc') diff --git a/doc/build/orm/session_state_management.rst b/doc/build/orm/session_state_management.rst index 1ca7ca2e4..1a8bb3dee 100644 --- 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: -- cgit v1.2.1