Behavioral Changes - ORM
========================
+.. _change_5074:
+
+Session does not immediately create a new SessionTransaction object
+----------------------------------------------------------------------------
+
+The :class:`.Session` object's default behavior of ``autocommit=False``
+historically has meant that there is always a :class:`.SessionTransaction`
+object in play, associated with the :class:`.Session` via the
+:attr:`.Session.transaction` attribute. When the given
+:class:`.SessionTransaction` was complete, due to a commit, rollback, or close,
+it was immediately replaced with a new one. The :class:`.SessionTransaction`
+by itself does not imply the usage of any connection-oriented resources, so
+this long-standing behavior has a particular elegance to it in that the state
+of :attr:`.Session.transaction` is always predictable as non-None.
+
+However, as part of the initiative in :ticket:`5056` to greatly reduce
+reference cycles, this assumption means that calling upon
+:meth:`.Session.close` results in a :class:`.Session` object that still has
+reference cycles and is more expensive to clean up, not to mention that there
+is a small overhead in constructing the :class:`.SessionTransaction`
+object, which meant that there would be unnecessary overhead created
+for a :class:`.Session` that for example invoked :meth:`.Session.commit`
+and then :meth:`.Session.close`.
+
+As such, it was decided that :meth:`.Session.close` should leave the internal
+state of ``self.transaction``, now referred to internally as
+``self._transaction``, as None, and that a new :class:`.SessionTransaction`
+should only be created when needed. For consistency and code coverage, this
+behavior was also expanded to include all the points at which "autobegin" is
+expected, not just when :meth:`.Session.close` were called.
+
+In particular, this causes a behavioral change for applications which
+subscribe to the :meth:`.SessionEvents.after_transaction_create` event hook;
+previously, this event would be emitted when the :class:`.Session` were first
+constructed, as well as for most actions that closed the previous transaction
+and would emit :meth:`.SessionEvents.after_transaction_end`. The new behavior
+is that :meth:`.SessionEvents.after_transaction_create` is emitted on demand,
+when the :class:`.Session` has not yet created a new
+:class:`.SessionTransaction` object and mapped objects are associated with the
+:class:`.Session` through methods like :meth:`.Session.add` and
+:meth:`.Session.delete`, when the :attr:`.Session.transaction` attribute is
+called upon, when the :meth:`.Session.flush` method has tasks to complete, etc.
+
+Besides the change in when the :meth:`.SessionEvents.after_transaction_create`
+event is emitted, the change should have no other user-visible impact on the
+:class:`.Session` object's behavior; the :class:`.Session` will continue to have
+the behavior that it remains usable for new operations after :meth:`.Session.close`
+is called, and the sequencing of how the :class:`.Session` interacts with the
+:class:`.Engine` and the database itself should also remain unaffected, since
+these operations were already operating in an on-demand fashion.
+
+:ticket:`5074`
+
.. _change_1763:
Eager loaders emit during unexpire operations
**Life Cycle**
- A :class:`.SessionTransaction` is associated with a :class:`.Session`
- in its default mode of ``autocommit=False`` immediately, associated
- with no database connections. As the :class:`.Session` is called upon
- to emit SQL on behalf of various :class:`.Engine` or :class:`.Connection`
- objects, a corresponding :class:`.Connection` and associated
- :class:`.Transaction` is added to a collection within the
- :class:`.SessionTransaction` object, becoming one of the
- connection/transaction pairs maintained by the
+ A :class:`.SessionTransaction` is associated with a :class:`.Session` in
+ its default mode of ``autocommit=False`` whenever the "autobegin" process
+ takes place, associated with no database connections. As the
+ :class:`.Session` is called upon to emit SQL on behalf of various
+ :class:`.Engine` or :class:`.Connection` objects, a corresponding
+ :class:`.Connection` and associated :class:`.Transaction` is added to a
+ collection within the :class:`.SessionTransaction` object, becoming one of
+ the connection/transaction pairs maintained by the
:class:`.SessionTransaction`. The start of a :class:`.SessionTransaction`
can be tracked using the :meth:`.SessionEvents.after_transaction_create`
event.
:meth:`.Session.close` methods are called. At this point, the
:class:`.SessionTransaction` removes its association with its parent
:class:`.Session`. A :class:`.Session` that is in ``autocommit=False``
- mode will create a new :class:`.SessionTransaction` to replace it
- immediately, whereas a :class:`.Session` that's in ``autocommit=True``
- mode will remain without a :class:`.SessionTransaction` until the
- :meth:`.Session.begin` method is called. The end of a
+ mode will create a new :class:`.SessionTransaction` to replace it when the
+ next "autobegin" event occurs, whereas a :class:`.Session` that's in
+ ``autocommit=True`` mode will remain without a :class:`.SessionTransaction`
+ until the :meth:`.Session.begin` method is called. The end of a
:class:`.SessionTransaction` can be tracked using the
:meth:`.SessionEvents.after_transaction_end` event.
+ .. versionchanged:: 1.4 the :class:`.SessionTransaction` is not created
+ immediately within a :class:`.Session` when constructed or when the
+ previous transaction is removed, it instead is created when the
+ :class:`.Session` is next used.
+
**Nesting and Subtransactions**
Another detail of :class:`.SessionTransaction` behavior is that it is
_rollback_exception = None
- def __init__(self, session, parent=None, nested=False):
+ def __init__(self, session, parent=None, nested=False, autobegin=False):
self.session = session
self._connections = {}
self._parent = parent
)
if self.session._enable_transaction_accounting:
- self._take_snapshot()
+ self._take_snapshot(autobegin=autobegin)
self.session.dispatch.after_transaction_create(self.session, self)
return result
- def _take_snapshot(self):
+ def _take_snapshot(self, autobegin=False):
if not self._is_transaction_boundary:
self._new = self._parent._new
self._deleted = self._parent._deleted
self._key_switches = self._parent._key_switches
return
- if not self.session._flushing:
+ if not autobegin and not self.session._flushing:
self.session.flush()
self._new = weakref.WeakKeyDictionary()
return self._parent
def close(self, invalidate=False):
- self.session.transaction = self._parent
+ self.session._transaction = self._parent
if self._parent is None:
for connection, transaction, autoclose in set(
self._connections.values()
self._state = CLOSED
self.session.dispatch.after_transaction_end(self.session, self)
- if self._parent is None:
- if not self.session.autocommit:
- self.session.begin()
self.session = None
self._connections = None
def __exit__(self, type_, value, traceback):
self._assert_active(deactive_ok=True, prepared_ok=True)
- if self.session.transaction is None:
+ if self.session._transaction is None:
return
if type_ is None:
try:
self.__binds = {}
self._flushing = False
self._warn_on_events = False
- self.transaction = None
+ self._transaction = None
self.hash_key = _new_sessionid()
self.autoflush = autoflush
self.autocommit = autocommit
for key, bind in binds.items():
self._add_bind(key, bind)
- if not self.autocommit:
- self.begin()
_sessions[self.hash_key] = self
connection_callable = None
- transaction = None
- """The current active or inactive :class:`.SessionTransaction`."""
+ @property
+ def transaction(self):
+ """The current active or inactive :class:`.SessionTransaction`.
+
+ If this session is in "autobegin" mode and the transaction was not
+ begun, this accessor will implicitly begin the transaction.
+
+ .. versionchanged:: 1.4 the :attr:`.Session.transaction` attribute
+ is now a read-only descriptor that will automatically start a
+ transaction in "autobegin" mode if one is not present.
+
+ """
+ self._autobegin()
+ return self._transaction
@util.memoized_property
def info(self):
"""
return {}
+ def _autobegin(self):
+ if not self.autocommit and self._transaction is None:
+ self._transaction = SessionTransaction(self, autobegin=True)
+ return True
+
+ return False
+
def begin(self, subtransactions=False, nested=False):
"""Begin a transaction on this :class:`.Session`.
"""
- if self.transaction is not None:
+
+ if self._autobegin():
+ if not subtransactions and not nested:
+ return
+
+ if self._transaction is not None:
if subtransactions or nested:
- self.transaction = self.transaction._begin(nested=nested)
+ self._transaction = self._transaction._begin(nested=nested)
else:
raise sa_exc.InvalidRequestError(
"A transaction is already begun. Use "
"subtransactions=True to allow subtransactions."
)
else:
- self.transaction = SessionTransaction(self, nested=nested)
- return self.transaction # needed for __enter__/__exit__ hook
+ self._transaction = SessionTransaction(self, nested=nested)
+ return self._transaction # needed for __enter__/__exit__ hook
def begin_nested(self):
"""Begin a "nested" transaction on this Session, e.g. SAVEPOINT.
:ref:`session_rollback`
"""
- if self.transaction is None:
+ if self._transaction is None:
pass
else:
- self.transaction.rollback()
+ self._transaction.rollback()
def commit(self):
"""Flush pending changes and commit the current transaction.
:ref:`session_committing`
"""
- if self.transaction is None:
- if not self.autocommit:
- self.begin()
- else:
+ if self._transaction is None:
+ if not self._autobegin():
raise sa_exc.InvalidRequestError("No transaction is begun.")
- self.transaction.commit()
+ self._transaction.commit()
def prepare(self):
"""Prepare the current transaction in progress for two phase commit.
:exc:`~sqlalchemy.exc.InvalidRequestError` is raised.
"""
- if self.transaction is None:
- if not self.autocommit:
- self.begin()
- else:
+ if self._transaction is None:
+ if not self._autobegin():
raise sa_exc.InvalidRequestError("No transaction is begun.")
- self.transaction.prepare()
+ self._transaction.prepare()
def connection(
self,
)
def _connection_for_bind(self, engine, execution_options=None, **kw):
- if self.transaction is not None:
- return self.transaction._connection_for_bind(
+ self._autobegin()
+
+ if self._transaction is not None:
+ return self._transaction._connection_for_bind(
engine, execution_options
)
else:
This clears all items and ends any transaction in progress.
If this session were created with ``autocommit=False``, a new
- transaction is immediately begun. Note that this new transaction does
- not use any connection resources until they are first needed.
+ transaction will be begun when the :class:`.Session` is next asked
+ to procure a database connection.
+
+ .. versionchanged:: 1.4 The :meth:`.Session.close` method does not
+ immediately create a new :class:`.SessionTransaction` object;
+ instead, the new :class:`.SessionTransaction` is created only if
+ the :class:`.Session` is used again for a database operation.
"""
self._close_impl(invalidate=False)
def _close_impl(self, invalidate):
self.expunge_all()
- if self.transaction is not None:
- for transaction in self.transaction._iterate_self_and_parents():
+ if self._transaction is not None:
+ for transaction in self._transaction._iterate_self_and_parents():
transaction.close(invalidate)
def expunge_all(self):
elif self.identity_map.contains_state(state):
self.identity_map.safe_discard(state)
self._deleted.pop(state, None)
- elif self.transaction:
+ elif self._transaction:
# state is "detached" from being deleted, but still present
# in the transaction snapshot
- self.transaction._deleted.pop(state, None)
+ self._transaction._deleted.pop(state, None)
statelib.InstanceState._detach_states(
states, self, to_transient=to_transient
)
# state has already replaced this one in the identity
# map (see test/orm/test_naturalpks.py ReversePKsTest)
self.identity_map.safe_discard(state)
- if state in self.transaction._key_switches:
- orig_key = self.transaction._key_switches[state][0]
+ if state in self._transaction._key_switches:
+ orig_key = self._transaction._key_switches[state][0]
else:
orig_key = state.key
- self.transaction._key_switches[state] = (
+ self._transaction._key_switches[state] = (
orig_key,
instance_key,
)
self._new.pop(state)
def _register_altered(self, states):
- if self._enable_transaction_accounting and self.transaction:
+ if self._enable_transaction_accounting and self._transaction:
for state in states:
if state in self._new:
- self.transaction._new[state] = True
+ self._transaction._new[state] = True
else:
- self.transaction._dirty[state] = True
+ self._transaction._dirty[state] = True
def _remove_newly_deleted(self, states):
persistent_to_deleted = self.dispatch.persistent_to_deleted or None
for state in states:
- if self._enable_transaction_accounting and self.transaction:
- self.transaction._deleted[state] = True
+ if self._enable_transaction_accounting and self._transaction:
+ self._transaction._deleted[state] = True
if persistent_to_deleted is not None:
# get a strong reference before we pop out of
self._after_attach(state, obj)
def _before_attach(self, state, obj):
+ self._autobegin()
+
if state.session_id == self.hash_key:
return False
:meth:`.SessionEvents.after_rollback` and related events.
"""
- return self.transaction and self.transaction.is_active
+ self._autobegin()
+ return self._transaction and self._transaction.is_active
identity_map = None
"""A mapping of object identities to objects themselves.
from sqlalchemy import ForeignKey
from sqlalchemy import inspect
from sqlalchemy import Integer
+from sqlalchemy import select
from sqlalchemy import Sequence
from sqlalchemy import String
from sqlalchemy import testing
from sqlalchemy.testing import eq_
from sqlalchemy.testing import fixtures
from sqlalchemy.testing import is_
+from sqlalchemy.testing import is_not_
from sqlalchemy.testing import is_true
from sqlalchemy.testing import mock
from sqlalchemy.testing import pickleable
s.close()
c.execute("select * from users")
+ def test_autobegin_execute(self):
+ # test the new autobegin behavior introduced in #5074
+ s = Session(testing.db)
+
+ is_(s._transaction, None)
+
+ s.execute(select([1]))
+ is_not_(s._transaction, None)
+
+ s.commit()
+ is_(s._transaction, None)
+
+ s.execute(select([1]))
+ is_not_(s._transaction, None)
+
+ s.close()
+ is_(s._transaction, None)
+
+ s.execute(select([1]))
+ is_not_(s._transaction, None)
+
+ s.close()
+ is_(s._transaction, None)
+
+ def test_autobegin_flush(self):
+ # test the new autobegin behavior introduced in #5074
+ User, users = self.classes.User, self.tables.users
+
+ mapper(User, users)
+
+ s = Session(testing.db)
+
+ is_(s._transaction, None)
+
+ # empty flush, nothing happens
+ s.flush()
+ is_(s._transaction, None)
+
+ s.add(User(id=1, name="name"))
+ s.flush()
+ is_not_(s._transaction, None)
+ s.commit()
+ is_(s._transaction, None)
+
+ def test_autobegin_begin_method(self):
+ s = Session(testing.db)
+
+ s.begin() # OK
+
+ assert_raises_message(
+ sa.exc.InvalidRequestError,
+ "A transaction is already begun. Use "
+ "subtransactions=True to allow subtransactions.",
+ s.begin,
+ )
+
@testing.requires.independent_connections
@engines.close_open_connections
def test_transaction(self):
sess.flush()
assert u1 not in sess
assert_raises(sa.exc.InvalidRequestError, sess.add, u1)
+ assert sess.transaction is not None
sess.rollback()
assert u1 in sess
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
