introductory docstring bonanza

16 files changed, 118 insertions, 33 deletions

diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py
index 783d60cf4..ff2245f39 100644
--- a/lib/sqlalchemy/engine/base.py
+++ b/lib/sqlalchemy/engine/base.py
@@ -5,7 +5,7 @@
 # the MIT License: http://www.opensource.org/licenses/mit-license.php
 
 
-"""Basic components for SQL execution and interfacing with DB-API..
+"""Basic components for SQL execution and interfacing with DB-API.
 
 Defines the basic components used to interface DB-API modules with
 higher-level statement-construction, connection-management, execution
diff --git a/lib/sqlalchemy/engine/default.py b/lib/sqlalchemy/engine/default.py
index 38ea903e4..b06f862f7 100644
--- a/lib/sqlalchemy/engine/default.py
+++ b/lib/sqlalchemy/engine/default.py
@@ -4,7 +4,13 @@
 # This module is part of SQLAlchemy and is released under
 # the MIT License: http://www.opensource.org/licenses/mit-license.php
 
-"""Default implementations of per-dialect sqlalchemy.engine classes."""
+"""Default implementations of per-dialect sqlalchemy.engine classes.
+
+These are semi-private implementation classes which are only of importance
+to database dialect authors; dialects will usually use the classes here
+as the base class for their own corresponding classes.
+
+"""
 
 
 import re, random
diff --git a/lib/sqlalchemy/engine/strategies.py b/lib/sqlalchemy/engine/strategies.py
index 175846ff8..d4a0ad841 100644
--- a/lib/sqlalchemy/engine/strategies.py
+++ b/lib/sqlalchemy/engine/strategies.py
@@ -1,10 +1,13 @@
 """Strategies for creating new instances of Engine types.
 
-By default there are two, one which is the "thread-local" strategy,
-one which is the "plain" strategy.
-
-New strategies can be added via constructing a new EngineStrategy
-object which will add itself to the list of available strategies.
+These are semi-private implementation classes which 
+provide the underlying behavior for the "strategy" keyword argument 
+available on [sqlalchemy.engine#create_engine()].
+Current available options are ``plain``, ``threadlocal``, and
+``mock``.
+
+New strategies can be added via new ``EngineStrategy``
+classes.
 """
 
 
diff --git a/lib/sqlalchemy/engine/threadlocal.py b/lib/sqlalchemy/engine/threadlocal.py
index 6122b61b2..d07d8da83 100644
--- a/lib/sqlalchemy/engine/threadlocal.py
+++ b/lib/sqlalchemy/engine/threadlocal.py
@@ -1,12 +1,13 @@
-from sqlalchemy import util
-from sqlalchemy.engine import base
-
 """Provides a thread-local transactional wrapper around the root Engine class.
 
-Provides begin/commit methods on the engine itself which correspond to
-a thread-local transaction.
+The ``threadlocal`` module is invoked when using the ``strategy="threadlocal"`` flag
+with [sqlalchemy.engine#create_engine()].  This module is semi-private and is 
+invoked automatically when the threadlocal engine strategy is used.
 """
 
+from sqlalchemy import util
+from sqlalchemy.engine import base
+
 class TLSession(object):
     def __init__(self, engine):
         self.engine = engine
diff --git a/lib/sqlalchemy/engine/url.py b/lib/sqlalchemy/engine/url.py
index a3487638c..663819f05 100644
--- a/lib/sqlalchemy/engine/url.py
+++ b/lib/sqlalchemy/engine/url.py
@@ -1,4 +1,10 @@
-"""Provides URL facilities for specifying database connections."""
+"""Provides the [sqlalchemy.engine.url#URL] class which encapsulates
+information about a database connection specification.
+
+The URL object is created automatically when [sqlalchemy.engine#create_engine()] is called
+with a string argument; alternatively, the URL is a public-facing construct which can
+be used directly and is also accepted directly by ``create_engine()``.
+"""
 
 import re, cgi, sys, urllib
 from sqlalchemy import exceptions
diff --git a/lib/sqlalchemy/exceptions.py b/lib/sqlalchemy/exceptions.py
index dd0f89737..8338bc554 100644
--- a/lib/sqlalchemy/exceptions.py
+++ b/lib/sqlalchemy/exceptions.py
@@ -3,7 +3,10 @@
 #
 # This module is part of SQLAlchemy and is released under
 # the MIT License: http://www.opensource.org/licenses/mit-license.php
+"""Exceptions used with SQLAlchemy.
 
+The base exception class is SQLAlchemyError.  Exceptions which are raised as a result
+of DBAPI exceptions are all subclasses of [sqlalchemy.exceptions#DBAPIError]."""
 
 class SQLAlchemyError(Exception):
     """Generic error class."""
diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index 7e8d8b8bf..8bff42d2c 100644
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -5,9 +5,10 @@
 # the MIT License: http://www.opensource.org/licenses/mit-license.php
 
 """
-The mapper package provides object-relational functionality, building upon
-the schema and sql packages and tying operations to class properties and
-constructors.
+Functional constructs for ORM configuration.
+
+See the SQLAlchemy object relational tutorial and mapper configuration 
+documentation for an overview of how this module is used.
 """
 
 from sqlalchemy import util as sautil
diff --git a/lib/sqlalchemy/orm/interfaces.py b/lib/sqlalchemy/orm/interfaces.py
index 6119d1c6e..52e39372d 100644
--- a/lib/sqlalchemy/orm/interfaces.py
+++ b/lib/sqlalchemy/orm/interfaces.py
@@ -4,7 +4,15 @@
 # This module is part of SQLAlchemy and is released under
 # the MIT License: http://www.opensource.org/licenses/mit-license.php
 
+"""Semi-private implementation objects which form the basis
+of ORM-mapped attributes, query options and mapper extension.
 
+Defines the [sqlalchemy.orm.interfaces#MapperExtension] class,
+which can be end-user subclassed to add event-based functionality
+to mappers.  The remainder of this module is generally private to the
+ORM.
+
+"""
 from sqlalchemy import util, logging, exceptions
 from sqlalchemy.sql import expression
 class_mapper = None
diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py
index 95d118ee4..2c3d3ea40 100644
--- a/lib/sqlalchemy/orm/mapper.py
+++ b/lib/sqlalchemy/orm/mapper.py
@@ -4,6 +4,13 @@
 # This module is part of SQLAlchemy and is released under
 # the MIT License: http://www.opensource.org/licenses/mit-license.php
 
+"""Defines the [sqlalchemy.orm.mapper#Mapper] class, the central configurational
+unit which associates a class with a database table.
+
+This is a semi-private module; the main configurational API of the ORM is 
+avaiable in [sqlalchemy.orm#].
+"""
+
 import weakref, warnings
 from itertools import chain
 from sqlalchemy import sql, util, exceptions, logging
@@ -37,7 +44,7 @@ class Mapper(object):
     columns.
 
     Instances of this class should be constructed via the
