edits

diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst
index 1bd7278328ad5aca2ea6d96bcf33cc8e7039fa86..91e1d698b318fa030a02f6fc3ac06e56f3770db1 100644 (file)
--- a/doc/build/core/connections.rst
+++ b/doc/build/core/connections.rst
@@ -97,13 +97,6 @@ DBAPI connection resource to the pool (SQLAlchemy achieves this by the usage
 of weakref callbacks - *never* the ``__del__`` method) - however it's never a
 good idea to rely upon Python garbage collection to manage resources.
 
-We have just summarized two of three usage patterns that are possible
-with the :class:`.Engine`.   When the :class:`.Connection` object is used
-explicitly, it's referred to as **explicit execution**.   When the 
-:meth:`~.Engine.execute` method of :class:`.Engine` is used, this 
-pattern is referred to as **explicit, connectionless execution**.  The 
-third pattern is known as **implicit execution** and is described later.
-
 Our example above illustrated the execution of a textual SQL string. 
 The :meth:`~.Connection.execute` method can of course accommodate more than 
 that, including the variety of SQL expression constructs described
@@ -240,7 +233,8 @@ refers to the usage of the ``execute()`` method on an object which is not a
 :class:`.Connection`.  This was illustrated using the :meth:`~.Engine.execute` method
 of :class:`.Engine`.
 
-A third case exists, which is to use the :meth:`~.Executable.execute` method of 
+In addition to "connectionless" execution, it is also possible 
+to use the :meth:`~.Executable.execute` method of 
 any :class:`.Executable` construct, which is a marker for SQL expression objects
 that support execution.   The SQL expression object itself references an
 :class:`.Engine` or :class:`.Connection` known as the **bind**, which it uses
@@ -329,7 +323,7 @@ connection resources derived from a thread-local variable whenever
 :meth:`.Engine.execute` or :meth:`.Engine.contextual_connect` is called. This
 connection resource is maintained as long as it is referenced, which allows
 multiple points of an application to share a transaction while using
-connectionless, explicit execution::
+connectionless execution::
 
     def call_operation1():
         engine.execute("insert into users values (?, ?)", 1, "john")
@@ -372,4 +366,4 @@ call :meth:`.Engine.contextual_connect`::
 
 Calling :meth:`~.Connection.close` on the "contextual" connection does not release 
 its resources until all other usages of that resource are closed as well, including
-that any ongoing transactions are rolled back or committed.
\ No newline at end of file
+that any ongoing transactions are rolled back or committed.

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 63d76efa02d6a313d54c01b5d63f0b042414d95f..79cadaea90187471d504ef4c91d8226358aec5c9 100644 (file)
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -812,10 +812,7 @@ class Connection(Connectable):
     upon the connection, including its expiration or timeout state. For the
     connection pool to properly manage connections, connections should be
     returned to the connection pool (i.e. ``connection.close()``) whenever the
-    connection is not in use. If your application has a need for management
-    of multiple connections or is otherwise long running (this includes all
-    web applications, threaded or not), don't hold a single connection open at
-    the module level.
+    connection is not in use.
 
     .. index::
       single: thread safety; Connection

diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index 4eae375d8be5e5d94574d0ce115ef69a628311fd..879a7b0c1e67f5c6c47cf59b0eab137b97fbe134 100644 (file)
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -318,25 +318,28 @@ def relationship(argument, secondary=None, **kwargs):
       which is already higher up in the chain.  This option applies
       both to joined- and subquery- eager loaders.
 
-    :param lazy=('select'|'joined'|'subquery'|'noload'|'dynamic'): specifies 
-      how the related items should be loaded. Values include:
+    :param lazy='select': specifies 
+      how the related items should be loaded.  Default value is 
+      ``select``.  Values include:
 
-      * 'select' - items should be loaded lazily when the property is first
-        accessed.
+      * ``select`` - items should be loaded lazily when the property is first
+        accessed, using a separate SELECT statement.
 
-      * 'joined' - items should be loaded "eagerly" in the same query as
-        that of the parent, using a JOIN or LEFT OUTER JOIN.
+      * ``joined`` - items should be loaded "eagerly" in the same query as
+        that of the parent, using a JOIN or LEFT OUTER JOIN.  Whether
+        the join is "outer" or not is determined by the ``innerjoin``
+        parameter.
               
-      * 'subquery' - items should be loaded "eagerly" within the same
+      * ``subquery`` - items should be loaded "eagerly" within the same
         query as that of the parent, using a second SQL statement
         which issues a JOIN to a subquery of the original
         statement.
 
-      * 'noload' - no loading should occur at any time.  This is to 
+      * ``noload`` - no loading should occur at any time.  This is to 
         support "write-only" attributes, or attributes which are
         populated in some manner specific to the application.
 
-      * 'dynamic' - the attribute will return a pre-configured
+      * ``dynamic`` - the attribute will return a pre-configured
         :class:`~sqlalchemy.orm.query.Query` object for all read 
         operations, onto which further filtering operations can be
         applied before iterating the results.  The dynamic