Commits

Mike Bayer committed 7c09c29

- some doc reorg
- change engine.Connection to _connection_cls so sphinx doesn't get upset
- globally add "." to all :class:`Foo`
- start naming sections that are mostly docstrings "API Documentation - blah blah"
- move some ad-hoc docstrings into "API" sections, there is some inconsistency here
and it may be that we just have to leave it that way
- add "internals" rsts to core, orm, I'm not super thrilled how these look but they are
targeted by some of the public api docs, users typically become aware of these anyway

Comments (0)

Files changed (35)

doc/build/builder/builders.py

         self.layout = builder.config.html_context.get('mako_layout', 'html')
 
         self.lookup = TemplateLookup(directories=builder.config.templates_path,
-            format_exceptions=True, 
+            #format_exceptions=True, 
             imports=[
                 "from builder import util"
             ]

doc/build/core/connections.rst

 that, including the variety of SQL expression constructs described
 in :ref:`sqlexpression_toplevel`.
 
+API Documentation - Connection, Engine, result objects
+=======================================================
+
 .. autoclass:: Connection
    :show-inheritance:
    :members:

doc/build/core/engines.rst

 
 .. _create_engine_args:
 
-Database Engine Options
-========================
+API Documentation - Creating Engines
+=====================================
 
 Keyword options can also be specified to :func:`~sqlalchemy.create_engine`,
 following the string URL as follows:

doc/build/core/expression_api.rst

 .. _expression_api_toplevel:
 
-SQL Statements and Expressions
-==============================
+API Documentation - SQL Statements and Expressions
+==================================================
 
 .. module:: sqlalchemy.sql.expression
 
   :members: where, values
   :show-inheritance:
 
+.. autoclass:: ValuesBase
+    :members:
+    :show-inheritance:
+
 .. _generic_functions:
 
 Generic Functions

doc/build/core/index.rst

 ===============
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 3
 
     tutorial
     expression_api
     serializer
     interfaces
     exceptions
-
+    internals

doc/build/core/internals.rst

+.. _core_internal_toplevel:
+
+Core Internals
+==============
+
+Some key internal constructs are listed here.   
+
+.. currentmodule: sqlalchemy
+
+.. autoclass:: sqlalchemy.engine.base.Compiled
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: sqlalchemy.sql.compiler.DDLCompiler
+    :members:
+    :show-inheritance:
+
+.. autoclass:: sqlalchemy.engine.default.DefaultDialect
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: sqlalchemy.engine.base.Dialect
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: sqlalchemy.engine.default.DefaultExecutionContext
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: sqlalchemy.engine.base.ExecutionContext
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. autoclass:: sqlalchemy.sql.compiler.IdentifierPreparer
+    :members:
+    :show-inheritance:
+
+.. autoclass:: sqlalchemy.sql.compiler.SQLCompiler
+    :members:
+    :show-inheritance:
+

doc/build/core/pooling.rst

 -----------------------------
 
 The :class:`~sqlalchemy.engine.Engine` returned by the
-:func:`~sqlalchemy.create_engine` function in most cases has a :class:`QueuePool`
+:func:`~sqlalchemy.create_engine` function in most cases has a :class:`.QueuePool`
 integrated, pre-configured with reasonable pooling defaults.  If
 you're reading this section to simply enable pooling- congratulations!
 You're already done.
 
-The most common :class:`QueuePool` tuning parameters can be passed
+The most common :class:`.QueuePool` tuning parameters can be passed
 directly to :func:`~sqlalchemy.create_engine` as keyword arguments:
 ``pool_size``, ``max_overflow``, ``pool_recycle`` and
 ``pool_timeout``.  For example::
 upon first connect, upon each new connection, and upon checkout and 
 checkin of connections.   See :class:`.PoolListener` for details.
 
-Builtin Pool Implementations
-----------------------------
+API Documentation - Available Pool Implementations
+---------------------------------------------------
 
 .. autoclass:: sqlalchemy.pool.Pool
 
 connection, a connection proxy object is returned, which delegates its
 calls to a real DB-API connection object.  This connection object is
 stored persistently within a connection pool (an instance of
-:class:`Pool`) that corresponds to the exact connection arguments sent
+:class:`.Pool`) that corresponds to the exact connection arguments sent
 to the ``connect()`` function.
 
 The connection proxy supports all of the methods on the original

doc/build/core/schema.rst

 is *confusing* if:
 
 * Your application talks to multiple database engines at different times,
-  which use the *same* set of :class:`Table` objects. It's usually confusing
-  and unnecessary to begin to create "copies" of :class:`Table` objects just
+  which use the *same* set of :class:`.Table` objects. It's usually confusing
+  and unnecessary to begin to create "copies" of :class:`.Table` objects just
   so that different engines can be used for different operations. An example
   is an application that writes data to a "master" database while performing
   read-only operations from a "read slave". A global
 Specifying the Schema Name
 ---------------------------
 
-Some databases support the concept of multiple schemas.  A :class:`~sqlalchemy.schema.Table` can reference this by specifying the ``schema`` keyword argument::
+Some databases support the concept of multiple schemas. A
+:class:`~sqlalchemy.schema.Table` can reference this by specifying the
+``schema`` keyword argument::
 
     financial_info = Table('financial_info', meta,
         Column('id', Integer, primary_key=True),
         schema='remote_banks'
     )
 
-Within the :class:`~sqlalchemy.schema.MetaData` collection, this table will be identified by the combination of ``financial_info`` and ``remote_banks``.  If another table called ``financial_info`` is referenced without the ``remote_banks`` schema, it will refer to a different :class:`~sqlalchemy.schema.Table`.  :class:`~sqlalchemy.schema.ForeignKey` objects can specify references to columns in this table using the form ``remote_banks.financial_info.id``.
+Within the :class:`~sqlalchemy.schema.MetaData` collection, this table will be
+identified by the combination of ``financial_info`` and ``remote_banks``. If
+another table called ``financial_info`` is referenced without the
+``remote_banks`` schema, it will refer to a different
+:class:`~sqlalchemy.schema.Table`. :class:`~sqlalchemy.schema.ForeignKey`
+objects can specify references to columns in this table using the form
+``remote_banks.financial_info.id``.
 
-The ``schema`` argument should be used for any name qualifiers required, including Oracle's "owner" attribute and similar.  It also can accommodate a dotted name for longer schemes::
+The ``schema`` argument should be used for any name qualifiers required,
+including Oracle's "owner" attribute and similar. It also can accommodate a
+dotted name for longer schemes::
 
     schema="dbo.scott"
 
 Backend-Specific Options
 ------------------------
 
-:class:`~sqlalchemy.schema.Table` supports database-specific options.   For example, MySQL has different table backend types, including "MyISAM" and "InnoDB".   This can be expressed with :class:`~sqlalchemy.schema.Table` using ``mysql_engine``::
+:class:`~sqlalchemy.schema.Table` supports database-specific options. For
+example, MySQL has different table backend types, including "MyISAM" and
+"InnoDB". This can be expressed with :class:`~sqlalchemy.schema.Table` using
+``mysql_engine``::
 
     addresses = Table('engine_email_addresses', meta,
         Column('address_id', Integer, primary_key = True),
         mysql_engine='InnoDB'
     )
 
-Other backends may support table-level options as well - these would be described in the individual documentation sections for each dialect.
+Other backends may support table-level options as well - these would be
+described in the individual documentation sections for each dialect.
 
-Schema API Constructs
----------------------
+API Documenation - Column, Table, MetaData
+-------------------------------------------
 
 .. autoclass:: Column
     :members:
     seq = Sequence('some_sequence')
     nextid = connection.execute(seq)
 
-Default Generation API Constructs
----------------------------------
+API Documentation - Default Objects
+-----------------------------------
 
 .. autoclass:: ColumnDefault
     :show-inheritance:
 tables when used with MySQL. They may also not be supported on other
 databases.
 
-Foreign Key API Constructs
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. autoclass:: ForeignKey
-    :members:
-    :show-inheritance:
-
-.. autoclass:: ForeignKeyConstraint
-    :members:
-    :show-inheritance:
-
 
 UNIQUE Constraint
 -----------------
         UniqueConstraint('col2', 'col3', name='uix_1')
         )
 
