migrated (most) docstrings to pep-257 format, docstring generator using straight <pre> + trim() func

for now.  applies most of [ticket:214], compliemnts of Lele Gaifax

3 files changed, 73 insertions, 31 deletions

diff --git a/lib/sqlalchemy/mods/legacy_session.py b/lib/sqlalchemy/mods/legacy_session.py
index a28cd3dac..e21a5634b 100644
--- a/lib/sqlalchemy/mods/legacy_session.py
+++ b/lib/sqlalchemy/mods/legacy_session.py
@@ -1,4 +1,4 @@
-"""a plugin that emulates 0.1 Session behavior."""
+"""A plugin that emulates 0.1 Session behavior."""
 
 import sqlalchemy.orm.objectstore as objectstore
 import sqlalchemy.orm.unitofwork as unitofwork
@@ -14,6 +14,7 @@ class LegacySession(objectstore.Session):
         self.begin_count = 0
         self.nest_on = util.to_list(nest_on)
         self.__pushed_count = 0
+
     def was_pushed(self):
         if self.nest_on is None:
             return
@@ -21,6 +22,7 @@ class LegacySession(objectstore.Session):
         if self.__pushed_count == 1:
             for n in self.nest_on:
                 n.push_session()
+
     def was_popped(self):
         if self.nest_on is None or self.__pushed_count == 0:
             return
@@ -28,46 +30,74 @@ class LegacySession(objectstore.Session):
         if self.__pushed_count == 0:
             for n in self.nest_on:
                 n.pop_session()
+
     class SessionTrans(object):
-        """returned by Session.begin(), denotes a transactionalized UnitOfWork instance.
-        call commit() on this to commit the transaction."""
+        """Returned by ``Session.begin()``, denotes a
+        transactionalized UnitOfWork instance.  Call ``commit()`
+        on this to commit the transaction.
+        """
+
         def __init__(self, parent, uow, isactive):
             self.__parent = parent
             self.__isactive = isactive
             self.__uow = uow
+
         isactive = property(lambda s:s.__isactive, doc="True if this SessionTrans is the 'active' transaction marker, else its a no-op.")
-        parent = property(lambda s:s.__parent, doc="returns the parent Session of this SessionTrans object.")
-        uow = property(lambda s:s.__uow, doc="returns the parent UnitOfWork corresponding to this transaction.")
+        parent = property(lambda s:s.__parent, doc="The parent Session of this SessionTrans object.")
+        uow = property(lambda s:s.__uow, doc="The parent UnitOfWork corresponding to this transaction.")
+
         def begin(self):
-            """calls begin() on the underlying Session object, returning a new no-op SessionTrans object."""
+            """Call ``begin()`` on the underlying ``Session`` object,
+            returning a new no-op ``SessionTrans`` object.
+            """
+
             if self.parent.uow is not self.uow:
                 raise InvalidRequestError("This SessionTrans is no longer valid")
             return self.parent.begin()
+
         def commit(self):
-            """commits the transaction noted by this SessionTrans object."""
+            """Commit the transaction noted by this ``SessionTrans`` object."""
+
             self.__parent._trans_commit(self)
             self.__isactive = False
+
         def rollback(self):
-            """rolls back the current UnitOfWork transaction, in the case that begin()
-            has been called.  The changes logged since the begin() call are discarded."""
+            """Roll back the current UnitOfWork transaction, in the
+            case that ``begin()`` has been called.
+
+            The changes logged since the begin() call are discarded.
+            """
+
             self.__parent._trans_rollback(self)
             self.__isactive = False
+
     def begin(self):
-        """begins a new UnitOfWork transaction and returns a tranasaction-holding
-        object.  commit() or rollback() should be called on the returned object.
-        commit() on the Session will do nothing while a transaction is pending, and further
-        calls to begin() will return no-op transactional objects."""
+        """Begin a new UnitOfWork transaction and return a
+        transaction-holding object.
+
+        ``commit()`` or ``rollback()`` should be called on the returned object.
+
+        ``commit()`` on the ``Session`` will do nothing while a
+        transaction is pending, and further calls to ``begin()`` will
+        return no-op transactional objects.
+        """
+
         if self.parent_uow is not None:
             return LegacySession.SessionTrans(self, self.uow, False)
         self.parent_uow = self.uow
         self.uow = unitofwork.UnitOfWork(identity_map = self.uow.identity_map)
         return LegacySession.SessionTrans(self, self.uow, True)
+
     def commit(self, *objects):
