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,
<%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"/>
# 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
# 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
"""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.
"""
-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
-"""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
#
# 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."""
# 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
# 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
# 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,
# 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
# 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
# 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
+"""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
"""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
# 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
# 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',
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