-.. autoclass:: UniqueConstraint
-    :show-inheritance:
-
 CHECK Constraint
 ----------------
 
         CONSTRAINT check1  CHECK (col2 > col3 + 5)
     ){stop}
 
-.. autoclass:: CheckConstraint
+API Documentation - Constraints
+--------------------------------
+.. autoclass:: Constraint
     :show-inheritance:
 
-Other Constraint Classes
-------------------------
-
-.. autoclass:: Constraint
+.. autoclass:: CheckConstraint
     :show-inheritance:
 
 .. autoclass:: ColumnCollectionConstraint
     :show-inheritance:
 
+.. autoclass:: ForeignKey
+    :members:
+    :show-inheritance:
+
+.. autoclass:: ForeignKeyConstraint
+    :members:
+    :show-inheritance:
+
 .. autoclass:: PrimaryKeyConstraint
     :show-inheritance:
 
+.. autoclass:: UniqueConstraint
+    :show-inheritance:
+
+
 Indexes
 -------
 
 
 .. _schema_api_ddl:
 
-DDL API
--------
+API Documentation - DDL Expression Constructs
+---------------------------------------------
 
 .. autoclass:: DDLElement
     :members:

doc/build/core/types.rst

 Augmenting Existing Types
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The :class:`TypeDecorator` allows the creation of custom types which
+The :class:`.TypeDecorator` allows the creation of custom types which
 add bind-parameter and result-processing behavior to an existing
 type object.  It is used when additional in-Python marshalling of data
 to and from the database is required.
 Creating New Types
 ~~~~~~~~~~~~~~~~~~
 
-The :class:`UserDefinedType` class is provided as a simple base class
+The :class:`.UserDefinedType` class is provided as a simple base class
 for defining entirely new database types:
 
 .. autoclass:: UserDefinedType

doc/build/orm/collections.rst

 more information and discussion of advanced usage and Python 2.3-compatible
 decoration options.
 
-Collections API
-~~~~~~~~~~~~~~~
+API Documentation - Collections
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. autofunction:: attribute_mapped_collection
 

doc/build/orm/index.rst

 ===============
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 3
 
     tutorial
     mapper_config
     examples
     interfaces
     exceptions
-
+    internals

doc/build/orm/internals.rst

+.. _orm_internal_toplevel:
+
+ORM Internals
+=============
+
+Some key internal constructs are listed here.
+
+.. currentmodule: sqlalchemy.orm
+
+.. autoclass:: sqlalchemy.orm.instrumentation.ClassManager
+    :members:
+    :show-inheritance:
+
+.. autoclass:: sqlalchemy.orm.properties.ColumnProperty
+    :members:
+    :show-inheritance:
+
+.. autoclass:: sqlalchemy.orm.descriptor_props.CompositeProperty
+    :members:
+    :show-inheritance:
+
+.. autoclass:: sqlalchemy.orm.properties.DeferredColumnProperty
+    :members:
+    :show-inheritance:
+
+.. autoclass:: sqlalchemy.orm.state.InstanceState
+    :members:
+    :show-inheritance:
+
+.. autoclass:: sqlalchemy.orm.interfaces.MapperProperty
+    :members:
+    :show-inheritance:
+
+.. autoclass:: sqlalchemy.orm.interfaces.PropComparator
+    :members:
+    :show-inheritance:
+
+.. autoclass:: sqlalchemy.orm.properties.RelationshipProperty
+    :members:
+    :show-inheritance:
+
+.. autoclass:: sqlalchemy.orm.descriptor_props.SynonymProperty
+    :members:
+    :show-inheritance:
+
+.. autoclass:: sqlalchemy.orm.query.QueryContext
+    :members:
+    :show-inheritance:

doc/build/orm/mapper_config.rst

 
 .. _mapper_config_toplevel:
 
+====================
 Mapper Configuration
 ====================
 
 
 
 Customizing Column Properties
-------------------------------
+==============================
 
 The default behavior of :func:`~.orm.mapper` is to assemble all the columns in
 the mapped :class:`.Table` into mapped object attributes. This behavior can be
 modified in several ways, as well as enhanced by SQL expressions.
 
 Mapping a Subset of Table Columns
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------
 
 To reference a subset of columns referenced by a table as mapped attributes,
 use the ``include_properties`` or ``exclude_properties`` arguments. For
 
 
 Attribute Names for Mapped Columns
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------
 
 To change the name of the attribute mapped to a particular column, place the
 :class:`~sqlalchemy.schema.Column` object in the ``properties`` dictionary
 
 
 Mapping Multiple Columns to a Single Attribute
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------------
 
 To place multiple columns which are known to be "synonymous" based on foreign
 key relationship or join condition into the same mapped attribute, put them
 
 For further examples on this particular use case, see :ref:`maptojoin`.
 
-column_property API
-~~~~~~~~~~~~~~~~~~~
+API Documentation - column_property
+------------------------------------
 
 The establishment of a :class:`.Column` on a :func:`.mapper` can be further
 customized using the :func:`.column_property` function, as specified
 .. _deferred:
 
 Deferred Column Loading
-------------------------
+========================
 
 This feature allows particular columns of a table to not be loaded by default,
 instead being loaded later on when first referenced. It is essentially
     query = session.query(Book)
     query.options(undefer_group('photos')).all()
 
+API Documentation - Column Deferral
+-----------------------------------
+
 .. autofunction:: deferred
 
 .. autofunction:: defer
 .. _mapper_sql_expressions:
 
 SQL Expressions as Mapped Attributes
--------------------------------------
+=====================================
 
 Any SQL expression that relates to the primary mapped selectable can be mapped as a 
 read-only attribute which will be bundled into the SELECT emitted
 
 
 Changing Attribute Behavior
-----------------------------
+============================
 
 Simple Validators
-~~~~~~~~~~~~~~~~~~
+-----------------
 
 A quick way to add a "validation" routine to an attribute is to use the
 :func:`~sqlalchemy.orm.validates` decorator. An attribute validator can raise
 .. _synonyms:
 
 Using Descriptors
-~~~~~~~~~~~~~~~~~~
+-----------------
 
 A more comprehensive way to produce modified behavior for an attribute is to
 use descriptors. These are commonly used in Python using the ``property()``
 Read more about Hybrids at :ref:`hybrids_toplevel`.
 
 Synonyms
-~~~~~~~~
+--------
 
 Synonyms are a mapper-level construct that applies expression behavior to a descriptor
 based attribute.  The functionality of synonym is superceded as of 0.7 by hybrid attributes.
 .. _custom_comparators:
 
 Custom Comparators
-~~~~~~~~~~~~~~~~~~~
+------------------
 
 The expressions returned by comparison operations, such as
 ``User.name=='ed'``, can be customized, by implementing an object that
 .. _mapper_composite:
 
 Composite Column Types
------------------------
+=======================
 
 Sets of columns can be associated with a single user-defined datatype. The ORM
 provides a single attribute which represents the group of columns using the
 .. autofunction:: composite
 
 Tracking In-Place Mutations on Composites
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------
 
 As of SQLAlchemy 0.7, in-place changes to an existing composite value are 
 not tracked automatically.  Instead, the composite class needs to provide
 Please see the example in :ref:`mutable_composites`.
 
 Redefining Comparison Operations for Composites
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------------------
 
 The "equals" comparison operation by default produces an AND of all
 corresponding columns equated to one another. This can be changed using
 .. _maptojoin:
 
 Mapping a Class against Multiple Tables
-----------------------------------------
+========================================
 
 Mappers can be constructed against arbitrary relational units (called
 ``Selectables``) as well as plain ``Tables``. For example, The ``join``
 
 
 Mapping a Class against Arbitrary Selects
-------------------------------------------
+=========================================
 
 Similar to mapping against a join, a plain select() object can be used with a mapper as well.  Below, an example select which contains two aggregate functions and a group_by is mapped to a class:
 
 Above, the "customers" table is joined against the "orders" table to produce a full row for each customer row, the total count of related rows in the "orders" table, and the highest price in the "orders" table, grouped against the full set of columns in the "customers" table.  That query is then mapped against the Customer class.  New instances of Customer will contain attributes for each column in the "customers" table as well as an "order_count" and "highest_order" attribute.  Updates to the Customer object will only be reflected in the "customers" table and not the "orders" table.  This is because the primary key columns of the "orders" table are not represented in this mapper and therefore the table is not affected by save or delete operations.
 
 Multiple Mappers for One Class
