want to work with them again, so that they can resume their normal task of
representing database state.
example's sake! In reality, the :class:`.sessionmaker` would be somewhere
at the module level. The calls to instantiate :class:`.Session`
would then be placed at the point in the application where database
- conversations begin
* When do I construct a :class:`.Session`, when do I commit it, and when do I close it ?
begin a new transaction if it is used again, subsequent to the previous
transaction ending; from this it follows that the :class:`.Session`
is capable of having a lifespan across many transactions, though only
- one at a time. We refer to these two concepts as *transaction scope*
+ one at a time. We refer to these two concepts as **transaction scope**
The implication here is that the SQLAlchemy ORM is encouraging the
developer to establish these two scopes in his or her application,
pattern which establishes one as soon as it is needed. The request
then proceeds, with some system in place where application logic can access
the current :class:`.Session` in a manner associated with how the actual
set object is accessed. As the request ends, the :class:`.Session`
+ requet object is accessed. As the request ends, the :class:`.Session`
is torn down as well, usually through the usage of event hooks provided
by the web framework. The transaction used by the :class:`.Session`
may also be committed at this point, or alternatively the application may
In those situations where integration libraries are not available,
SQLAlchemy includes its own "helper" class known as
- :class:`.scoped_session`. This object actually is used as the basis
- of some integration packages, and provides both a quick way
+ :class:`.scoped_session`. A tutorial on the usage of this object
+ is at :ref:`unitofwork_contextual`. It provides both a quick way
to associate a :class:`.Session` with the current thread, as well as
patterns to associate :class:`.Session` objects with other kinds of
a series of operations for some period of time, which can be committed
at the end. Some examples:
- * A background daemon which spawns off child forks
+ * A background daemon which spawns off child forks
would want to create a :class:`.Session` local to each child
process work with that :class:`.Session` through the life of the "job"
that the fork is handling, then tear it down when the job is completed.
:class:`.Session` with a thread implies it is also associated with the web request
running within that thread, and vice versa, provided that the :class:`.Session` is
created only after the web request begins and torn down just before the web request ends.
-So it is a
very common practice to use :class:`.scoped_session` as a quick way
+So it is a common practice to use :class:`.scoped_session` as a quick way
to integrate the :class:`.Session` with a web application. The sequence
diagram below illustrates this flow::
based on any existing system of getting at "the current thing we are working with".
Suppose a web framework defines a library function ``get_current_request()``. An application
d on this framework can call this function at any time, and the result will be
+buil this framework can call this function at any time, and the result will be
some kind of ``Request`` object that represents the current request being processed.
If the ``Request`` object is hashable, then this function can be easily integrated with
:class:`.scoped_session` to associate the :class:`.Session` with the request. Below we illustrate