- merge tip, 0.6.4 + 0.6.5

3 files changed, 117 insertions, 37 deletions

diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py
index b4894250f..43d3dd038 100644
--- a/lib/sqlalchemy/engine/__init__.py
+++ b/lib/sqlalchemy/engine/__init__.py
@@ -132,12 +132,19 @@ def create_engine(*args, **kwargs):
         additional keyword arguments.
 
     :param convert_unicode=False: if set to True, all
-        String/character based types will convert Unicode values to raw
-        byte values going into the database, and all raw byte values to
+        String/character based types will convert Python Unicode values to raw
+        byte values sent to the DBAPI as bind parameters, and all raw byte values to
         Python Unicode coming out in result sets. This is an
-        engine-wide method to provide unicode conversion across the
-        board. For unicode conversion on a column-by-column level, use
-        the ``Unicode`` column type instead, described in `types`.
+        engine-wide method to provide Unicode conversion across the
+        board for those DBAPIs that do not accept Python Unicode objects
+        as input.  For Unicode conversion on a column-by-column level, use
+        the ``Unicode`` column type instead, described in :ref:`types_toplevel`.  Note that
+        many DBAPIs have the ability to return Python Unicode objects in
+        result sets directly - SQLAlchemy will use these modes of operation
+        if possible and will also attempt to detect "Unicode returns" 
+        behavior by the DBAPI upon first connect by the 
+        :class:`.Engine`.  When this is detected, string values in 
+        result sets are passed through without further processing.
 
     :param creator: a callable which returns a DBAPI connection.
         This creation function will be passed to the underlying
@@ -188,10 +195,13 @@ def create_engine(*args, **kwargs):
         opened above and beyond the pool_size setting, which defaults
         to five. this is only used with :class:`~sqlalchemy.pool.QueuePool`.
 
-    :param module=None: used by database implementations which
-        support multiple DBAPI modules, this is a reference to a DBAPI2
-        module to be used instead of the engine's default module. For
-        PostgreSQL, the default is psycopg2. For Oracle, it's cx_Oracle.
+    :param module=None: reference to a Python module object (the module itself, not
+        its string name).  Specifies an alternate DBAPI module to be used
+        by the engine's dialect.  Each sub-dialect references a specific DBAPI which
+        will be imported before first connect.  This parameter causes the
+        import to be bypassed, and the given module to be used instead.
+        Can be used for testing of DBAPIs as well as to inject "mock"
+        DBAPI implementations into the :class:`.Engine`.
 
     :param pool=None: an already-constructed instance of
         :class:`~sqlalchemy.pool.Pool`, such as a
@@ -199,7 +209,7 @@ def create_engine(*args, **kwargs):
         pool will be used directly as the underlying connection pool
         for the engine, bypassing whatever connection parameters are
         present in the URL argument. For information on constructing
-        connection pools manually, see `pooling`.
+        connection pools manually, see :ref:`pooling_toplevel`.
 
     :param poolclass=None: a :class:`~sqlalchemy.pool.Pool`
         subclass, which will be used to create a connection pool
@@ -224,7 +234,7 @@ def create_engine(*args, **kwargs):
         connections after the given number of seconds has passed. It
         defaults to -1, or no timeout. For example, setting to 3600
         means connections will be recycled after one hour. Note that
-        MySQL in particular will ``disconnect automatically`` if no
+        MySQL in particular will disconnect automatically if no
         activity is detected on a connection for eight hours (although
         this is configurable with the MySQLDB connection itself and the
         server configuration as well).
@@ -233,8 +243,8 @@ def create_engine(*args, **kwargs):
         up on getting a connection from the pool. This is only used
         with :class:`~sqlalchemy.pool.QueuePool`.
 
-    :param strategy='plain': used to invoke alternate :class:`~sqlalchemy.engine.base.Engine.`
-        implementations. Currently available is the ``threadlocal``
+    :param strategy='plain': selects alternate engine implementations.
+        Currently available is the ``threadlocal``
         strategy, which is described in :ref:`threadlocal_strategy`.
     
     """
diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index a02e90aba..6c81f8b74 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -797,11 +797,22 @@ class Connectable(object):
 class Connection(Connectable):
     """Provides high-level functionality for a wrapped DB-API connection.
 