--------------------------------
+==============================
 
 The first mapper created for a certain class is known as that class's "primary mapper."  Other mappers can be created as well on the "load side" - these are called **secondary mappers**.   This is a mapper that must be constructed with the keyword argument ``non_primary=True``, and represents a load-only mapper.  Objects that are loaded with a secondary mapper will have their save operation processed by the primary mapper.  It is also invalid to add new :func:`~sqlalchemy.orm.relationship` objects to a non-primary mapper. To use this mapper with the Session, specify it to the :class:`~sqlalchemy.orm.session.Session.query` method:
 
 The "non primary mapper" is a rarely needed feature of SQLAlchemy; in most cases, the :class:`~sqlalchemy.orm.query.Query` object can produce any kind of query that's desired.  It's recommended that a straight :class:`~sqlalchemy.orm.query.Query` be used in place of a non-primary mapper unless the mapper approach is absolutely needed.  Current use cases for the "non primary mapper" are when you want to map the class to a particular select statement or view to which additional query criterion can be added, and for when the particular mapped select statement or view is to be placed in a :func:`~sqlalchemy.orm.relationship` of a parent mapper.
 
 Multiple "Persistence" Mappers for One Class
----------------------------------------------
+=============================================
 
 The non_primary mapper defines alternate mappers for the purposes of loading objects.  What if we want the same class to be *persisted* differently, such as to different tables ?   SQLAlchemy
 refers to this as the "entity name" pattern, and in Python one can use a recipe which creates
 anonymous subclasses which are distinctly mapped.  See the recipe at `Entity Name <http://www.sqlalchemy.org/trac/wiki/UsageRecipes/EntityName>`_.
 
 Constructors and Object Initialization
----------------------------------------
+=======================================
 
 Mapping imposes no restrictions or requirements on the constructor (``__init__``) method for the class. You are free to require any arguments for the function
 that you wish, assign attributes to the instance that are unknown to the ORM, and generally do anything else you would normally do when writing a constructor
 
 .. autofunction:: reconstructor
 
-The :func:`mapper` API
-----------------------
+API Documentation - Class Mapping
+=================================
 
 .. autofunction:: mapper
 

doc/build/orm/query.rst

 .. _query_api_toplevel:
 
-Querying
-========
+API Documentation - Querying
+============================
 
 This section provides API documentation for the :class:`.Query` object and related constructs.
 
 
     q = session.query(SomeMappedClass)
 
-Following is the full interface for the :class:`Query` object.
+Following is the full interface for the :class:`.Query` object.
 
 .. autoclass:: sqlalchemy.orm.query.Query
    :members:

doc/build/orm/relationships.rst

 map for objects that may be referencing the one with a
 mutating primary key, not throughout the database.
 
-The :func:`relationship` API
-----------------------------
+API Documentation - Relationships
+----------------------------------
 
 .. autofunction:: relationship
 

doc/build/orm/session.rst

 pair actually commits the transaction, or if the outermost block rolls back,
 everything is rolled back.
 
-The :class:`.Session` object and :func:`.sessionmaker` function
-================================================================
-
-.. autofunction:: sessionmaker
-
-.. autoclass:: sqlalchemy.orm.session.Session
-   :members:
-
 .. _unitofwork_contextual:
 
 Contextual/Thread-local Sessions
 Doing nothing is an option too, if individual controller methods take responsibility
 for ensuring that no transactions remain open after a request ends.
 
-Contextual Session API
------------------------
+API Documentation - Contextual Session
+--------------------------------------
 
 .. autofunction:: sqlalchemy.orm.scoped_session
 
 
 See the "sharding" example: :ref:`examples_sharding`.
 
-Session Utilities
-=================
+API Documentation - Sessions
+============================
+
+Session and sessionmaker()
+---------------------------
+
+.. autofunction:: sessionmaker
+
+.. autoclass:: sqlalchemy.orm.session.Session
+   :members:
+
+Session Utilites
+----------------
 
 .. autofunction:: make_transient
 
 .. autofunction:: object_session
 
 Attribute and State Management Utilities
-========================================
+-----------------------------------------
 
 These functions are provided by the SQLAlchemy attribute
 instrumentation API to provide a detailed interface for dealing
 
 .. function:: instance_state
 
-    Return the :class:`InstanceState` for a given object.
+    Return the :class:`.InstanceState` for a given object.
 
 .. autofunction:: is_instrumented
 
 .. function:: manager_of_class
 
-    Return the :class:`ClassManager` for a given class.
+    Return the :class:`.ClassManager` for a given class.
 
 .. autofunction:: set_attribute
 

lib/sqlalchemy/dialects/mssql/base.py

     from sqlalchemy.dialects.mssql import VARCHAR
     Column('login', VARCHAR(32, collation='Latin1_General_CI_AS'))
 
-When such a column is associated with a :class:`Table`, the
+When such a column is associated with a :class:`.Table`, the
 CREATE TABLE statement for this column will yield::
 
     login VARCHAR(32) COLLATE Latin1_General_CI_AS NULL

lib/sqlalchemy/dialects/sqlite/base.py

 out of the box functionality for translating values between Python `datetime` objects
 and a SQLite-supported format.  SQLAlchemy's own :class:`~sqlalchemy.types.DateTime`
 and related types provide date formatting and parsing functionality when SQlite is used.
-The implementation classes are :class:`DATETIME`, :class:`DATE` and :class:`TIME`.
+The implementation classes are :class:`.DATETIME`, :class:`.DATE` and :class:`.TIME`.
 These types represent dates and times as ISO formatted strings, which also nicely
 support ordering.   There's no reliance on typical "libc" internals for these functions
 so historical dates are fully supported.

lib/sqlalchemy/engine/base.py

      initial connection to the database.
 
     execution_ctx_cls
-      a :class:`ExecutionContext` class used to handle statement execution
+      a :class:`.ExecutionContext` class used to handle statement execution
 
     execute_sequence_format
       either the 'tuple' or 'list' type, depending on what cursor.execute()
     def reflecttable(self, connection, table, include_columns=None):
         """Load table description from the database.
 
-        Given a :class:`~sqlalchemy.engine.Connection` and a
+        Given a :class:`.Connection` and a
         :class:`~sqlalchemy.schema.Table` object, reflect its columns and
         properties from the database.  If include_columns (a list or
         set) is specified, limit the autoload to the given column
         The default implementation uses the 
         :class:`~sqlalchemy.engine.reflection.Inspector` interface to 
         provide the output, building upon the granular table/column/
-        constraint etc. methods of :class:`Dialect`.
+        constraint etc. methods of :class:`.Dialect`.
 
         """
 
     def get_columns(self, connection, table_name, schema=None, **kw):
         """Return information about columns in `table_name`.
 
-        Given a :class:`~sqlalchemy.engine.Connection`, a string
+        Given a :class:`.Connection`, a string
         `table_name`, and an optional string `schema`, return column
         information as a list of dictionaries with these keys:
 
     def get_primary_keys(self, connection, table_name, schema=None, **kw):
         """Return information about primary keys in `table_name`.
 
-        Given a :class:`~sqlalchemy.engine.Connection`, a string
+        Given a :class:`.Connection`, a string
         `table_name`, and an optional string `schema`, return primary
         key information as a list of column names.
 
     def get_foreign_keys(self, connection, table_name, schema=None, **kw):
         """Return information about foreign_keys in `table_name`.
 
-        Given a :class:`~sqlalchemy.engine.Connection`, a string
+        Given a :class:`.Connection`, a string
         `table_name`, and an optional string `schema`, return foreign
         key information as a list of dicts with these keys:
 
     def get_view_definition(self, connection, view_name, schema=None, **kw):
         """Return view definition.
 
