diff options
author | Mike Bayer <mike_mp@zzzcomputing.com> | 2015-08-27 23:38:14 -0400 |
---|---|---|
committer | Mike Bayer <mike_mp@zzzcomputing.com> | 2015-08-27 23:38:14 -0400 |
commit | 956907a4b15f6dcc492582a7ad03706ff62d96fb (patch) | |
tree | e49a175c979b932c6b47d9dd96348149248f64f8 | |
parent | ed535649d423020c816e66869016992df25e456e (diff) | |
download | sqlalchemy-956907a4b15f6dcc492582a7ad03706ff62d96fb.tar.gz |
- 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
-rw-r--r-- | doc/build/orm/session_state_management.rst | 32 | ||||
-rw-r--r-- | lib/sqlalchemy/orm/identity.py | 12 | ||||
-rw-r--r-- | lib/sqlalchemy/orm/session.py | 17 |
3 files changed, 52 insertions, 9 deletions
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: 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() |