-    Provides execution support for string-based SQL statements as well
-    as ClauseElement, Compiled and DefaultGenerator objects.  Provides
-    a :meth:`begin` method to return Transaction objects.
-
-    The Connection object is **not** thread-safe.
+    Provides execution support for string-based SQL statements as well as
+    :class:`.ClauseElement`, :class:`.Compiled` and :class:`.DefaultGenerator`
+    objects. Provides a :meth:`begin` method to return :class:`.Transaction`
+    objects.
+
+    The Connection object is **not** thread-safe.  While a Connection can be
+    shared among threads using properly synchronized access, it is still
+    possible that the underlying DBAPI connection may not support shared
+    access between threads.  Check the DBAPI documentation for details.
+    
+    The Connection object represents a single dbapi connection checked out
+    from the connection pool. In this state, the connection pool has no affect
+    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.
 
     .. index::
       single: thread safety; Connection
@@ -812,9 +823,9 @@ class Connection(Connectable):
                  _branch=False, _execution_options=None):
         """Construct a new Connection.
 
-        Connection objects are typically constructed by an
-        :class:`~sqlalchemy.engine.Engine`, see the ``connect()`` and
-        ``contextual_connect()`` methods of Engine.
+        The constructor here is not public and is only called only by an
+        :class:`.Engine`. See :meth:`.Engine.connect` and
+        :meth:`.Engine.contextual_connect` methods.
         
         """
         self.engine = engine
@@ -1154,7 +1165,22 @@ class Connection(Connectable):
         return self.execute(object, *multiparams, **params).scalar()
 
     def execute(self, object, *multiparams, **params):
-        """Executes and returns a ResultProxy."""
+        """Executes the given construct and returns a :class:`.ResultProxy`.
+        
+        The construct can be one of:
+        
+        * a textual SQL string
+        * any :class:`.ClauseElement` construct that is also
+          a subclass of :class:`.Executable`, such as a 
+          :func:`.select` construct
+        * a :class:`.FunctionElement`, such as that generated
+          by :attr:`.func`, will be automatically wrapped in
+          a SELECT statement, which is then executed.
+        * a :class:`.DDLElement` object
+        * a :class:`.DefaultGenerator` object
+        * a :class:`.Compiled` object
+            
+        """
 
         for c in type(object).__mro__:
             if c in Connection.executors:
@@ -1451,6 +1477,12 @@ class Connection(Connectable):
 class Transaction(object):
     """Represent a Transaction in progress.
 
+    The object provides :meth:`.rollback` and :meth:`.commit`
+    methods in order to control transaction boundaries.  It 
+    also implements a context manager interface so that 
+    the Python ``with`` statement can be used with the 
+    :meth:`.Connection.begin` method.
+    
     The Transaction object is **not** threadsafe.
 
     .. index::
@@ -1458,12 +1490,17 @@ class Transaction(object):
     """
 
     def __init__(self, connection, parent):
+        """The constructor for :class:`.Transaction` is private
+        and is called from within the :class:`.Connection.begin` 
+        implementation.
+        
+        """
         self.connection = connection
         self._parent = parent or self
         self.is_active = True
 
     def close(self):
-        """Close this transaction.
+        """Close this :class:`.Transaction`.
 
         If this transaction is the base transaction in a begin/commit
         nesting, the transaction will rollback().  Otherwise, the
@@ -1471,6 +1508,7 @@ class Transaction(object):
 
         This is used to cancel a Transaction without affecting the scope of
         an enclosing transaction.