-        Given a :class:`~sqlalchemy.engine.Connection`, a string
+        Given a :class:`.Connection`, a string
         `view_name`, and an optional string `schema`, return the view
         definition.
         """
     def get_indexes(self, connection, table_name, schema=None, **kw):
         """Return information about indexes in `table_name`.
 
-        Given a :class:`~sqlalchemy.engine.Connection`, a string
+        Given a :class:`.Connection`, a string
         `table_name` and an optional string `schema`, return index
         information as a list of dictionaries with these keys:
 
     def has_table(self, connection, table_name, schema=None):
         """Check the existence of a particular table in the database.
 
-        Given a :class:`~sqlalchemy.engine.Connection` object and a string
+        Given a :class:`.Connection` object and a string
         `table_name`, return True if the given table (possibly within
         the specified `schema`) exists in the database, False
         otherwise.
     def has_sequence(self, connection, sequence_name, schema=None):
         """Check the existence of a particular sequence in the database.
 
-        Given a :class:`~sqlalchemy.engine.Connection` object and a string
+        Given a :class:`.Connection` object and a string
         `sequence_name`, return True if the given sequence exists in
         the database, False otherwise.
         """
 class Connectable(object):
     """Interface for an object which supports execution of SQL constructs.
 
-    The two implementations of ``Connectable`` are :class:`Connection` and
-    :class:`Engine`.
+    The two implementations of ``Connectable`` are :class:`.Connection` and
+    :class:`.Engine`.
 
     Connectable must also implement the 'dialect' member which references a
-    :class:`Dialect` instance.
+    :class:`.Dialect` instance.
     """
 
     def contextual_connect(self):
         usually an INSERT statement.
         """
 
