integrated docutils formatting into generated documentation;

restructuredtext fixes throughout docstrings

8 files changed, 97 insertions, 75 deletions

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index f79167abc..4c9595437 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -783,7 +783,7 @@ class ResultProxy(object):
       col3 = row[mytable.c.mycol] # access via Column object.
 
     ResultProxy also contains a map of TypeEngine objects and will
-    invoke the appropriate ``convert_result_value()` method before
+    invoke the appropriate ``convert_result_value()`` method before
     returning columns, as well as the ExecutionContext corresponding
     to the statement execution.  It provides several methods for which
     to obtain information from the underlying ExecutionContext.
diff --git a/lib/sqlalchemy/ext/selectresults.py b/lib/sqlalchemy/ext/selectresults.py
index f498e26b0..ec3ad8026 100644
--- a/lib/sqlalchemy/ext/selectresults.py
+++ b/lib/sqlalchemy/ext/selectresults.py
@@ -70,7 +70,7 @@ class SelectResults(object):
         return self._col_aggregate(col, sql.func.max)
 
     def sum(self, col):
-        """Execute the SQL ``sum``() function against the given column."""
+        """Execute the SQL ``sum()`` function against the given column."""
 
         return self._col_aggregate(col, sql.func.sum)
 
@@ -155,11 +155,12 @@ class SelectResults(object):
         return new
 
     def outerjoin_to(self, prop):
-        """Outer join the table of this ``SelectResults`` to the table located against the given property name.
+        """Outer join the table of this ``SelectResults`` to the 
+        table located against the given property name.
 
         Subsequent calls to join_to or outerjoin_to will join against
-        the rightmost table located from the previous ``join_to` or
-        `outerjoin_to` call, searching for the property starting with
+        the rightmost table located from the previous ``join_to`` or
+        ``outerjoin_to`` call, searching for the property starting with
         the rightmost mapper last located.
         """
 
diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index 4c87c4bdc..48b69dadf 100644
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -76,7 +76,7 @@ def synonym(name, proxy=False):
 def compile_mappers():
     """Compile all mappers that have been defined.
 
