From bbcf70019aef8af41fd59b5a7f33e4ed61727945 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Sun, 30 Sep 2012 11:31:49 -0400 Subject: [PATCH] session modernize --- doc/build/orm/session.rst | 78 +++++++++++++++++++-------------------- 1 file changed, 39 insertions(+), 39 deletions(-) diff --git a/doc/build/orm/session.rst b/doc/build/orm/session.rst index 17d00b440d..98be1ede6c 100644 --- a/doc/build/orm/session.rst +++ b/doc/build/orm/session.rst @@ -175,7 +175,7 @@ It's helpful to know the states which an instance can have within a session: object has to the ORM is that its class has a ``mapper()`` associated with it. -* **Pending** - when you :func:`~sqlalchemy.orm.session.Session.add` a transient +* **Pending** - when you :meth:`~.Session.add` a transient instance, it becomes pending. It still wasn't actually flushed to the database yet, but it will be when the next flush occurs. @@ -356,7 +356,7 @@ Session Frequently Asked Questions * How can I get the :class:`~sqlalchemy.orm.session.Session` for a certain object ? - Use the :func:`~sqlalchemy.orm.session.Session.object_session` classmethod + Use the :meth:`~.Session.object_session` classmethod available on :class:`~sqlalchemy.orm.session.Session`:: session = Session.object_session(someobject) @@ -392,7 +392,7 @@ Session Frequently Asked Questions Querying -------- -The :func:`~sqlalchemy.orm.session.Session.query` function takes one or more +The :meth:`~.Session.query` function takes one or more *entities* and returns a new :class:`~sqlalchemy.orm.query.Query` object which will issue mapper queries within the context of this Session. An entity is defined as a mapped class, a :class:`~sqlalchemy.orm.mapper.Mapper` object, an @@ -428,7 +428,7 @@ The :class:`.Query` object is introduced in great detail in Adding New or Existing Items ---------------------------- -:func:`~sqlalchemy.orm.session.Session.add` is used to place instances in the +:meth:`~.Session.add` is used to place instances in the session. For *transient* (i.e. brand new) instances, this will have the effect of an INSERT taking place for those instances upon the next flush. For instances which are *persistent* (i.e. were loaded by this session), they are @@ -444,11 +444,11 @@ using this method:: session.commit() # write changes to the database To add a list of items to the session at once, use -:func:`~sqlalchemy.orm.session.Session.add_all`:: +:meth:`~.Session.add_all`:: session.add_all([item1, item2, item3]) -The :func:`~sqlalchemy.orm.session.Session.add` operation **cascades** along +The :meth:`~.Session.add` operation **cascades** along the ``save-update`` cascade. For more details see the section :ref:`unitofwork_cascades`. @@ -457,7 +457,7 @@ the ``save-update`` cascade. For more details see the section Merging ------- -:func:`~sqlalchemy.orm.session.Session.merge` transfers state from an +:meth:`~.Session.merge` transfers state from an outside object into a new or already existing instance within a session. It also reconciles the incoming data against the state of the database, producing a history stream which will be applied towards the next @@ -745,12 +745,12 @@ When the :class:`~sqlalchemy.orm.session.Session` is used with its default configuration, the flush step is nearly always done transparently. Specifically, the flush occurs before any individual :class:`~sqlalchemy.orm.query.Query` is issued, as well as within the -:func:`~sqlalchemy.orm.session.Session.commit` call before the transaction is +:meth:`~.Session.commit` call before the transaction is committed. It also occurs before a SAVEPOINT is issued when -:func:`~sqlalchemy.orm.session.Session.begin_nested` is used. +:meth:`~.Session.begin_nested` is used. Regardless of the autoflush setting, a flush can always be forced by issuing -:func:`~sqlalchemy.orm.session.Session.flush`:: +:meth:`~.Session.flush`:: session.flush() @@ -772,10 +772,10 @@ The flush process *always* occurs within a transaction, even if the :class:`~sqlalchemy.orm.session.Session` has been configured with ``autocommit=True``, a setting that disables the session's persistent transactional state. If no transaction is present, -:func:`~sqlalchemy.orm.session.Session.flush` creates its own transaction and +:meth:`~.Session.flush` creates its own transaction and commits it. Any failures during flush will always result in a rollback of whatever transaction is present. If the Session is not in ``autocommit=True`` -mode, an explicit call to :func:`~sqlalchemy.orm.session.Session.rollback` is +mode, an explicit call to :meth:`~.Session.rollback` is required after a flush fails, even though the underlying transaction will have been rolled back already - this is so that the overall nesting pattern of so-called "subtransactions" is consistently maintained. @@ -783,14 +783,14 @@ so-called "subtransactions" is consistently maintained. Committing ---------- -:func:`~sqlalchemy.orm.session.Session.commit` is used to commit the current -transaction. It always issues :func:`~sqlalchemy.orm.session.Session.flush` +:meth:`~.Session.commit` is used to commit the current +transaction. It always issues :meth:`~.Session.flush` beforehand to flush any remaining state to the database; this is independent of the "autoflush" setting. If no transaction is present, it raises an error. Note that the default behavior of the :class:`~sqlalchemy.orm.session.Session` is that a "transaction" is always present; this behavior can be disabled by setting ``autocommit=True``. In autocommit mode, a transaction can be -initiated by calling the :func:`~sqlalchemy.orm.session.Session.begin` method. +initiated by calling the :meth:`~.Session.begin` method. .. note:: @@ -802,7 +802,7 @@ initiated by calling the :func:`~sqlalchemy.orm.session.Session.begin` method. "transaction" is completed. See :ref:`unitofwork_transaction` for further detail. -Another behavior of :func:`~sqlalchemy.orm.session.Session.commit` is that by +Another behavior of :meth:`~.Session.commit` is that by default it expires the state of all instances present after the commit is complete. This is so that when the instances are next accessed, either through attribute access or by them being present in a @@ -821,7 +821,7 @@ transaction is present. Rolling Back ------------ -:func:`~sqlalchemy.orm.session.Session.rollback` rolls back the current +:meth:`~.Session.rollback` rolls back the current transaction. With a default configured session, the post-rollback state of the session is as follows: @@ -842,15 +842,15 @@ session is as follows: With that state understood, the :class:`~sqlalchemy.orm.session.Session` may safely continue usage after a rollback occurs. -When a :func:`~sqlalchemy.orm.session.Session.flush` fails, typically for +When a :meth:`~.Session.flush` fails, typically for reasons like primary key, foreign key, or "not nullable" constraint -violations, a :func:`~sqlalchemy.orm.session.Session.rollback` is issued +violations, a :meth:`~.Session.rollback` is issued automatically (it's currently not possible for a flush to continue after a partial failure). However, the flush process always uses its own transactional demarcator called a *subtransaction*, which is described more fully in the docstrings for :class:`~sqlalchemy.orm.session.Session`. What it means here is that even though the database transaction has been rolled back, the end user -must still issue :func:`~sqlalchemy.orm.session.Session.rollback` to fully +must still issue :meth:`~.Session.rollback` to fully reset the state of the :class:`~sqlalchemy.orm.session.Session`. Expunging @@ -863,14 +863,14 @@ the detached state, and pending instances to the transient state: session.expunge(obj1) -To remove all items, call :func:`~sqlalchemy.orm.session.Session.expunge_all` +To remove all items, call :meth:`~.Session.expunge_all` (this method was formerly known as ``clear()``). Closing ------- -The :func:`~sqlalchemy.orm.session.Session.close` method issues a -:func:`~sqlalchemy.orm.session.Session.expunge_all`, and releases any +The :meth:`~.Session.close` method issues a +:meth:`~.Session.expunge_all`, and releases any transactional/connection resources. When connections are returned to the connection pool, transactional state is rolled back as well. @@ -1169,7 +1169,7 @@ This behavior can be disabled using the ``cascade_backrefs`` flag:: So above, the assignment of ``i1.order = o1`` will append ``i1`` to the ``items`` collection of ``o1``, but will not add ``i1`` to the session. You can, of -course, :func:`~.Session.add` ``i1`` to the session at a later point. This option +course, :meth:`~.Session.add` ``i1`` to the session at a later point. This option may be helpful for situations where an object needs to be kept out of a session until it's construction is completed, but still needs to be given associations to objects which are already persistent in the target session. @@ -1256,7 +1256,7 @@ Using SAVEPOINT --------------- SAVEPOINT transactions, if supported by the underlying engine, may be -delineated using the :func:`~sqlalchemy.orm.session.Session.begin_nested` +delineated using the :meth:`~.Session.begin_nested` method:: Session = sessionmaker() @@ -1270,19 +1270,19 @@ method:: session.commit() # commits u1 and u2 -:func:`~sqlalchemy.orm.session.Session.begin_nested` may be called any number +:meth:`~.Session.begin_nested` may be called any number of times, which will issue a new SAVEPOINT with a unique identifier for each -call. For each :func:`~sqlalchemy.orm.session.Session.begin_nested` call, a -corresponding :func:`~sqlalchemy.orm.session.Session.rollback` or -:func:`~sqlalchemy.orm.session.Session.commit` must be issued. +call. For each :meth:`~.Session.begin_nested` call, a +corresponding :meth:`~.Session.rollback` or +:meth:`~.Session.commit` must be issued. -When :func:`~sqlalchemy.orm.session.Session.begin_nested` is called, a -:func:`~sqlalchemy.orm.session.Session.flush` is unconditionally issued +When :meth:`~.Session.begin_nested` is called, a +:meth:`~.Session.flush` is unconditionally issued (regardless of the ``autoflush`` setting). This is so that when a -:func:`~sqlalchemy.orm.session.Session.rollback` occurs, the full state of the +:meth:`~.Session.rollback` occurs, the full state of the session is expired, thus causing all subsequent attribute/instance access to reference the full state of the :class:`~sqlalchemy.orm.session.Session` right -before :func:`~sqlalchemy.orm.session.Session.begin_nested` was called. +before :meth:`~.Session.begin_nested` was called. :meth:`~.Session.begin_nested`, in the same manner as the less often used :meth:`~.Session.begin` method, returns a transactional object @@ -1344,7 +1344,7 @@ goes back into "autocommit" mode, until :meth:`.Session.begin` is called again:: session.rollback() raise -The :func:`.Session.begin` method also returns a +The :meth:`~.Session.begin` method also returns a transactional token which is compatible with the Python 2.6 ``with`` statement:: @@ -1417,7 +1417,7 @@ For backends which support two-phase operaration (currently MySQL and PostgreSQL), the session can be instructed to use two-phase commit semantics. This will coordinate the committing of transactions across databases so that the transaction is either committed or rolled back in all databases. You can -also :func:`~sqlalchemy.orm.session.Session.prepare` the session for +also :meth:`~.Session.prepare` the session for interacting with transactions not managed by SQLAlchemy. To use two phase transactions set the flag ``twophase=True`` on the session:: @@ -1468,7 +1468,7 @@ Using SQL Expressions with Sessions SQL expressions and strings can be executed via the :class:`~sqlalchemy.orm.session.Session` within its transactional context. This is most easily accomplished using the -:func:`~sqlalchemy.orm.session.Session.execute` method, which returns a +:meth:`~.Session.execute` method, which returns a :class:`~sqlalchemy.engine.base.ResultProxy` in the same manner as an :class:`~sqlalchemy.engine.base.Engine` or :class:`~sqlalchemy.engine.base.Connection`:: @@ -1484,7 +1484,7 @@ This is most easily accomplished using the The current :class:`~sqlalchemy.engine.base.Connection` held by the :class:`~sqlalchemy.orm.session.Session` is accessible using the -:func:`~sqlalchemy.orm.session.Session.connection` method:: +:meth:`~.Session.connection` method:: connection = session.connection() @@ -1493,8 +1493,8 @@ bound to a single :class:`~sqlalchemy.engine.base.Engine` or :class:`~sqlalchemy.engine.base.Connection`. To execute statements using a :class:`~sqlalchemy.orm.session.Session` which is bound either to multiple engines, or none at all (i.e. relies upon bound metadata), both -:func:`~sqlalchemy.orm.session.Session.execute` and -:func:`~sqlalchemy.orm.session.Session.connection` accept a ``mapper`` keyword +:meth:`~.Session.execute` and +:meth:`~.Session.connection` accept a ``mapper`` keyword argument, which is passed a mapped class or :class:`~sqlalchemy.orm.mapper.Mapper` instance, which is used to locate the proper context for the desired engine:: -- 2.47.2