-        return self.engine.Connection(
+        return self.engine._connection_cls(
                                 self.engine, 
                                 self.__connection, _branch=True)
 
         """ Set non-SQL options for the connection which take effect 
         during execution.
 
-        The method returns a copy of this :class:`Connection` which references
+        The method returns a copy of this :class:`.Connection` which references
         the same underlying DBAPI connection, but also defines the given
         execution options which will take effect for a call to
-        :meth:`execute`. As the new :class:`Connection` references the same
+        :meth:`execute`. As the new :class:`.Connection` references the same
         underlying resource, it is probably best to ensure that the copies
         would be discarded immediately, which is implicit if used as in::
 
         * a textual SQL string
         * any :class:`.ClauseElement` construct that is also
           a subclass of :class:`.Executable`, such as a 
-          :func:`.select` construct
+          :func:`expression.select` construct
         * a :class:`.FunctionElement`, such as that generated
           by :attr:`.func`, will be automatically wrapped in
           a SELECT statement, which is then executed.
     :class:`~sqlalchemy.engine.base.Dialect` together to provide a source 
     of database connectivity and behavior.
 
-    An :class:`Engine` object is instantiated publically using the 
+    An :class:`.Engine` object is instantiated publically using the 
     :func:`~sqlalchemy.create_engine` function.
 
     """
 
     _execution_options = util.immutabledict()
     _has_events = False
-    Connection = Connection
+    _connection_cls = Connection
 
     def __init__(self, pool, dialect, url, 
                         logging_name=None, echo=None, proxy=None,
     dispatch = event.dispatcher(events.ConnectionEvents)
 
     def update_execution_options(self, **opt):
-        """update the execution_options dictionary of this :class:`Engine`.
+        """update the execution_options dictionary of this :class:`.Engine`.
 
         For details on execution_options, see
         :meth:`Connection.execution_options` as well as
         return 'Engine(%s)' % str(self.url)
 
     def dispose(self):
-        """Dispose of the connection pool used by this :class:`Engine`.
+        """Dispose of the connection pool used by this :class:`.Engine`.
 
         A new connection pool is created immediately after the old one has
         been disposed.   This new pool, like all SQLAlchemy connection pools,
 
         """
 
-        return self.Connection(self, **kwargs)
+        return self._connection_cls(self, **kwargs)
 
     def contextual_connect(self, close_with_result=False, **kwargs):
         """Return a :class:`.Connection` object which may be part of some ongoing context.
 
         """
 
-        return self.Connection(self, 
+        return self._connection_cls(self, 
                                     self.pool.connect(), 
                                     close_with_result=close_with_result, 
                                     **kwargs)

lib/sqlalchemy/engine/threadlocal.py

 class TLEngine(base.Engine):
     """An Engine that includes support for thread-local managed transactions."""
 
-    TLConnection = TLConnection
+    _tl_connection_cls = TLConnection
 
     def __init__(self, *args, **kwargs):
         super(TLEngine, self).__init__(*args, **kwargs)
         if connection is None or connection.closed:
             # guards against pool-level reapers, if desired.
             # or not connection.connection.is_valid:
-            connection = self.TLConnection(self, self.pool.connect(), **kw)
+            connection = self._tl_connection_cls(self, self.pool.connect(), **kw)
             self._connections.conn = conn = weakref.ref(connection)
 
         return connection._increment_connect()

lib/sqlalchemy/ext/declarative.py

             firstname + " " + lastname
         )
 
-Correlated subqueries reference the :class:`Column` objects they
+Correlated subqueries reference the :class:`.Column` objects they
 need either from the local class definition or from remote 
 classes::
 
 
 When using :mod:`~sqlalchemy.ext.declarative`, this need is met by
 using a "mixin class". A mixin class is one that isn't mapped to a
-table and doesn't subclass the declarative :class:`Base`. For example::
+table and doesn't subclass the declarative :class:`.Base`. For example::
 
     class MyMixin(object):
 
 parent tables ``a`` and ``b`` respectively.
 
 In the case of the mixin column, it seems that only one
-:class:`Column` object is explicitly created, yet the ultimate 
+:class:`.Column` object is explicitly created, yet the ultimate 
 ``created_at`` column above must exist as a distinct Python object
 for each separate destination class.  To accomplish this, the declarative
-extension creates a **copy** of each :class:`Column` object encountered on 
+extension creates a **copy** of each :class:`.Column` object encountered on 
 a class that is detected as a mixin.
 
 This copy mechanism is limited to simple columns that have no foreign
-keys, as a :class:`ForeignKey` itself contains references to columns
+keys, as a :class:`.ForeignKey` itself contains references to columns
 which can't be properly recreated at this level.  For columns that 
 have foreign keys, as well as for the variety of mapper-level constructs
 that require destination-explicit context, the
 
 Where above, the ``address_id`` class-level callable is executed at the 
 point at which the ``User`` class is constructed, and the declarative
-extension can use the resulting :class:`Column` object as returned by
+extension can use the resulting :class:`.Column` object as returned by
 the method without the need to copy it.
 
 Columns generated by :func:`~.declared_attr` can also be
       cls.__init__ by way of the normal Python semantics.
 
     :param metaclass:
-      Defaults to :class:`DeclarativeMeta`.  A metaclass or __metaclass__
+      Defaults to :class:`.DeclarativeMeta`.  A metaclass or __metaclass__
       compatible callable to use as the meta type of the generated
       declarative base class.
 

lib/sqlalchemy/interfaces.py

 from sqlalchemy import event, util
 
 class PoolListener(object):
-    """Hooks into the lifecycle of connections in a :class:`Pool`.
+    """Hooks into the lifecycle of connections in a :class:`.Pool`.
 
-    .. note:: :class:`PoolListener` is deprecated.   Please
+    .. note:: :class:`.PoolListener` is deprecated.   Please
        refer to :class:`.PoolEvents`.
 
     Usage::
 
     @classmethod
     def _adapt_listener(cls, self, listener):
-        """Adapt a :class:`PoolListener` to individual
+        """Adapt a :class:`.PoolListener` to individual
         :class:`event.Dispatch` events.
 
         """
 class ConnectionProxy(object):
     """Allows interception of statement execution by Connections.
 
-    .. note:: :class:`ConnectionProxy` is deprecated.   Please
-       refer to :class:`.EngineEvents`.
+    .. note:: :class:`.ConnectionProxy` is deprecated.   Please
+       refer to :class:`.ConnectionEvents`.
 
     Either or both of the ``execute()`` and ``cursor_execute()``
     may be implemented to intercept compiled statement and

lib/sqlalchemy/log.py

         return level
 
 def instance_logger(instance, echoflag=None):
-    """create a logger for an instance that implements :class:`Identified`."""
+    """create a logger for an instance that implements :class:`.Identified`."""
 
     if instance.logging_name:
         name = "%s.%s.%s" % (instance.__class__.__module__,

lib/sqlalchemy/orm/__init__.py

     :class:`.ScopedSession`.
 
     :param session_factory: a callable function that produces
-      :class:`Session` instances, such as :func:`sessionmaker`.
+      :class:`.Session` instances, such as :func:`sessionmaker`.
 
     :param scopefunc: Optional "scope" function which would be
       passed to the :class:`.ScopedRegistry`.  If None, the
       :class:`~sqlalchemy.orm.session.Session`.
 
     :param \*\*kwargs: optional, passed through to the
-      :class:`Session` constructor.
+      :class:`.Session` constructor.
 
     :returns: an :class:`~sqlalchemy.orm.session.Session` instance
 
        :func:`relation` prior to version 0.6.
 
     This corresponds to a parent-child or associative table relationship.  The
-    constructed class is an instance of :class:`RelationshipProperty`.
+    constructed class is an instance of :class:`.RelationshipProperty`.
 
     A typical :func:`relationship`::
 
        })
 
     :param argument:
-      a class or :class:`Mapper` instance, representing the target of
+      a class or :class:`.Mapper` instance, representing the target of
       the relationship.
 
     :param secondary:
       :ref:`custom_collections`.
 
     :param comparator_factory:
-      a class which extends :class:`RelationshipProperty.Comparator` which
+      a class which extends :class:`.RelationshipProperty.Comparator` which
       provides custom SQL clause generation for comparison operations.
 
     :param doc:
     """Construct a dynamically-loading mapper property.
 
     This property is similar to :func:`relationship`, except read
-    operations return an active :class:`Query` object which reads from
+    operations return an active :class:`.Query` object which reads from
     the database when accessed.  Items may be appended to the
     attribute via ``append()``, or removed via ``remove()``; changes
     will be persisted to the database during a :meth:`Sesion.flush`.
     here.
 
     :param argument:
-      a class or :class:`Mapper` instance, representing the target of
+      a class or :class:`.Mapper` instance, representing the target of
       the relationship.
 
     :param secondary:
     return (name, kwargs)
 
 def deferred(*columns, **kwargs):
-    """Return a :class:`DeferredColumnProperty`, which indicates this
+    """Return a :class:`.DeferredColumnProperty`, which indicates this
     object attributes should only be loaded from its corresponding
     table column when first accessed.
 
            condition contains no ForeignKey columns, specify the "foreign"
            columns of the join condition in this list. else leave as None.
 
-        :param non_primary: Construct a :class:`Mapper` that will define only
+        :param non_primary: Construct a :class:`.Mapper` that will define only
            the selection of instances, not their persistence. Any number of
            non_primary mappers may be created for a particular class.
 
            that will be used to keep a running version id of mapped entities
            in the database. this is used during save operations to ensure that
            no other thread or process has updated the instance during the
-           lifetime of the entity, else a :class:`StaleDataError` exception is
+           lifetime of the entity, else a :class:`.StaleDataError` exception is
            thrown.
 
         :param version_id_generator: A callable which defines the algorithm

lib/sqlalchemy/orm/attributes.py

         return self != HISTORY_BLANK
 
     def empty(self):
-        """Return True if this :class:`History` has no changes
+        """Return True if this :class:`.History` has no changes
         and no existing, unchanged state.
 
         """
                 (self.deleted or [])
 
     def has_changes(self):
-        """Return True if this :class:`History` has changes."""
+        """Return True if this :class:`.History` has changes."""
 
         return bool(self.added or self.deleted)
 

lib/sqlalchemy/orm/deprecated_interfaces.py

             'bar':relationship(Bar, extension=MyAttrExt())
         })
 
-    Note that the :class:`AttributeExtension` methods
+    Note that the :class:`.AttributeExtension` methods
     :meth:`~.AttributeExtension.append` and
     :meth:`~.AttributeExtension.set` need to return the
     ``value`` parameter. The returned value is used as the

lib/sqlalchemy/orm/descriptor_props.py

 properties = util.importlater('sqlalchemy.orm', 'properties')
 
 class DescriptorProperty(MapperProperty):
-    """:class:`MapperProperty` which proxies access to a 
+    """:class:`.MapperProperty` which proxies access to a 
         user-defined descriptor."""
 
     doc = None
         return str(self.parent.class_.__name__) + "." + self.key
 
 class ConcreteInheritedProperty(DescriptorProperty):
-    """A 'do nothing' :class:`MapperProperty` that disables 
+    """A 'do nothing' :class:`.MapperProperty` that disables 
     an attribute on a concrete subclass that is only present
     on the inherited mapper, not the concrete classes' mapper.
 

lib/sqlalchemy/orm/events.py

         listen(UserContact.phone, 'set', validate_phone, retval=True)
 
     A validation function like the above can also raise an exception
-    such as :class:`ValueError` to halt the operation.
+    such as :class:`.ValueError` to halt the operation.
 
     Several modifiers are available to the :func:`~.event.listen` function.
 

lib/sqlalchemy/orm/properties.py

         Make several attempts to determine if cols are compared using 
         "=" or other comparators (in which case suggest viewonly), 
         columns are present but not part of the expected mappings, columns
-        don't have any :class:`ForeignKey` information on them, or 
+        don't have any :class:`.ForeignKey` information on them, or 
         the ``foreign_keys`` attribute is being used incorrectly.
 
         """

lib/sqlalchemy/orm/query.py

 
     @_generative()
     def populate_existing(self):
-        """Return a :class:`Query` that will expire and refresh all instances 
+        """Return a :class:`.Query` that will expire and refresh all instances 
         as they are loaded, or reused from the current :class:`.Session`.
 
         :meth:`.populate_existing` does not improve behavior when 
     @_generative()
     def with_hint(self, selectable, text, dialect_name='*'):
         """Add an indexing hint for the given entity or selectable to 
-        this :class:`Query`.
+        this :class:`.Query`.
 
         Functionality is passed straight through to 
         :meth:`~sqlalchemy.sql.expression.Select.with_hint`, 
         with the addition that ``selectable`` can be a 
-        :class:`Table`, :class:`Alias`, or ORM entity / mapped class 
+        :class:`.Table`, :class:`.Alias`, or ORM entity / mapped class 
         /etc.
         """
         mapper, selectable, is_aliased_class = _entity_info(selectable)
     @property
     def column_descriptions(self):
         """Return metadata about the columns which would be 
-        returned by this :class:`Query`.
+        returned by this :class:`.Query`.
 
         Format is a list of dictionaries::
 

lib/sqlalchemy/orm/session.py

         To expire individual objects and individual attributes 
         on those objects, use :meth:`Session.expire`.
 
-        The :class:`Session` object's default behavior is to 
+        The :class:`.Session` object's default behavior is to 
         expire all state whenever the :meth:`Session.rollback`
         or :meth:`Session.commit` methods are called, so that new
         state can be loaded for the new transaction.   For this reason,
         To expire all objects in the :class:`.Session` simultaneously,
         use :meth:`Session.expire_all`.
 
-        The :class:`Session` object's default behavior is to 
+        The :class:`.Session` object's default behavior is to 
         expire all state whenever the :meth:`Session.rollback`
         or :meth:`Session.commit` methods are called, so that new
         state can be loaded for the new transaction.   For this reason,

lib/sqlalchemy/pool.py

     :param module: a DB-API 2.0 database module
 
     :param poolclass: the class used by the pool module to provide
-      pooling.  Defaults to :class:`QueuePool`.
+      pooling.  Defaults to :class:`.QueuePool`.
 
     :param \*\*params: will be passed through to *poolclass*
 
     Maintains one connection per each thread, never moving a connection to a
     thread other than the one which it was created in.
 
-    Options are the same as those of :class:`Pool`, as well as:
+    Options are the same as those of :class:`.Pool`, as well as:
 
     :param pool_size: The number of threads in which to maintain connections 
         at once.  Defaults to five.
         return c
 
 class QueuePool(Pool):
-    """A :class:`Pool` that imposes a limit on the number of open connections.
+    """A :class:`.Pool` that imposes a limit on the number of open connections.
 
     :class:`.QueuePool` is the default pooling implementation used for 
     all :class:`.Engine` objects, unless the SQLite dialect is in use.

lib/sqlalchemy/schema.py

     :param name: The name of this table as represented in the database. 
 
         This property, along with the *schema*, indicates the *singleton
-        identity* of this table in relation to its parent :class:`MetaData`.
-        Additional calls to :class:`Table` with the same name, metadata,
-        and schema name will return the same :class:`Table` object.
+        identity* of this table in relation to its parent :class:`.MetaData`.
+        Additional calls to :class:`.Table` with the same name, metadata,
+        and schema name will return the same :class:`.Table` object.
 
         Names which contain no upper case characters
         will be treated as case insensitive names, and will not be quoted
         behavior applies even for databases which standardize upper 
         case names as case insensitive such as Oracle.
 
-    :param metadata: a :class:`MetaData` object which will contain this 
+    :param metadata: a :class:`.MetaData` object which will contain this 
         table.  The metadata is used as a point of association of this table
         with other tables which are referenced via foreign key.  It also
         may be used to associate this table with a particular 
         :class:`~sqlalchemy.engine.base.Connectable`.
 
     :param \*args: Additional positional arguments are used primarily
-        to add the list of :class:`Column` objects contained within this
+        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:`PrimaryKeyConstraint`, and :class:`ForeignKeyConstraint`.
+        :class:`.PrimaryKeyConstraint`, and :class:`.ForeignKeyConstraint`.
 
     :param autoload: Defaults to False: the Columns for this table should 
         be reflected from the database. Usually there will be no Column
                 ])
 
     :param mustexist: When ``True``, indicates that this Table must already 
