From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Fri, 21 Mar 2014 02:46:23 +0000 (-0400)
Subject: - reword the paragraph which talks about web framework integration for sessions:
X-Git-Tag: rel_0_8_6~10
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=cb51fe3ef894f279537f6de91af23034da226f62;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- reword the paragraph which talks about web framework integration for sessions:

1. fix the typo in the paragraph, fixes #2998
2. as zope-sqlalchemy only provides transaction integration and not session scoping,
dial back the language here as people are probably using scoped_session with pyramid anyway
3. as I'm going to again start recommending people don't cling to flask-sqlalchemy so hard,
take out the word "strongly" from the recommendation.
4. as flask is the only framework I can think of that actually has an explicit SQLAlchemy
layer that handles setting up scoped_session, take out the word "most", now it's "some web frameworks"
(by which it means "only flask...and flask-sqlalchemy is probably not worth using anyway")
---

diff --git a/doc/build/orm/session.rst b/doc/build/orm/session.rst
index 92aa337b9e..05b2535bcd 100644
--- a/doc/build/orm/session.rst
+++ b/doc/build/orm/session.rst
@@ -301,19 +301,16 @@ opt for an explicit commit pattern, only committing for those requests
 where one is warranted, but still always tearing down the :class:`.Session`
 unconditionally at the end.
 
-Most web frameworks include infrastructure to establish a single
-:class:`.Session`, associated with the request, which is correctly
-constructed and torn down corresponding
-torn down at the end of a request.   Such infrastructure pieces
-include products such as `Flask-SQLAlchemy <http://packages.python.org/Flask-SQLAlchemy/>`_,
+Some web frameworks include infrastructure to assist in the task
+of aligning the lifespan of a :class:`.Session` with that of a web request.
+This includes products such as `Flask-SQLAlchemy <http://packages.python.org/Flask-SQLAlchemy/>`_,
 for usage in conjunction with the Flask web framework,
 and `Zope-SQLAlchemy <http://pypi.python.org/pypi/zope.sqlalchemy>`_,
-for usage in conjunction with the Pyramid and Zope frameworks.
-SQLAlchemy strongly recommends that these products be used as
-available.
+typically used with the Pyramid framework.
+SQLAlchemy recommends that these products be used as available.
 
-In those situations where integration libraries are not available,
-SQLAlchemy includes its own "helper" class known as
+In those situations where the integration libraries are not
+provided or are insufficient, SQLAlchemy includes its own "helper" class known as
 :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