From: Mike Bayer Date: Tue, 18 Dec 2007 23:53:40 +0000 (+0000) Subject: introductory docstring bonanza X-Git-Tag: rel_0_4_2~28 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ba0267a955d40efb09de06ce226fbab63994aa78;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git introductory docstring bonanza --- diff --git a/doc/build/gen_docstrings.py b/doc/build/gen_docstrings.py index 1931e08918..d7c6b210f1 100644 --- a/doc/build/gen_docstrings.py +++ b/doc/build/gen_docstrings.py @@ -4,7 +4,7 @@ import re 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 @@ -24,16 +24,16 @@ def make_all_docs(): 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, diff --git a/doc/build/templates/pydoc.html b/doc/build/templates/pydoc.html index 34bb5e7bc3..a4f4caf141 100644 --- a/doc/build/templates/pydoc.html +++ b/doc/build/templates/pydoc.html @@ -37,12 +37,14 @@ def formatdocstring(content): <%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) %> <%namespace name="formatting" file="formatting.html"/> diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index 783d60cf44..ff2245f39e 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 38ea903e43..b06f862f7e 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 175846ff8a..d4a0ad8418 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 6122b61b23..d07d8da835 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 a3487638c2..663819f052 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 dd0f89737f..8338bc554f 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 7e8d8b8bf8..8bff42d2c4 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 6119d1c6e6..52e39372d8 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 95d118ee40..2c3d3ea406 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 441a1d7cd6..aadac5122c 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 2c9a1d0ff5..0d7f76dcad 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 541590b82d..993eba4c5f 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 5036bc1154..7cf4eb2cc5 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 301acdc2b6..dd925a508d 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 2472853847..bdcd94688b 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 44e6ebf60d..83e388c4f3 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',