-        be present in the given :class:`MetaData`` collection.
+        be present in the given :class:`.MetaData`` collection.
 
     :param prefixes:
         A list of strings to insert after CREATE in the CREATE TABLE
         for the engine's database connection. Defaults to ``None``.
 
     :param useexisting: When ``True``, indicates that if this Table is already
-        present in the given :class:`MetaData`, apply further arguments within
-        the constructor to the existing :class:`Table`. If this flag is not
+        present in the given :class:`.MetaData`, apply further arguments within
+        the constructor to the existing :class:`.Table`. If this flag is not
         set, an error is raised when the parameters of an existing
-        :class:`Table` are overwritten.
+        :class:`.Table` are overwritten.
 
     """
 
 
 
     def tometadata(self, metadata, schema=RETAIN_SCHEMA):
-        """Return a copy of this :class:`Table` associated with a different
-        :class:`MetaData`.
+        """Return a copy of this :class:`.Table` associated with a different
+        :class:`.MetaData`.
 
         E.g.::
 
 
           The name field may be omitted at construction time and applied
           later, at any time before the Column is associated with a 
-          :class:`Table`.  This is to support convenient
+          :class:`.Table`.  This is to support convenient
           usage within the :mod:`~sqlalchemy.ext.declarative` extension.
 
         :param type\_: The column's type, indicated using an instance which 
           or specified by keyword.
 
           There is partial support for automatic detection of the 
-          type based on that of a :class:`ForeignKey` associated 
+          type based on that of a :class:`.ForeignKey` associated 
           with this column, if the type is specified as ``None``. 
           However, this feature is not fully implemented and 
           may not function in all cases.
         :param \*args: Additional positional arguments include various 
           :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 
+          :class:`.Constraint`, :class:`.ForeignKey`, :class:`.ColumnDefault`, 
+          and :class:`.Sequence`.  In some cases an equivalent keyword 
           argument is available such as ``server_default``, ``default``
           and ``unique``.
 
             :class:`~sqlalchemy.sql.expression.ClauseElement` representing the
             *default value* for this column, which will be invoked upon insert
             if this column is otherwise not specified in the VALUES clause of
-            the insert. This is a shortcut to using :class:`ColumnDefault` as
+            the insert. This is a shortcut to using :class:`.ColumnDefault` as
             a positional argument.
 
             Contrast this argument to ``server_default`` which creates a 
             comments (a future attribute 'comment' will achieve that).
 
         :param key: An optional string identifier which will identify this
-            ``Column`` object on the :class:`Table`. When a key is provided,
+            ``Column`` object on the :class:`.Table`. When a key is provided,
             this is the only identifier referencing the ``Column`` within the
             application, including ORM attribute mapping; the ``name`` field
             is used only when rendering SQL.
 
         :param index: When ``True``, indicates that the column is indexed.
-            This is a shortcut for using a :class:`Index` construct on the
+            This is a shortcut for using a :class:`.Index` construct on the
             table. To specify indexes with explicit names or indexes that
-            contain multiple columns, use the :class:`Index` construct
+            contain multiple columns, use the :class:`.Index` construct
             instead.
 
         :param info: A dictionary which defaults to ``{}``. A space to store
             default value to be applied to the column within UPDATE
             statements, which wil be invoked upon update if this column is not
             present in the SET clause of the update. This is a shortcut to
-            using :class:`ColumnDefault` as a positional argument with
+            using :class:`.ColumnDefault` as a positional argument with
             ``for_update=True``.
 
         :param primary_key: If ``True``, marks this column as a primary key
             column. Multiple columns can have this flag set to specify
             composite primary keys. As an alternative, the primary key of a
-            :class:`Table` can be specified via an explicit
-            :class:`PrimaryKeyConstraint` object.
-
-        :param server_default: A :class:`FetchedValue` instance, str, Unicode
+            :class:`.Table` can be specified via an explicit
+            :class:`.PrimaryKeyConstraint` object.
+
+        :param server_default: A :class:`.FetchedValue` instance, str, Unicode
             or :func:`~sqlalchemy.sql.expression.text` construct representing
             the DDL DEFAULT value for the column.
 
 
                 y DATETIME DEFAULT NOW()
 
-            Strings and text() will be converted into a :class:`DefaultClause`
+            Strings and text() will be converted into a :class:`.DefaultClause`
             object upon initialization.
 
-            Use :class:`FetchedValue` to indicate that an already-existing
+            Use :class:`.FetchedValue` to indicate that an already-existing
             column will generate a default value on the database side which
             will be available to SQLAlchemy for post-fetch after inserts. This
             construct does not specify any DDL and the implementation is left
             to the database, such as via a trigger.
 
-        :param server_onupdate:   A :class:`FetchedValue` instance
+        :param server_onupdate:   A :class:`.FetchedValue` instance
              representing a database-side default generation function. This
              indicates to SQLAlchemy that a newly generated value will be
              available after updates. This construct does not specify any DDL
 
         :param unique: When ``True``, indicates that this column contains a
              unique constraint, or if ``index`` is ``True`` as well, indicates
-             that the :class:`Index` should be created with the unique flag.
+             that the :class:`.Index` should be created with the unique flag.
              To specify multiple columns in the constraint/index or to specify
-             an explicit name, use the :class:`UniqueConstraint` or
-             :class:`Index` constructs explicitly.
+             an explicit name, use the :class:`.UniqueConstraint` or
+             :class:`.Index` constructs explicitly.
 
         """
 
 class ForeignKey(SchemaItem):
     """Defines a dependency between two columns.
 
-    ``ForeignKey`` is specified as an argument to a :class:`Column` object,
+    ``ForeignKey`` is specified as an argument to a :class:`.Column` object,
     e.g.::
 
         t = Table("remote_table", metadata, 
 
     Note that ``ForeignKey`` is only a marker object that defines
     a dependency between two columns.   The actual constraint
-    is in all cases represented by the :class:`ForeignKeyConstraint`
+    is in all cases represented by the :class:`.ForeignKeyConstraint`
     object.   This object will be generated automatically when
-    a ``ForeignKey`` is associated with a :class:`Column` which 
-    in turn is associated with a :class:`Table`.   Conversely,
-    when :class:`ForeignKeyConstraint` is applied to a :class:`Table`,
+    a ``ForeignKey`` is associated with a :class:`.Column` which 
+    in turn is associated with a :class:`.Table`.   Conversely,
+    when :class:`.ForeignKeyConstraint` is applied to a :class:`.Table`,
     ``ForeignKey`` markers are automatically generated to be
-    present on each associated :class:`Column`, which are also
+    present on each associated :class:`.Column`, which are also
     associated with the constraint object.
 
     Note that you cannot define a "composite" foreign key constraint,
     that is a constraint between a grouping of multiple parent/child
     columns, using ``ForeignKey`` objects.   To define this grouping,
-    the :class:`ForeignKeyConstraint` object must be used, and applied
-    to the :class:`Table`.   The associated ``ForeignKey`` objects
+    the :class:`.ForeignKeyConstraint` object must be used, and applied
+    to the :class:`.Table`.   The associated ``ForeignKey`` objects
     are created automatically.
 
     The ``ForeignKey`` objects associated with an individual 
-    :class:`Column` object are available in the `foreign_keys` collection
+    :class:`.Column` object are available in the `foreign_keys` collection
     of that column.
 
     Further examples of foreign key configuration are in
         """
         Construct a column-level FOREIGN KEY.
 
