summaryrefslogtreecommitdiff
path: root/lib/sqlalchemy/orm/session.py
diff options
context:
space:
mode:
authorMike Bayer <mike_mp@zzzcomputing.com>2010-08-12 10:47:07 -0400
committerMike Bayer <mike_mp@zzzcomputing.com>2010-08-12 10:47:07 -0400
commit646bb7ae373d387d24fc2854895d942af36a1b14 (patch)
tree0fe4bb88650761287bfba05f06d32319553f0cdd /lib/sqlalchemy/orm/session.py
parent0097879e6d53bda0b5dc51a62941263d0963c9c3 (diff)
downloadsqlalchemy-646bb7ae373d387d24fc2854895d942af36a1b14.tar.gz
- added much more verbiage about transactions and expire_all
Diffstat (limited to 'lib/sqlalchemy/orm/session.py')
-rw-r--r--lib/sqlalchemy/orm/session.py56
1 files changed, 48 insertions, 8 deletions
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index 8516a22de..c67dc5553 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -918,6 +918,13 @@ class Session(object):
Eagerly-loaded relational attributes will eagerly load within the
single refresh operation.
+ Note that a highly isolated transaction will return the same values as
+ were previously read in that same transaction, regardless of changes
+ in database state outside of that transaction - usage of
+ :meth:`~Session.refresh` usually only makes sense if non-ORM SQL
+ statement were emitted in the ongoing transaction, or if autocommit
+ mode is turned on.
+
:param attribute_names: optional. An iterable collection of
string attribute names indicating a subset of attributes to
be refreshed.
@@ -942,22 +949,55 @@ class Session(object):
mapperutil.instance_str(instance))
def expire_all(self):
- """Expires all persistent instances within this Session."""
+ """Expires all persistent instances within this Session.
+
+ When any attributes on a persitent instance is next accessed,
+ a query will be issued using the
+ :class:`.Session` object's current transactional context in order to
+ load all expired attributes for the given instance. Note that
+ a highly isolated transaction will return the same values as were
+ previously read in that same transaction, regardless of changes
+ in database state outside of that transaction.
+
+ To expire individual objects and individual attributes
+ on those objects, use :meth:`Session.expire`.
+
+ The :class:`Session` object's default behavior is to
+ expire all state whenever the :meth:`Session.rollback`
+ or :meth:`Session.commit` methods are called, so that new
+ state can be loaded for the new transaction. For this reason,
+ calling :meth:`Session.expire_all` should not be needed when
+ autocommit is ``False``, assuming the transaction is isolated.
+ """
for state in self.identity_map.all_states():
_expire_state(state, state.dict, None, instance_dict=self.identity_map)
def expire(self, instance, attribute_names=None):
"""Expire the attributes on an instance.
- Marks the attributes of an instance as out of date. When an expired
- attribute is next accessed, query will be issued to the database and
- the attributes will be refreshed with their current database value.
- ``expire()`` is a lazy variant of ``refresh()``.
+ Marks the attributes of an instance as out of date. When an expired
+ attribute is next accessed, a query will be issued to the
+ :class:`.Session` object's current transactional context in order to
+ load all expired attributes for the given instance. Note that
+ a highly isolated transaction will return the same values as were
+ previously read in that same transaction, regardless of changes
+ in database state outside of that transaction.
+
+ To expire all objects in the :class:`.Session` simultaneously,
+ use :meth:`Session.expire_all`.
+
+ The :class:`Session` object's default behavior is to
+ expire all state whenever the :meth:`Session.rollback`
+ or :meth:`Session.commit` methods are called, so that new
+ state can be loaded for the new transaction. For this reason,
+ calling :meth:`Session.expire` only makes sense for the specific
+ case that a non-ORM SQL statement was emitted in the current
+ transaction.
- The ``attribute_names`` argument is an iterable collection
- of attribute names indicating a subset of attributes to be
- expired.
+ :param instance: The instance to be refreshed.
+ :param attribute_names: optional list of string attribute names
+ indicating a subset of attributes to be expired.
"""
try: