roughly the finished product.

4 files changed, 85 insertions, 23 deletions

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 14ebf916b..20e7e2338 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -801,7 +801,20 @@ class Connection(Connectable):
     as ClauseElement, Compiled and DefaultGenerator objects.  Provides
     a :meth:`begin` method to return Transaction objects.
 
-    The Connection object is **not** thread-safe.
+    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. 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.
 
     .. index::
       single: thread safety; Connection
diff --git a/lib/sqlalchemy/orm/attributes.py b/lib/sqlalchemy/orm/attributes.py
index 800f3889f..bccdaeb4b 100644
--- a/lib/sqlalchemy/orm/attributes.py
+++ b/lib/sqlalchemy/orm/attributes.py
@@ -35,18 +35,18 @@ NEVER_SET = util.symbol('NEVER_SET')
 
 # "passive" get settings
 # TODO: the True/False values need to be factored out
-# of the rest of ORM code
-# don't fire off any callables, and don't initialize the attribute to
-# an empty value
 PASSIVE_NO_INITIALIZE = True #util.symbol('PASSIVE_NO_INITIALIZE')
+"""Symbol indicating that loader callables should
+   not be fired off, and a non-initialized attribute 
+   should remain that way."""
 
-# don't fire off any callables, but if no callables present
-# then initialize to an empty value/collection
 # this is used by backrefs.
 PASSIVE_NO_FETCH = util.symbol('PASSIVE_NO_FETCH')
+"""Symbol indicating that loader callables should not boe fired off.
+   Non-initialized attributes should be initialized to an empty value."""
 
-# fire callables/initialize as needed
 PASSIVE_OFF = False #util.symbol('PASSIVE_OFF')
+"""Symbol indicating that loader callables should be executed."""
 
 INSTRUMENTATION_MANAGER = '__sa_instrumentation_manager__'
 """Attribute, elects custom instrumentation when present on a mapped class.
@@ -1293,8 +1293,10 @@ class _ClassInstrumentationAdapter(ClassManager):
         return self._get_dict
 
 class History(tuple):
-    """A 3-tuple of added, unchanged and deleted values.
-
+    """A 3-tuple of added, unchanged and deleted values,
+    representing the changes which have occured on an instrumented
+    attribute.
+    
     Each tuple member is an iterable sequence.
 
     """
@@ -1302,9 +1304,18 @@ class History(tuple):
     __slots__ = ()
 
     added = property(itemgetter(0))
+    """Return the collection of items added to the attribute (the first tuple
+    element)."""
+    
     unchanged = property(itemgetter(1))
+    """Return the collection of items that have not changed on the attribute
+    (the second tuple element)."""
+    
+    
     deleted = property(itemgetter(2))
-
+    """Return the collection of items that have been removed from the
+    attribute (the third tuple element)."""
+    
     def __new__(cls, added, unchanged, deleted):
         return tuple.__new__(cls, (added, unchanged, deleted))
     
@@ -1312,25 +1323,38 @@ class History(tuple):
         return self != HISTORY_BLANK
     
     def empty(self):
+        """Return True if this :class:`History` has no changes
+        and no existing, unchanged state.
+        
+        """
+        
         return not bool(
                         (self.added or self.deleted)
                         or self.unchanged and self.unchanged != [None]
                     ) 
         
     def sum(self):
+        """Return a collection of added + unchanged + deleted."""
+        
         return (self.added or []) +\
                 (self.unchanged or []) +\
                 (self.deleted or [])
     
     def non_deleted(self):
+        """Return a collection of added + unchanged."""
+        
         return (self.added or []) +\
                 (self.unchanged or [])
     
     def non_added(self):
+        """Return a collection of unchanged + deleted."""
+        
         return (self.unchanged or []) +\
                 (self.deleted or [])
     
     def has_changes(self):
+        """Return True if this :class:`History` has changes."""
+        
         return bool(self.added or self.deleted)
         
     def as_state(self):
@@ -1391,11 +1415,19 @@ class History(tuple):
 HISTORY_BLANK = History(None, None, None)
 
 def get_history(obj, key, **kwargs):
-    """Return a History record for the given object and attribute key.
+    """Return a :class:`.History` record for the given object 
+    and attribute key.
     