-        The :class:`ForeignKey` object when constructed generates a
-        :class:`ForeignKeyConstraint` which is associated with the parent
-        :class:`Table` object's collection of constraints.
+        The :class:`.ForeignKey` object when constructed generates a
+        :class:`.ForeignKeyConstraint` which is associated with the parent
+        :class:`.Table` object's collection of constraints.
 
         :param column: A single target column for the key relationship. A
-            :class:`Column` object or a column name as a string:
+            :class:`.Column` object or a column name as a string:
             ``tablename.columnkey`` or ``schema.tablename.columnkey``.
             ``columnkey`` is the ``key`` which has been assigned to the column
             (defaults to the column name itself), unless ``link_to_name`` is
             assigned ``key``.
 
         :param use_alter: passed to the underlying
-            :class:`ForeignKeyConstraint` to indicate the constraint should be
+            :class:`.ForeignKeyConstraint` to indicate the constraint should be
             generated/dropped externally from the CREATE TABLE/ DROP TABLE
             statement. See that classes' constructor for details.
 
         return "ForeignKey(%r)" % self._get_colspec()
 
     def copy(self, schema=None):
-        """Produce a copy of this :class:`ForeignKey` object.
-
-        The new :class:`ForeignKey` will not be bound
-        to any :class:`Column`.
+        """Produce a copy of this :class:`.ForeignKey` object.
+
+        The new :class:`.ForeignKey` will not be bound
+        to any :class:`.Column`.
 
         This method is usually used by the internal
-        copy procedures of :class:`Column`, :class:`Table`,
-        and :class:`MetaData`.
-
-        :param schema: The returned :class:`ForeignKey` will
+        copy procedures of :class:`.Column`, :class:`.Table`,
+        and :class:`.MetaData`.
+
+        :param schema: The returned :class:`.ForeignKey` will
           reference the original table and column name, qualified
           by the given string schema name.
 
         return fk
 
     def _get_colspec(self, schema=None):
-        """Return a string based 'column specification' for this :class:`ForeignKey`.
+        """Return a string based 'column specification' for this :class:`.ForeignKey`.
 
         This is usually the equivalent of the string-based "tablename.colname"
         argument first passed to the object's constructor.
     target_fullname = property(_get_colspec)
 
     def references(self, table):
-        """Return True if the given :class:`Table` is referenced by this :class:`ForeignKey`."""
+        """Return True if the given :class:`.Table` is referenced by this :class:`.ForeignKey`."""
 
         return table.corresponding_column(self.column) is not None
 
     def get_referent(self, table):
         """Return the :class:`.Column` in the given :class:`.Table` 
-        referenced by this :class:`ForeignKey`.
-
-        Returns None if this :class:`ForeignKey` does not reference the given
-        :class:`Table`.
+        referenced by this :class:`.ForeignKey`.
+
+        Returns None if this :class:`.ForeignKey` does not reference the given
+        :class:`.Table`.
 
         """
 
     def column(self):
         """Return the target :class:`.Column` referenced by this :class:`.ForeignKey`.
 
-        If this :class:`ForeignKey` was created using a
+        If this :class:`.ForeignKey` was created using a
         string-based target column specification, this
         attribute will on first access initiate a resolution
         process to locate the referenced remote
 
     Defines a single column or composite FOREIGN KEY ... REFERENCES
     constraint. For a no-frills, single column foreign key, adding a
-    :class:`ForeignKey` to the definition of a :class:`Column` is a shorthand
-    equivalent for an unnamed, single column :class:`ForeignKeyConstraint`.
+    :class:`.ForeignKey` to the definition of a :class:`.Column` is a shorthand
+    equivalent for an unnamed, single column :class:`.ForeignKeyConstraint`.
 
     Examples of foreign key configuration are in :ref:`metadata_foreignkeys`.
 
           ALTER TABLE statement issued after the full collection of tables
           have been created, and drop it via an ALTER TABLE statement before
           the full collection of tables are dropped. This is shorthand for the
-          usage of :class:`AddConstraint` and :class:`DropConstraint` applied
+          usage of :class:`.AddConstraint` and :class:`.DropConstraint` applied
           as "after-create" and "before-drop" events on the MetaData object.
           This is normally used to generate/drop constraints on objects that
           are mutually dependent on each other.
         A DDLElement instance can be linked to any number of schema items. 
 
         ``execute_at`` builds on the ``append_ddl_listener`` interface of
-        :class:`MetaData` and :class:`Table` objects.
+        :class:`.MetaData` and :class:`.Table` objects.
 
         Caveat: Creating or dropping a Table in isolation will also trigger
         any DDL set to ``execute_at`` that Table's MetaData.  This may change

lib/sqlalchemy/sql/expression.py

 """Defines the base components of SQL expression trees.
 
 All components are derived from a common base class
-:class:`ClauseElement`.  Common behaviors are organized
+:class:`.ClauseElement`.  Common behaviors are organized
 based on class hierarchies, in some cases via mixins.
 
 All object construction from this package occurs via functions which