-    This is equivalent to calling ``compile()` on any individual mapper.
+    This is equivalent to calling ``compile()`` on any individual mapper.
     """
 
     if not len(mapper_registry):
diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py
index 74dd58a3f..ae8333843 100644
--- a/lib/sqlalchemy/orm/mapper.py
+++ b/lib/sqlalchemy/orm/mapper.py
@@ -65,7 +65,7 @@ class Mapper(object):
         All arguments may be sent to the ``sqlalchemy.orm.mapper()``
         function where they are passed through to here.
 
-        class_
+        class\_
           The class to be mapped.
 
         local_table
@@ -1349,12 +1349,13 @@ class Mapper(object):
           The lead object instance.  child items will be processed per
           the relations defined for this object's mapper.
 
-        callable_
+        callable\_
           The callable function.
 
         recursive
           Used by the function for internal context during recursive
           calls, leave as None.
+          
         """
 
         if recursive is None:
@@ -1597,7 +1598,7 @@ class MapperExtension(object):
         row
           The result row from the database
 
-        class_
+        class\_
           The class we are mapping.
         """
 
@@ -1803,8 +1804,15 @@ def has_mapper(object):
     return hasattr(object, '_entity_name')
 
 def object_mapper(object, raiseerror=True):
-    """Given an object, return the primary Mapper associated with the
-    object instance.
+    """Given an object, return the primary Mapper associated with the object instance.
+    
+        object
+            The object instance.
+            
+        raiseerror
+            Defaults to True: raise an ``InvalidRequestError`` if no mapper can
+            be located.  If False, return None.
+            
     """
 
     try:
@@ -1817,8 +1825,9 @@ def object_mapper(object, raiseerror=True):
     return mapper.compile()
 
 def class_mapper(class_, entity_name=None, compile=True):
-    """Given a ClassKey, return the primary Mapper associated with the
-    key.
+    """Given a class and optional entity_name, return the primary Mapper associated with the key.
+    
+    If no mapper can be located, raises ``InvalidRequestError``.
     """
 
     try:
diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index fa96798fe..5fd0b7009 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -139,26 +139,29 @@ class Query(object):
         """Return an array of object instances based on the given
         clauses and key/value criterion.
 
-        `*args` is a list of zero or more ``ClauseElements`` which will be
-        connected by ``AND`` operators.
+        \*args
+            a list of zero or more ``ClauseElements`` which will be
+            connected by ``AND`` operators.
 
-        `**params` is a set of zero or more key/value parameters which
-        are converted into ``ClauseElements``.  the keys are mapped to
-        property or column names mapped by this mapper's Table, and
-        the values are coerced into a ``WHERE`` clause separated by
-        ``AND`` operators.  If the local property/column names dont
-        contain the key, a search will be performed against this
-        mapper's immediate list of relations as well, forming the
-        appropriate join conditions if a matching property is located.
+        \**params 
+            a set of zero or more key/value parameters which
+            are converted into ``ClauseElements``.  the keys are mapped to
+            property or column names mapped by this mapper's Table, and
+            the values are coerced into a ``WHERE`` clause separated by
+            ``AND`` operators.  If the local property/column names dont
+            contain the key, a search will be performed against this
+            mapper's immediate list of relations as well, forming the
+            appropriate join conditions if a matching property is located.
 
-        if the located property is a column-based property, the comparison
-        value should be a scalar with an appropriate type.  If the 
-        property is a relationship-bound property, the comparison value
-        should be an instance of the related class.
+            if the located property is a column-based property, the comparison
+            value should be a scalar with an appropriate type.  If the 
+            property is a relationship-bound property, the comparison value
+            should be an instance of the related class.
 
-        E.g.::
+            E.g.::
+
+              result = usermapper.select_by(user_name = 'fred')
 
-          result = usermapper.select_by(user_name = 'fred')
         """
 
         ret = self.extension.select_by(self, *args, **params)
@@ -502,7 +505,7 @@ class Query(object):
         return self._col_aggregate(col, sql.func.max)
 
     def sum(self, col):
-        """Execute the SQL ``sum``() function against the given column."""
+        """Execute the SQL ``sum()`` function against the given column."""
 
         return self._col_aggregate(col, sql.func.sum)
 
@@ -658,20 +661,20 @@ class Query(object):
         """Return a list of mapped instances corresponding to the rows
         in a given *cursor* (i.e. ``ResultProxy``).
         
-        *mappers_or_columns is an optional list containing one or more of
+        \*mappers_or_columns is an optional list containing one or more of
         classes, mappers, strings or sql.ColumnElements which will be
         applied to each row and added horizontally to the result set,
         which becomes a list of tuples. The first element in each tuple
         is the usual result based on the mapper represented by this
         ``Query``. Each additional element in the tuple corresponds to an
-        entry in the *mappers_or_columns list.
+        entry in the \*mappers_or_columns list.
         
-        For each element in *mappers_or_columns, if the element is 
+        For each element in \*mappers_or_columns, if the element is 
         a mapper or mapped class, an additional class instance will be 
         present in the tuple.  If the element is a string or sql.ColumnElement, 
         the corresponding result column from each row will be present in the tuple.
         
-        Note that when *mappers_or_columns is present, "uniquing" for the result set
+        Note that when \*mappers_or_columns is present, "uniquing" for the result set
         is *disabled*, so that the resulting tuples contain entities as they actually
         correspond.  this indicates that multiple results may be present if this 
         option is used.
@@ -923,7 +926,7 @@ class SelectionContext(OperationContext):
     state among all the Mappers and MapperProperty objects used in a
     load operation.
 
-    SelectionContext contains these attributes::
+    SelectionContext contains these attributes:
 
     mapper
       The Mapper which originated the instances() call.
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index c85b356b3..72a1c4c85 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -139,8 +139,7 @@ class Session(object):
             return self.transaction
 
     def connect(self, mapper=None, **kwargs):
-        """Return a unique connection corresponding to the given
-        mapper.
+        """Return a unique connection corresponding to the given mapper.
 
         This connection will not be part of any pre-existing
         transactional context.
@@ -447,21 +446,29 @@ class Session(object):
         return merged
 
     def identity_key(self, *args, **kwargs):
-        """Get an identity key
+        """Get an identity key.
 
         Valid call signatures:
 
-        identity_key(class_, ident, entity_name=None)
-            class_ - mapped class
-            ident - primary key, if the key is composite this is a tuple
-            entity_name - optional entity name. May be given as a
-                positional arg or as a keyword arg.
-
-        identity_key(instance=instance)
-            instance - object instance (must be given as a keyword arg)
-
-        identity_key(row=row, class=class_, entity_name=None)
-            row - result proxy row (must be given as a keyword arg)
+            identity_key(class\_, ident, entity_name=None)
+                class\_
+                    mapped class
+                
+                ident
+                    primary key, if the key is composite this is a tuple
+                
+                entity_name
+                    optional entity name. May be given as a
+                    positional arg or as a keyword arg.
+
+            identity_key(instance=instance)
+                instance
+                    object instance (must be given as a keyword arg)
+
+            identity_key(row=row, class=class\_, entity_name=None)
+                row
+                    result proxy row (must be given as a keyword arg)
+            
         """
         if args:
             kw = {}
diff --git a/lib/sqlalchemy/schema.py b/lib/sqlalchemy/schema.py
index 443d48ee5..168a0f90f 100644
--- a/lib/sqlalchemy/schema.py
+++ b/lib/sqlalchemy/schema.py
@@ -217,10 +217,10 @@ class Table(SchemaItem, sql.TableClause):
           Further tables constructed with the same name/schema
           combination will return the same Table instance.
 
-        *args
+        \*args
           Should contain a listing of the Column objects for this table.
 
-        **kwargs
+        \**kwargs
           options include:
 
           schema
@@ -413,11 +413,11 @@ class Column(SchemaItem, sql._ColumnClause):
           ForeignKey, the type can also be None, in which case the
           type assigned will be that of the referenced column.
 
-        *args
+        \*args
           Constraint, ForeignKey, ColumnDefault and Sequence objects
           should be added as list values.
 
-        **kwargs
+        \**kwargs
           Keyword arguments include:
 
           key
@@ -844,8 +844,7 @@ class Sequence(DefaultGenerator):
         return visitor.visit_sequence(self)
 
 class Constraint(SchemaItem):
-    """Represent a table-level ``Constraint`` such as a composite primary
-    key, foreign key, or unique constraint.
+    """Represent a table-level ``Constraint`` such as a composite primary key, foreign key, or unique constraint.
 
     Implements a hybrid of dict/setlike behavior with regards to the
     list of underying columns.
@@ -991,15 +990,16 @@ class Index(SchemaItem):
         name
           The name of the index
 
-        *columns
+        \*columns
           Columns to include in the index. All columns must belong to
           the same table, and no column may appear more than once.
 
-        **kwargs
+        \**kwargs
           Keyword arguments include:
 
           unique
             Defaults to True: create a unique index.
+            
         """
 
         self.name = name
@@ -1141,7 +1141,7 @@ class MetaData(SchemaItem):
 
 class BoundMetaData(MetaData):
     """Build upon ``MetaData`` to provide the capability to bind to an
-    ``Engine`` implementation.
+``Engine`` implementation.
     """
 
     def __init__(self, engine_or_url, name=None, **kwargs):
@@ -1155,9 +1155,9 @@ class BoundMetaData(MetaData):
         return True
 
 class DynamicMetaData(MetaData):
-    """Build upon ``MetaData`` to provide the capability to bind to
-    multiple ``Engine`` implementations on a dynamically alterable,
-    thread-local basis.
+    """Build upon ``MetaData`` to provide the capability to bind to 
+multiple ``Engine`` implementations on a dynamically alterable,
+thread-local basis.
     """
 
     def __init__(self, name=None, threadlocal=True, **kwargs):
diff --git a/lib/sqlalchemy/sql.py b/lib/sqlalchemy/sql.py
index d48e385f2..5c472310a 100644
--- a/lib/sqlalchemy/sql.py
+++ b/lib/sqlalchemy/sql.py
@@ -91,7 +91,7 @@ def select(columns=None, whereclause = None, from_obj = [], **kwargs):
       which will extend or override the default ``FROM`` objects
       created from the column list and the whereclause.
 
-    **kwargs
+    \**kwargs
       Additional parameters for the ``Select`` object.
     """
 
@@ -238,7 +238,7 @@ def case(whens, value=None, else_=None):
     value
       Optional for simple case statements.
 
-    else_
+    else\_
       Optional as well, for case defaults.
     """
 
@@ -251,11 +251,12 @@ def case(whens, value=None, else_=None):
     return cc
    
 def cast(clause, totype, **kwargs):
-    """ returns CAST function CAST(clause AS totype) 
-        Use with a sqlalchemy.types.TypeEngine object, i.e
-        cast(table.c.unit_price * table.c.qty, Numeric(10,4))
-         or
-        cast(table.c.timestamp, DATE)
+    """return CAST function CAST(clause AS totype)
+    
+    Use with a sqlalchemy.types.TypeEngine object, i.e
+    ``cast(table.c.unit_price * table.c.qty, Numeric(10,4))``
+    or ``cast(table.c.timestamp, DATE)``
+         
     """
     return _Cast(clause, totype, **kwargs)
 
@@ -351,7 +352,7 @@ def bindparam(key, value=None, type=None, shortname=None, unique=False):
        is called a ``value-based bindparam``.
      
      shortname
-        an ``alias`` for this bind parameter.  usually used to alias the ``key`` and 
+       an ``alias`` for this bind parameter.  usually used to alias the ``key`` and 
        ``label`` of a column, i.e. ``somecolname`` and ``sometable_somecolname``
        
      type
@@ -361,6 +362,7 @@ def bindparam(key, value=None, type=None, shortname=None, unique=False):
      unique
        if True, bind params sharing the same name will have their underlying ``key`` modified
        to a uniquely generated name.  mostly useful with value-based bind params.
+       
     """
 
     if isinstance(key, _ColumnClause):
@@ -580,8 +582,8 @@ class NoColumnVisitor(ClauseVisitor):
     __traverse_options__ = {'column_collections':False}
     
 class Executor(object):
-    """Interface representing a *thing that can produce Compiled objects 
-    and execute them*."""
+    """Interface representing a "thing that can produce Compiled objects 
+    and execute them"."""
 
     def execute_compiled(self, compiled, parameters, echo=None, **kwargs):
         """Execute a Compiled object."""
@@ -714,7 +716,7 @@ class ClauseElement(object):
         
         this is used for visit traversal.
         
-        **kwargs may contain flags that change the collection
+        \**kwargs may contain flags that change the collection
         that is returned, for example to return a subset of items
         in order to cut down on larger traversals, or to return 
         child items from a different context (such as schema-level
@@ -730,7 +732,7 @@ class ClauseElement(object):
 
     def copy_container(self):
         """Return a copy of this ``ClauseElement``, if this
-        ``ClauseElement`` contains other ``ClauseElements`.
+        ``ClauseElement`` contains other ``ClauseElements``.
 
         If this ``ClauseElement`` is not a container, it should return
         self.  This is used to create copies of expression trees that
@@ -996,7 +998,7 @@ class ColumnElement(Selectable, _CompareMixin):
                             doc=\
         """Foreign key accessor.  Points to a list of ForeignKey objects 
         which represents a Foreign Key placed on this column's ultimate
-         ancestor.
+        ancestor.
         """)
     columns = property(lambda self:[self],
                        doc=\
@@ -1739,7 +1741,7 @@ class Join(FromClause):
           columns in the column list of the resulting select.  this will recursively
           apply to any joins directly nested by this one as well.
           
-        **kwargs
+        \**kwargs
           all other kwargs are sent to the underlying ``select()`` function
           
         """