-    obj is an instrumented object instance.  An InstanceState
-    is accepted directly for backwards compatibility but 
-    this usage is deprecated.
+    :param obj: an object whose class is instrumented by the
+      attributes package.  
+    
+    :param key: string attribute name.
+    
+    :param kwargs: Optional keyword arguments currently
+      include the ``passive`` flag, which indicates if the attribute should be
+      loaded from the database if not already present (:attr:`PASSIVE_NO_FETCH`), and
+      if the attribute should be not initialized to a blank value otherwise
+      (:attr:`PASSIVE_NO_INITIALIZE`). Default is :attr:`PASSIVE_OFF`.
     
     """
     return get_state_history(instance_state(obj), key, **kwargs)
diff --git a/lib/sqlalchemy/schema.py b/lib/sqlalchemy/schema.py
index b01d815a9..98472f9f1 100644
--- a/lib/sqlalchemy/schema.py
+++ b/lib/sqlalchemy/schema.py
@@ -118,7 +118,7 @@ class Table(SchemaItem, expression.TableClause):
     :param \*args: Additional positional arguments are used primarily
         to add the list of :class:`Column` objects contained within this
         table. Similar to the style of a CREATE TABLE statement, other
-        :class:`SchemaItem` constructs may be added here, including
+        :class:`.SchemaItem` constructs may be added here, including
         :class:`PrimaryKeyConstraint`, and :class:`ForeignKeyConstraint`.
         
     :param autoload: Defaults to False: the Columns for this table should 
@@ -526,7 +526,7 @@ class Column(SchemaItem, expression.ColumnClause):
           may not function in all cases.
 
         :param \*args: Additional positional arguments include various 
-          :class:`SchemaItem` derived constructs which will be applied 
+          :class:`.SchemaItem` derived constructs which will be applied 
           as options to the column.  These include instances of 
           :class:`Constraint`, :class:`ForeignKey`, :class:`ColumnDefault`, 
           and :class:`Sequence`.  In some cases an equivalent keyword 
diff --git a/lib/sqlalchemy/types.py b/lib/sqlalchemy/types.py
index a3769dcd6..af7ef22e6 100644
--- a/lib/sqlalchemy/types.py
+++ b/lib/sqlalchemy/types.py
@@ -75,12 +75,14 @@ class AbstractType(Visitable):
 
         This allows systems like the ORM to know if a column value can
         be considered 'not changed' by comparing the identity of
-        objects alone.
-
-        Use the :class:`MutableType` mixin or override this method to
-        return True in custom types that hold mutable values such as
-        ``dict``, ``list`` and custom objects.
-
+        objects alone.  Values such as dicts, lists which
+        are serialized into strings are examples of "mutable" 
+        column structures.
+        
+        When this method is overridden, :meth:`copy_value` should
+        also be supplied.   The :class:`.MutableType` mixin
+        is recommended as a helper.
+        
         """
         return False
 
@@ -486,13 +488,18 @@ class TypeDecorator(AbstractType):
 
     def is_mutable(self):
         """Return True if the target Python type is 'mutable'.
+
+        This allows systems like the ORM to know if a column value can
+        be considered 'not changed' by comparing the identity of
+        objects alone.  Values such as dicts, lists which
+        are serialized into strings are examples of "mutable" 
+        column structures.
         
         When this method is overridden, :meth:`copy_value` should
         also be supplied.   The :class:`.MutableType` mixin
         is recommended as a helper.
         
         """
-
         return self.impl.is_mutable()
 
     def _adapt_expression(self, op, othertype):
@@ -572,6 +579,9 @@ class MutableType(object):
     def is_mutable(self):
         """Return True if the target Python type is 'mutable'.
         
+        For :class:`.MutableType`, this method is set to 
+        return ``True``.
+        
         """
         return True
 
@@ -1610,6 +1620,13 @@ class PickleType(MutableType, TypeDecorator):
             return x == y
 
     def is_mutable(self):
+        """Return True if the target Python type is 'mutable'.
+        
+        When this method is overridden, :meth:`copy_value` should
+        also be supplied.   The :class:`.MutableType` mixin
+        is recommended as a helper.
+        
+        """
         return self.mutable