-in some cases will construct composite :class:`ClauseElement` structures
-together, and in other cases simply return a single :class:`ClauseElement`
+in some cases will construct composite :class:`.ClauseElement` structures
+together, and in other cases simply return a single :class:`.ClauseElement`
 constructed directly.  The function interface affords a more "DSL-ish"
 feel to constructing SQL expressions and also allows future class
 reorganizations.
 def outerjoin(left, right, onclause=None):
     """Return an ``OUTER JOIN`` clause element.
 
-    The returned object is an instance of :class:`Join`.
+    The returned object is an instance of :class:`.Join`.
 
     Similar functionality is also available via the :func:`outerjoin()`
-    method on any :class:`FromClause`.
+    method on any :class:`.FromClause`.
 
     left
       The left side of the join.
       otherwise.
 
     To chain joins together, use the :func:`join()` or :func:`outerjoin()`
-    methods on the resulting :class:`Join` object.
+    methods on the resulting :class:`.Join` object.
 
     """
     return Join(left, right, onclause, isouter=True)
 def join(left, right, onclause=None, isouter=False):
     """Return a ``JOIN`` clause element (regular inner join).
 
-    The returned object is an instance of :class:`Join`.
+    The returned object is an instance of :class:`.Join`.
 
     Similar functionality is also available via the :func:`join()` method
-    on any :class:`FromClause`.
+    on any :class:`.FromClause`.
 
     left
       The left side of the join.
       otherwise.
 
     To chain joins together, use the :func:`join()` or :func:`outerjoin()`
-    methods on the resulting :class:`Join` object.
+    methods on the resulting :class:`.Join` object.
 
     """
     return Join(left, right, onclause, isouter)
     """Returns a ``SELECT`` clause element.
 
     Similar functionality is also available via the :func:`select()`
-    method on any :class:`FromClause`.
-
-    The returned object is an instance of :class:`Select`.
-
-    All arguments which accept :class:`ClauseElement` arguments also accept
+    method on any :class:`.FromClause`.
+
+    The returned object is an instance of :class:`.Select`.
+
+    All arguments which accept :class:`.ClauseElement` arguments also accept
     string arguments, which will be converted as appropriate into
     either :func:`text()` or :func:`literal_column()` constructs.
 
     :param columns:
-      A list of :class:`ClauseElement` objects, typically
-      :class:`ColumnElement` objects or subclasses, which will form the
+      A list of :class:`.ClauseElement` objects, typically
+      :class:`.ColumnElement` objects or subclasses, which will form the
       columns clause of the resulting statement. For all members which are
-      instances of :class:`Selectable`, the individual :class:`ColumnElement`
-      members of the :class:`Selectable` will be added individually to the
+      instances of :class:`.Selectable`, the individual :class:`.ColumnElement`
+      members of the :class:`.Selectable` will be added individually to the
       columns clause. For example, specifying a
       :class:`~sqlalchemy.schema.Table` instance will result in all the
       contained :class:`~sqlalchemy.schema.Column` objects within to be added
       available on :class:`~sqlalchemy.schema.Table`.
 
     :param whereclause:
-      A :class:`ClauseElement` expression which will be used to form the
+      A :class:`.ClauseElement` expression which will be used to form the
       ``WHERE`` clause.
 
     :param from_obj:
-      A list of :class:`ClauseElement` objects which will be added to the
+      A list of :class:`.ClauseElement` objects which will be added to the
       ``FROM`` clause of the resulting statement. Note that "from" objects are
       automatically located within the columns and whereclause ClauseElements.
       Use this parameter to explicitly specify "from" objects which are not
       automatically locatable. This could include
       :class:`~sqlalchemy.schema.Table` objects that aren't otherwise present,
-      or :class:`Join` objects whose presence will supercede that of the
+      or :class:`.Join` objects whose presence will supercede that of the
       :class:`~sqlalchemy.schema.Table` objects already located in the other
       clauses.
 
       :class:`.ClauseElement` members.
 
     :param correlate=True:
-      indicates that this :class:`Select` object should have its
-      contained :class:`FromClause` elements "correlated" to an enclosing
-      :class:`Select` object.  This means that any :class:`ClauseElement`
-      instance within the "froms" collection of this :class:`Select`
+      indicates that this :class:`.Select` object should have its
+      contained :class:`.FromClause` elements "correlated" to an enclosing
+      :class:`.Select` object.  This means that any :class:`.ClauseElement`
+      instance within the "froms" collection of this :class:`.Select`
       which is also present in the "froms" collection of an
       enclosing select will not be rendered in the ``FROM`` clause
       of this select statement.
       NOWAIT``.
 
     :param group_by:
-      a list of :class:`ClauseElement` objects which will comprise the
+      a list of :class:`.ClauseElement` objects which will comprise the
       ``GROUP BY`` clause of the resulting select.
 
     :param having:
-      a :class:`ClauseElement` that will comprise the ``HAVING`` clause
+      a :class:`.ClauseElement` that will comprise the ``HAVING`` clause
       of the resulting select when ``GROUP BY`` is used.
 
     :param limit=None:
       functionality.
 
     :param order_by:
-      a scalar or list of :class:`ClauseElement` objects which will
+      a scalar or list of :class:`.ClauseElement` objects which will
       comprise the ``ORDER BY`` clause of the resulting select.
 
     :param prefixes:
-      a list of strings or :class:`ClauseElement` objects to include
+      a list of strings or :class:`.ClauseElement` objects to include
       directly after the SELECT keyword in the generated statement,
       for dialect-specific query features.  ``prefixes`` is
       also available via the :meth:`~.Select.prefix_with`
       column with its parent table's (or aliases) name so that name
       conflicts between columns in different tables don't occur.
       The format of the label is <tablename>_<column>.  The "c"
-      collection of the resulting :class:`Select` object will use these
+      collection of the resulting :class:`.Select` object will use these
       names as well for targeting column members.
       
       use_labels is also available via the :meth:`~._SelectBase.apply_labels`
                   **kwargs)
 
 def subquery(alias, *args, **kwargs):
-    """Return an :class:`Alias` object derived 
-    from a :class:`Select`.
+    """Return an :class:`.Alias` object derived 
+    from a :class:`.Select`.
 
     name
       alias name
     return Select(*args, **kwargs).alias(alias)
 
 def insert(table, values=None, inline=False, **kwargs):
-    """Return an :class:`Insert` clause element.
+    """Return an :class:`.Insert` clause element.
 
     Similar functionality is available via the :func:`insert()` method on
     :class:`~sqlalchemy.schema.Table`.
     return Insert(table, values, inline=inline, **kwargs)
 
 def update(table, whereclause=None, values=None, inline=False, **kwargs):
-    """Return an :class:`Update` clause element.
+    """Return an :class:`.Update` clause element.
 
     Similar functionality is available via the :func:`update()` method on
     :class:`~sqlalchemy.schema.Table`.
 
     :param table: The table to be updated.
 
-    :param whereclause: A :class:`ClauseElement` describing the ``WHERE``
+    :param whereclause: A :class:`.ClauseElement` describing the ``WHERE``
      condition of the ``UPDATE`` statement. Note that the
      :meth:`~Update.where()` generative method may also be used for this.
 
             **kwargs)
 
 def delete(table, whereclause = None, **kwargs):
-    """Return a :class:`Delete` clause element.
+    """Return a :class:`.Delete` clause element.
 
     Similar functionality is available via the :func:`delete()` method on
     :class:`~sqlalchemy.schema.Table`.
 
     :param table: The table to be updated.
 
-    :param whereclause: A :class:`ClauseElement` describing the ``WHERE``
+    :param whereclause: A :class:`.ClauseElement` describing the ``WHERE``
       condition of the ``UPDATE`` statement. Note that the
       :meth:`~Delete.where()` generative method may be used instead.
 
         operators.collate, type_=expr.type)
 
 def exists(*args, **kwargs):
-    """Return an ``EXISTS`` clause as applied to a :class:`Select` object.
+    """Return an ``EXISTS`` clause as applied to a :class:`.Select` object.
 
     Calling styles are of the following forms::
 
     """Return a ``UNION`` of multiple selectables.
 
     The returned object is an instance of
-    :class:`CompoundSelect`.
+    :class:`.CompoundSelect`.
 
     A similar :func:`union()` method is available on all
-    :class:`FromClause` subclasses.
+    :class:`.FromClause` subclasses.
 
     \*selects
-      a list of :class:`Select` instances.
+      a list of :class:`.Select` instances.
 
     \**kwargs
        available keyword arguments are the same as those of
     """Return a ``UNION ALL`` of multiple selectables.
 
     The returned object is an instance of
-    :class:`CompoundSelect`.
+    :class:`.CompoundSelect`.
 
     A similar :func:`union_all()` method is available on all
-    :class:`FromClause` subclasses.
+    :class:`.FromClause` subclasses.
 
     \*selects
-      a list of :class:`Select` instances.
+      a list of :class:`.Select` instances.
 
     \**kwargs
       available keyword arguments are the same as those of
     """Return an ``EXCEPT`` of multiple selectables.
 
     The returned object is an instance of
-    :class:`CompoundSelect`.
+    :class:`.CompoundSelect`.
 
     \*selects
-      a list of :class:`Select` instances.
+      a list of :class:`.Select` instances.
 
     \**kwargs
       available keyword arguments are the same as those of
     """Return an ``EXCEPT ALL`` of multiple selectables.
 
     The returned object is an instance of
-    :class:`CompoundSelect`.
+    :class:`.CompoundSelect`.
 
     \*selects
-      a list of :class:`Select` instances.
+      a list of :class:`.Select` instances.
 
     \**kwargs
       available keyword arguments are the same as those of
     """Return an ``INTERSECT`` of multiple selectables.
 
     The returned object is an instance of
-    :class:`CompoundSelect`.
+    :class:`.CompoundSelect`.
 
     \*selects
-      a list of :class:`Select` instances.
+      a list of :class:`.Select` instances.
 
     \**kwargs
       available keyword arguments are the same as those of
     """Return an ``INTERSECT ALL`` of multiple selectables.
 
     The returned object is an instance of
-    :class:`CompoundSelect`.
+    :class:`.CompoundSelect`.
 
     \*selects