+        
         """
         if not self._parent.is_active:
             return
@@ -1478,6 +1516,9 @@ class Transaction(object):
             self.rollback()
 
     def rollback(self):
+        """Roll back this :class:`.Transaction`.
+        
+        """
         if not self._parent.is_active:
             return
         self._do_rollback()
@@ -1487,6 +1528,8 @@ class Transaction(object):
         self._parent.rollback()
 
     def commit(self):
+        """Commit this :class:`.Transaction`."""
+        
         if not self._parent.is_active:
             raise exc.InvalidRequestError("This transaction is inactive")
         self._do_commit()
@@ -1783,7 +1826,20 @@ class Engine(Connectable, log.Identified):
             conn.close()
 
     def execute(self, statement, *multiparams, **params):
-        """Executes and returns a ResultProxy."""
+        """Executes the given construct and returns a :class:`.ResultProxy`.
+        
+        The arguments are the same as those used by
+        :meth:`.Connection.execute`.
+        
+        Here, a :class:`.Connection` is acquired using the
+        :meth:`~.Engine.contextual_connect` method, and the statement executed
+        with that connection. The returned :class:`.ResultProxy` is flagged
+        such that when the :class:`.ResultProxy` is exhausted and its
+        underlying cursor is closed, the :class:`.Connection` created here
+        will also be closed, which allows its associated DBAPI connection
+        resource to be returned to the connection pool.
+        
+        """
 
         connection = self.contextual_connect(close_with_result=True)
         return connection.execute(statement, *multiparams, **params)
@@ -1800,16 +1856,30 @@ class Engine(Connectable, log.Identified):
         return connection._execute_compiled(compiled, multiparams, params)
 
     def connect(self, **kwargs):
-        """Return a newly allocated Connection object."""
+        """Return a new :class:`.Connection` object.
+        
+        The :class:`.Connection`, upon construction, will procure a DBAPI connection
+        from the :class:`.Pool` referenced by this :class:`.Engine`,
+        returning it back to the :class:`.Pool` after the :meth:`.Connection.close`
+        method is called.
+        
+        """
 
         return self.Connection(self, **kwargs)
 
     def contextual_connect(self, close_with_result=False, **kwargs):
-        """Return a Connection object which may be newly allocated, 
-        or may be part of some ongoing context.
-
-        This Connection is meant to be used by the various 
-        "auto-connecting" operations.
+        """Return a :class:`.Connection` object which may be part of some ongoing context.
+        
+        By default, this method does the same thing as :meth:`.Engine.connect`.
+        Subclasses of :class:`.Engine` may override this method
+        to provide contextual behavior.
+
+        :param close_with_result: When True, the first :class:`.ResultProxy` created
+          by the :class:`.Connection` will call the :meth:`.Connection.close` method
+          of that connection as soon as any pending result rows are exhausted.  
+          This is used to supply the "connectionless execution" behavior provided
+          by the :meth:`.Engine.execute` method.
+          
         """
 
         return self.Connection(self, 
diff --git a/lib/sqlalchemy/engine/reflection.py b/lib/sqlalchemy/engine/reflection.py
index 4a34ef1c6..def889e6d 100644
--- a/lib/sqlalchemy/engine/reflection.py
+++ b/lib/sqlalchemy/engine/reflection.py
@@ -50,27 +50,27 @@ class Inspector(object):
     consistent interface as well as caching support for previously
     fetched metadata.
     
-    The preferred method to construct an :class:`Inspector` is via the
+    The preferred method to construct an :class:`.Inspector` is via the
     :meth:`Inspector.from_engine` method.   I.e.::
     
         engine = create_engine('...')
         insp = Inspector.from_engine(engine)
     
     Where above, the :class:`~sqlalchemy.engine.base.Dialect` may opt
-    to return an :class:`Inspector` subclass that provides additional
+    to return an :class:`.Inspector` subclass that provides additional
     methods specific to the dialect's target database.
     
     """
 
     def __init__(self, bind):
-        """Initialize a new :class:`Inspector`.
+        """Initialize a new :class:`.Inspector`.
 
         :param bind: a :class:`~sqlalchemy.engine.base.Connectable`, 
           which is typically an instance of 
           :class:`~sqlalchemy.engine.base.Engine` or 
           :class:`~sqlalchemy.engine.base.Connection`.
         
-        For a dialect-specific instance of :class:`Inspector`, see
+        For a dialect-specific instance of :class:`.Inspector`, see
         :meth:`Inspector.from_engine`
 
         """
@@ -98,12 +98,12 @@ class Inspector(object):
           :class:`~sqlalchemy.engine.base.Engine` or 
           :class:`~sqlalchemy.engine.base.Connection`.
         
-        This method differs from direct a direct constructor call of :class:`Inspector`
+        This method differs from direct a direct constructor call of :class:`.Inspector`
         in that the :class:`~sqlalchemy.engine.base.Dialect` is given a chance to provide
-        a dialect-specific :class:`Inspector` instance, which may provide additional
+        a dialect-specific :class:`.Inspector` instance, which may provide additional
         methods.
         
-        See the example at :class:`Inspector`.
+        See the example at :class:`.Inspector`.
         
         """
         if hasattr(bind.dialect, 'inspector'):