- rewrote the "connections" section

- improved pool docs
- typos etc.
- ClauseElement.execute() and scalar() make no sense - these are depreacted.
The official home is Executable.
- alias() is not executable, allowing it is sloppy so this goes under
the deprecated umbrella

4 files changed, 130 insertions, 20 deletions

diff --git a/lib/sqlalchemy/dialects/mssql/base.py b/lib/sqlalchemy/dialects/mssql/base.py
index 88ca36dbd..95a5bf4c4 100644
--- a/lib/sqlalchemy/dialects/mssql/base.py
+++ b/lib/sqlalchemy/dialects/mssql/base.py
@@ -104,7 +104,7 @@ Compatibility Levels
 MSSQL supports the notion of setting compatibility levels at the
 database level. This allows, for instance, to run a database that
 is compatibile with SQL2000 while running on a SQL2005 database
-server. ``server_version_info`` will always retrun the database
+server. ``server_version_info`` will always return the database
 server version information (in this case SQL2005) and not the
 compatibiility level information. Because of this, if running under
 a backwards compatibility mode SQAlchemy may attempt to use T-SQL
diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 20e7e2338..7098e695d 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -797,9 +797,10 @@ 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.
+    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
@@ -825,9 +826,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
@@ -1167,7 +1168,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:
@@ -1739,7 +1755,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)
@@ -1756,16 +1785,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/pool.py b/lib/sqlalchemy/pool.py
index 9d37b1838..c70a41069 100644
--- a/lib/sqlalchemy/pool.py
+++ b/lib/sqlalchemy/pool.py
@@ -132,13 +132,30 @@ class Pool(log.Identified):
                 self.add_listener(l)
 
     def unique_connection(self):
+        """Produce a DBAPI connection that is not referenced by any
+        thread-local context.
+        
+        This method is different from :meth:`.Pool.connect` only if the
+        ``use_threadlocal`` flag has been set to ``True``.
+        
+        """
+        
         return _ConnectionFairy(self).checkout()
 
     def create_connection(self):
+        """Called by subclasses to create a new ConnectionRecord."""
+        
         return _ConnectionRecord(self)
 
     def recreate(self):
-        """Return a new instance with identical creation arguments."""
+        """Return a new :class:`.Pool`, of the same class as this one
+        and configured with identical creation arguments.
+        
+        This method is used in conjunection with :meth:`dispose` 
+        to close out an entire :class:`.Pool` and create a new one in 
+        its place.
+        
+        """
 
         raise NotImplementedError()
 
@@ -149,11 +166,19 @@ class Pool(log.Identified):
         remaining open, It is advised to not reuse the pool once dispose()
         is called, and to instead use a new pool constructed by the
         recreate() method.
+        
         """
 
         raise NotImplementedError()
 
     def connect(self):
+        """Return a DBAPI connection from the pool.
+        
+        The connection is instrumented such that when its 
+        ``close()`` method is called, the connection will be returned to 
+        the pool.
+        
+        """
         if not self._use_threadlocal:
             return _ConnectionFairy(self).checkout()
 
@@ -169,17 +194,33 @@ class Pool(log.Identified):
         return agent.checkout()
 
     def return_conn(self, record):
+        """Given a _ConnectionRecord, return it to the :class:`.Pool`.
+        
+        This method is called when an instrumented DBAPI connection
+        has its ``close()`` method called.
+        
+        """
         if self._use_threadlocal and hasattr(self._threadconns, "current"):
             del self._threadconns.current
         self.do_return_conn(record)
 
     def get(self):
+        """Return a non-instrumented DBAPI connection from this :class:`.Pool`.
+        
+        This is called by ConnectionRecord in order to get its DBAPI 
+        resource.
+        
+        """
         return self.do_get()
 
     def do_get(self):
+        """Implementation for :meth:`get`, supplied by subclasses."""
+        
         raise NotImplementedError()
 
     def do_return_conn(self, conn):
+        """Implementation for :meth:`return_conn`, supplied by subclasses."""
+        
         raise NotImplementedError()
 
     def status(self):
diff --git a/lib/sqlalchemy/sql/expression.py b/lib/sqlalchemy/sql/expression.py
index d184816ab..5235a696b 100644
--- a/lib/sqlalchemy/sql/expression.py
+++ b/lib/sqlalchemy/sql/expression.py
@@ -1269,10 +1269,13 @@ class ClauseElement(Visitable):
                 return engine
         else:
             return None
-
+    
+    @util.deprecated("0.7", "Only SQL expressions which subclass :class:`.Executable` "
+                        "may provide the :func:`.execute` method.")
     def execute(self, *multiparams, **params):
-        """Compile and execute this :class:`ClauseElement`."""
-
+        """Compile and execute this :class:`ClauseElement`.
+        
+        """
         e = self.bind
         if e is None:
             label = getattr(self, 'description', self.__class__.__name__)
@@ -1284,6 +1287,8 @@ class ClauseElement(Visitable):
             raise exc.UnboundExecutionError(msg)
         return e._execute_clauseelement(self, multiparams, params)
 
+    @util.deprecated("0.7", "Only SQL expressions which subclass :class:`.Executable` "
+                        "may provide the :func:`.scalar` method.")
     def scalar(self, *multiparams, **params):
         """Compile and execute this :class:`ClauseElement`, returning the
         result's scalar representation.
@@ -2401,7 +2406,7 @@ class Executable(_Generative):
           COMMIT will be invoked in order to provide its "autocommit" feature.
           Typically, all INSERT/UPDATE/DELETE statements as well as
           CREATE/DROP statements have autocommit behavior enabled; SELECT
-          constructs do not. Use this option when invokving a SELECT or other
+          constructs do not. Use this option when invoking a SELECT or other
           specific SQL construct where COMMIT is desired (typically when
           calling stored procedures and such).
           
@@ -2436,6 +2441,27 @@ class Executable(_Generative):
         """
         self._execution_options = self._execution_options.union(kw)
 
+    def execute(self, *multiparams, **params):
+        """Compile and execute this :class:`.Executable`."""
+
+        e = self.bind
+        if e is None:
+            label = getattr(self, 'description', self.__class__.__name__)
+            msg = ('This %s is not bound and does not support direct '
+                   'execution. Supply this statement to a Connection or '
+                   'Engine for execution. Or, assign a bind to the statement '
+                   'or the Metadata of its underlying tables to enable '
+                   'implicit execution via this method.' % label)
+            raise exc.UnboundExecutionError(msg)
+        return e._execute_clauseelement(self, multiparams, params)
+
+    def scalar(self, *multiparams, **params):
+        """Compile and execute this :class:`.Executable`, returning the
+        result's scalar representation.
+        
+        """
+        return self.execute(*multiparams, **params).scalar()
+
 # legacy, some outside users may be calling this
 _Executable = Executable