some docstrings

diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py
index 43dec46e3cc89c33242e25fa266494a102f31b9d..5a4865de0516e7a023de339701993ff6b5ee5c54 100644 (file)
--- a/lib/sqlalchemy/engine/__init__.py
+++ b/lib/sqlalchemy/engine/__init__.py
@@ -4,6 +4,47 @@
 # This module is part of SQLAlchemy and is released under
 # the MIT License: http://www.opensource.org/licenses/mit-license.php
 
+"""defines the basic components used to interface DBAPI modules with
+higher-level statement-construction, connection-management, 
+execution and result contexts.  The primary "entry point" class into
+this package is the Engine.
+
+The package is represented among several individual modules, including:
+
+    base.py
+        Defines interface classes and some implementation classes
+        which comprise the basic components used to interface between
+        a DBAPI, constructed and plain-text statements, 
+        connections, transactions, and results.
+        
+    default.py
+        Contains default implementations of some of the components 
+        defined in base.py.  All current database dialects use the 
+        classes in default.py as base classes for their own database-specific
+        implementations.
+    
+    strategies.py
+        the mechanics of constructing ``Engine`` objects are represented here.
+        Defines the ``EngineStrategy`` class which represents how to go from 
+        arguments specified to the ``create_engine()`` function, to a fully
+        constructed ``Engine``, including initialization of connection pooling,
+        dialects, and specific subclasses of ``Engine``.
+        
+    threadlocal.py
+        the ``TLEngine`` class is defined here, which is a subclass of the generic
+        ``Engine`` and tracks ``Connection`` and ``Transaction`` objects against
+        the identity of the current thread.  This allows certain programming patterns
+        based around the concept of a "thread-local connection" to be possible.  The
+        ``TLEngine`` is created by using the "threadlocal" engine strategy in 
+        conjunction with the ``create_engine()`` function.
+        
+    url.py
+        Defines the ``URL`` class which represents the individual components of a 
+        string URL passed to ``create_engine()``.  Also defines a basic module-loading
+        strategy for the dialect specifier within a URL.
+        
+"""
+
 from sqlalchemy import databases
 from sqlalchemy.engine.base import *
 from sqlalchemy.engine import strategies
@@ -45,10 +86,10 @@ def create_engine(*args, **kwargs):
     dialect and connection arguments, with additional keyword
     arguments sent as options to the dialect and resulting Engine.
 
-    The URL is in the form 
+    The URL is a string in the form 
     ``dialect://user:password@host/dbname[?key=value..]``, where 
     ``dialect`` is a name such as ``mysql``, ``oracle``, ``postgres``,
-    etc.
+    etc.  Alternatively, the URL can be an instance of ``sqlalchemy.engine.url.URL``.
 
     `**kwargs` represents options to be sent to the Engine itself as
     well as the components of the Engine, including the Dialect, the

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index e7a3f8feb1549ab0fac4c74aa2fc4b4362b325d1..b38e8faef6bb817bbda044aa38c089421118a6a2 100644 (file)
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -1,3 +1,13 @@
+# engine/base.py
+# Copyright (C) 2005, 2006, 2007 Michael Bayer mike_mp@zzzcomputing.com
+#
+# This module is part of SQLAlchemy and is released under
+# the MIT License: http://www.opensource.org/licenses/mit-license.php
+
+"""defines the basic components used to interface DBAPI modules with
+higher-level statement-construction, connection-management, 
+execution and result contexts."""
+
 from sqlalchemy import exceptions, sql, schema, util, types, logging
 import StringIO, sys, re
 
@@ -1018,6 +1028,16 @@ class ResultProxy(object):
             self.close()
 
 class BufferedRowResultProxy(ResultProxy):
+    """``ResultProxy`` that buffers the contents of a selection of rows before 
+    ``fetchone()`` is called.  This is to allow the results of 
+    ``cursor.description`` to be available immediately, when interfacing
+    with a DBAPI that requires rows to be consumed before this information is
+    available (currently psycopg2, when used with server-side cursors).
+    
+    The pre-fetching behavior fetches only one row initially, and then grows
+    its buffer size by a fixed amount with each successive need for additional 
+    rows up to a size of 100.
+    """
     def _init_metadata(self):
         self.__buffer_rows()
         super(BufferedRowResultProxy, self)._init_metadata()
@@ -1062,9 +1082,13 @@ class BufferedRowResultProxy(ResultProxy):
         return self.__rowbuffer + list(self.cursor.fetchall())
 
 class BufferedColumnResultProxy(ResultProxy):
-    """ResultProxy that loads all columns into memory each time fetchone() is
+    """``ResultProxy`` that loads all columns into memory each time fetchone() is
     called.  If fetchmany() or fetchall() are called, the full grid of results
-    is fetched.
+    is fetched.  This is to operate with databases where result rows contain "live"
+    results that fall out of scope unless explicitly fetched.  Currently this includes
+    just cx_Oracle LOB objects, but this behavior is known to exist in other DBAPIs as 
+    well (Pygresql, currently unsupported).
+
     """
     def _get_col(self, row, key):
         rec = self._convert_key(key)

diff --git a/lib/sqlalchemy/sql.py b/lib/sqlalchemy/sql.py
index a8663ed4c3a473cc827b326b18d163807c4e1c72..c3d0f9de081775d2e604ddcf0e6e564955c97e19 100644 (file)
--- a/lib/sqlalchemy/sql.py
+++ b/lib/sqlalchemy/sql.py
@@ -1,3 +1,4 @@
+# sql.py
 # Copyright (C) 2005, 2006, 2007 Michael Bayer mike_mp@zzzcomputing.com
 #
 # This module is part of SQLAlchemy and is released under