-        """commits the current UnitOfWork transaction.  called with
-        no arguments, this is only used
-        for "implicit" transactions when there was no begin().
-        if individual objects are submitted, then only those objects are committed, and the 
-        begin/commit cycle is not affected."""
+        """Commit the current UnitOfWork transaction.
+
+        Called with no arguments, this is only used for *implicit*
+        transactions when there was no ``begin()``.
+
+        If individual objects are submitted, then only those objects
+        are committed, and the begin/commit cycle is not affected.
+        """
+
         # if an object list is given, commit just those but dont
         # change begin/commit status
         if len(objects):
@@ -76,6 +106,7 @@ class LegacySession(objectstore.Session):
             return
         if self.parent_uow is None:
             self._commit_uow()
+
     def _trans_commit(self, trans):
         if trans.uow is self.uow and trans.isactive:
             try:
@@ -83,10 +114,12 @@ class LegacySession(objectstore.Session):
             finally:
                 self.uow = self.parent_uow
                 self.parent_uow = None
+
     def _trans_rollback(self, trans):
         if trans.uow is self.uow:
             self.uow = self.parent_uow
             self.parent_uow = None
+
     def _commit_uow(self, *obj):
         self.was_pushed()
         try:
@@ -95,11 +128,13 @@ class LegacySession(objectstore.Session):
             self.was_popped()
 
 def begin():
-    """deprecated.  use s = Session(new_imap=False)."""
+    """Deprecated. Use ``s = Session(new_imap=False)``."""
+
     return objectstore.get_session().begin()
 
 def commit(*obj):
-    """deprecated; use flush(*obj)"""
+    """Deprecated. Use ``flush(*obj)``."""
+
     objectstore.get_session().flush(*obj)
 
 def uow():
@@ -137,4 +172,5 @@ def install_plugin():
     objectstore.push_session = push_session
     objectstore.pop_session = pop_session
     objectstore.using_session = using_session
+
 install_plugin()
diff --git a/lib/sqlalchemy/mods/selectresults.py b/lib/sqlalchemy/mods/selectresults.py
index 51ed6e4a5..ac8de9b06 100644
--- a/lib/sqlalchemy/mods/selectresults.py
+++ b/lib/sqlalchemy/mods/selectresults.py
@@ -1,7 +1,7 @@
 from sqlalchemy.ext.selectresults import *
 from sqlalchemy.orm.mapper import global_extensions
 
-
 def install_plugin():
     global_extensions.append(SelectResultsExt)
+
 install_plugin()
diff --git a/lib/sqlalchemy/mods/threadlocal.py b/lib/sqlalchemy/mods/threadlocal.py
index 6fce85954..c8043bc62 100644
--- a/lib/sqlalchemy/mods/threadlocal.py
+++ b/lib/sqlalchemy/mods/threadlocal.py
@@ -1,15 +1,22 @@
-"""this plugin installs thread-local behavior at the Engine and Session level.
+"""This plugin installs thread-local behavior at the ``Engine`` and ``Session`` level.
 
-The default Engine strategy will be "threadlocal", producing TLocalEngine instances for create_engine by default.
-With this engine, connect() method will return the same connection on the same thread, if it is already checked out
-from the pool.  this greatly helps functions that call multiple statements to be able to easily use just one connection
-without explicit "close" statements on result handles.
+The default ``Engine`` strategy will be *threadlocal*, producing
+``TLocalEngine`` instances for create_engine by default.
 
-on the Session side, module-level methods will be installed within the objectstore module, such as flush(), delete(), etc.
-which call this method on the thread-local session.
+With this engine, ``connect()`` method will return the same connection
+on the same thread, if it is already checked out from the pool.  This
+greatly helps functions that call multiple statements to be able to
+easily use just one connection without explicit ``close`` statements
+on result handles.
 
-Note: this mod creates a global, thread-local session context named sqlalchemy.objectstore. All mappers created
-while this mod is installed will reference this global context when creating new mapped object instances.
+On the ``Session`` side, module-level methods will be installed within
+the objectstore module, such as ``flush()``, ``delete()``, etc.  which
+call this method on the thread-local session.
+
+Note: this mod creates a global, thread-local session context named
+``sqlalchemy.objectstore``. All mappers created while this mod is
+installed will reference this global context when creating new mapped
+object instances.
 """
 
 from sqlalchemy import util, engine, mapper
@@ -20,7 +27,6 @@ from sqlalchemy.orm.session import Session
 import sqlalchemy
 import sys, types
 
-
 __all__ = ['Objectstore', 'assign_mapper']
 
 class Objectstore(object):