Commits

Mike Bayer committed 727d7b7

introductory docstring bonanza

  • Participants
  • Parent commits 51d0726

Comments (0)

Files changed (18)

File doc/build/gen_docstrings.py

 
 from sqlalchemy import schema, types, engine, sql, pool, orm, exceptions, databases, interfaces
 from sqlalchemy.sql import compiler, expression
-from sqlalchemy.engine import default, strategies, threadlocal
+from sqlalchemy.engine import default, strategies, threadlocal, url
 import sqlalchemy.orm.shard
 import sqlalchemy.ext.sessioncontext as sessioncontext
 import sqlalchemy.ext.selectresults as selectresults
     objects = [
         make_doc(obj=engine),
         make_doc(obj=default),
-        make_doc(obj=engine.url),
+        make_doc(obj=strategies),
         make_doc(obj=threadlocal),
+        make_doc(obj=url),
         make_doc(obj=exceptions),
+        make_doc(obj=interfaces),
+        make_doc(obj=pool),
         make_doc(obj=schema),
         #make_doc(obj=sql,include_all_classes=True),
         make_doc(obj=compiler),
         make_doc(obj=expression,include_all_classes=True),
-        make_doc(obj=interfaces),
-        make_doc(obj=pool),
-        make_doc(obj=strategies),
         make_doc(obj=types),
         make_doc(obj=orm),
         make_doc(obj=orm.collections, classes=[orm.collections.collection,

File doc/build/templates/pydoc.html

 <%def name="inline_links(toc, extension, paged)"><%
     def link(match):
         (module, desc) = match.group(1,2)
-        if desc.endswith('()'):
+        if not desc:
+            path = "docstrings_" + module
+        elif desc.endswith('()'):
             path = "docstrings_" + module + "_modfunc_" + desc[:-2]
         else:
             path = "docstrings_" + module + "_" + desc
-        return capture(nav.toclink, toc=toc, path=path, description=desc, extension=extension, paged=paged)
-    return lambda content: re.sub(r'\[(.+?)#(.+?)?\]', link, content)
+        return capture(nav.toclink, toc=toc, path=path, description=desc or None, extension=extension, paged=paged)
+    return lambda content: re.sub('\[(.+?)#(.*?)\]', link, content)
 %></%def>
 
 <%namespace name="formatting" file="formatting.html"/>

File lib/sqlalchemy/engine/base.py

 # 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

File lib/sqlalchemy/engine/default.py

 # 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

File lib/sqlalchemy/engine/strategies.py

 """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.
+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 constructing a new EngineStrategy
-object which will add itself to the list of available strategies.
+New strategies can be added via new ``EngineStrategy``
+classes.
 """
 
 

File lib/sqlalchemy/engine/threadlocal.py

+"""Provides a thread-local transactional wrapper around the root Engine class.
+
+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
 
-"""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.
-"""
-
 class TLSession(object):
     def __init__(self, engine):
         self.engine = engine

File lib/sqlalchemy/engine/url.py

-"""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

File lib/sqlalchemy/exceptions.py

 #
 # 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."""

File lib/sqlalchemy/orm/__init__.py

 # 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

File lib/sqlalchemy/orm/interfaces.py

 # 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

File lib/sqlalchemy/orm/mapper.py

 # 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
     columns.
 
     Instances of this class should be constructed via the
-    ``sqlalchemy.orm.mapper()`` function.
+    [sqlalchemy.orm#mapper()] function.
     """
 
     def __init__(self,

File lib/sqlalchemy/orm/properties.py

 # 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

File lib/sqlalchemy/orm/query.py

 # 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

File lib/sqlalchemy/orm/session.py

 # 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
 
     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

File lib/sqlalchemy/orm/shard.py

+"""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

File lib/sqlalchemy/schema.py

 
 """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.
+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.
 
-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.
+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

File lib/sqlalchemy/sql/compiler.py

 # 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

File lib/sqlalchemy/types.py

 # 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',