-    ``sqlalchemy.orm.mapper()`` function.
+    [sqlalchemy.orm#mapper()] function.
     """
 
     def __init__(self,
diff --git a/lib/sqlalchemy/orm/properties.py b/lib/sqlalchemy/orm/properties.py
index 441a1d7cd..aadac5122 100644
--- a/lib/sqlalchemy/orm/properties.py
+++ b/lib/sqlalchemy/orm/properties.py
@@ -4,11 +4,10 @@
 # This module is part of SQLAlchemy and is released under
 # the MIT License: http://www.opensource.org/licenses/mit-license.php
 
-"""Defines a set of mapper.MapperProperty objects, including basic
-column properties as well as relationships.  The objects rely upon the
-LoaderStrategy objects in the strategies.py module to handle load
-operations.  PropertyLoader also relies upon the dependency.py module
-to handle flush-time dependency sorting and processing.
+"""MapperProperty implementations.  
+
+This is a private module which defines the behavior of
+invidual ORM-mapped attributes.
 """
 
 from sqlalchemy import sql, schema, util, exceptions, logging
diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 2c9a1d0ff..0d7f76dca 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -4,6 +4,17 @@
 # This module is part of SQLAlchemy and is released under
 # the MIT License: http://www.opensource.org/licenses/mit-license.php
 
+"""Defines the [sqlalchemy.orm.query#Query] class, the central
+construct used by the ORM to construct database queries.
+
+The ``Query`` class should not be confused with the [sqlalchemy.sql.expression#Select]
+class, which defines database SELECT operations at the SQL (non-ORM) level.
+``Query`` differs from ``Select`` in that it returns ORM-mapped objects and interacts
+with an ORM session, whereas the ``Select`` construct interacts directly with the database
+to return iterable result sets.
+"""
+
+
 from sqlalchemy import sql, util, exceptions, logging
 from sqlalchemy.sql import util as sql_util
 from sqlalchemy.sql import expression, visitors, operators
diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index 541590b82..993eba4c5 100644
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -4,6 +4,9 @@
 # This module is part of SQLAlchemy and is released under
 # the MIT License: http://www.opensource.org/licenses/mit-license.php
 
+"""Provides the Session class and related utilities."""
+
+
 import weakref
 from sqlalchemy import util, exceptions, sql, engine
 from sqlalchemy.orm import unitofwork, query, attributes, util as mapperutil
@@ -320,6 +323,9 @@ class Session(object):
 
     def __init__(self, bind=None, autoflush=True, transactional=False, twophase=False, echo_uow=False, weak_identity_map=True, binds=None, extension=None):
         """Construct a new Session.
+        
+        A session is usually constructed using the [sqlalchemy.orm#create_session()] function, 
+        or its more "automated" variant [sqlalchemy.orm#sessionmaker()].
 
         autoflush
             When ``True``, all query operations will issue a ``flush()`` call to this
diff --git a/lib/sqlalchemy/orm/shard.py b/lib/sqlalchemy/orm/shard.py
index 5036bc115..7cf4eb2cc 100644
--- a/lib/sqlalchemy/orm/shard.py
+++ b/lib/sqlalchemy/orm/shard.py
@@ -1,3 +1,10 @@
+"""Defines a rudimental 'horizontal sharding' system which allows a 
+Session to distribute queries and persistence operations across multiple 
+databases.
+
+For a usage example, see the example ``examples/sharding/attribute_shard.py``.
+
+"""
 from sqlalchemy.orm.session import Session
 from sqlalchemy.orm.query import Query
 from sqlalchemy import exceptions, util
diff --git a/lib/sqlalchemy/schema.py b/lib/sqlalchemy/schema.py
index 301acdc2b..dd925a508 100644
--- a/lib/sqlalchemy/schema.py
+++ b/lib/sqlalchemy/schema.py
@@ -6,15 +6,23 @@
 
 """The schema module provides the building blocks for database metadata.
 
-This means all the entities within a SQL database that we might want
-to look at, modify, or create and delete are described by these
-objects, in a database-agnostic way.
-
-A structure of SchemaItems also provides a *visitor* interface which is
-the primary method by which other methods operate upon the schema.
-The SQL package extends this structure with its own clause-specific
-objects as well as the visitor interface, so that the schema package
-*plugs in* to the SQL package.
+Each element within this module describes a database entity 
+which can be created and dropped, or is otherwise part of such an entity.
+Examples include tables, columns, sequences, and indexes.
+
+All entities are subclasses of [sqlalchemy.schema#SchemaItem], and as 
+defined in this module they are intended to be agnostic of any 
+vendor-specific constructs.
+
+A collection of entities are grouped into a unit called [sqlalchemy.schema#MetaData].
+MetaData serves as a logical grouping of schema elements, and can also
+be associated with an actual database connection such that operations 
+involving the contained elements can contact the database as needed.
+
+Two of the elements here also build upon their "syntactic" counterparts,
+which are defined in [sqlalchemy.sql.expression#], specifically [sqlalchemy.schema#Table]
+and [sqlalchemy.schema#Column].  Since these objects are part of the
+SQL expression language, they are usable as components in SQL expressions.
 """
 
 import re, inspect
diff --git a/lib/sqlalchemy/sql/compiler.py b/lib/sqlalchemy/sql/compiler.py
index 247285384..bdcd94688 100644
--- a/lib/sqlalchemy/sql/compiler.py
+++ b/lib/sqlalchemy/sql/compiler.py
@@ -4,7 +4,19 @@
 # This module is part of SQLAlchemy and is released under
 # the MIT License: http://www.opensource.org/licenses/mit-license.php
 
-"""SQL expression compilation routines and DDL implementations."""
+"""Base SQL and DDL compiler implementations.
+
+Provides the [sqlalchemy.sql.compiler#DefaultCompiler] class, which is
+responsible for generating all SQL query strings, as well as 
+[sqlalchemy.sql.compiler#SchemaGenerator] and [sqlalchemy.sql.compiler#SchemaDropper]
+which issue CREATE and DROP DDL for tables, sequences, and indexes.
+
+The elements in this module are used by public-facing constructs like
+[sqlalchemy.sql.expression#ClauseElement] and [sqlalchemy.engine#Engine].
+While dialect authors will want to be familiar with this module for the purpose of
+creating database-specific compilers and schema generators, the module 
+is otherwise internal to SQLAlchemy.
+"""
 
 import string, re
 from sqlalchemy import schema, engine, util, exceptions
diff --git a/lib/sqlalchemy/types.py b/lib/sqlalchemy/types.py
index 44e6ebf60..83e388c4f 100644
--- a/lib/sqlalchemy/types.py
+++ b/lib/sqlalchemy/types.py
@@ -4,7 +4,14 @@
 # This module is part of SQLAlchemy and is released under
 # the MIT License: http://www.opensource.org/licenses/mit-license.php
 
-__all__ = [ 'TypeEngine', 'TypeDecorator',
+"""defines genericized SQL types, each represented by a subclass of 
+[sqlalchemy.types#AbstractType].  Dialects define further subclasses of these 
+types.
+
+For more information see the SQLAlchemy documentation on types.
+
+"""
+__all__ = [ 'TypeEngine', 'TypeDecorator', 'AbstractType',
             'INT', 'CHAR', 'VARCHAR', 'NCHAR', 'TEXT', 'FLOAT',
             'NUMERIC', 'DECIMAL', 'TIMESTAMP', 'DATETIME', 'CLOB', 'BLOB',
             'BOOLEAN', 'SMALLINT', 'DATE', 'TIME',