<%namespace name="nav" file="nav.html"/>
<%namespace name="pydoc" file="pydoc.html"/>
<%def name="title()">SQLAlchemy 0.3 Documentation - Modules and Classes</%def>
+
+<%def name="style()">
+ ${parent.style()}
+ <link rel="stylesheet" href="docutil.css"></link>
+</%def>
+
<%!
filename = 'docstrings'
%>
make_doc(obj=types),
make_doc(obj=engine),
make_doc(obj=engine.url),
- make_doc(obj=orm, classes=[orm.MapperExtension]),
- make_doc(obj=orm.mapperlib, classes=[orm.mapperlib.Mapper]),
+ make_doc(obj=orm),
+ make_doc(obj=orm.mapperlib, classes=[orm.mapperlib.MapperExtension, orm.mapperlib.Mapper]),
make_doc(obj=orm.query, classes=[orm.query.Query, orm.query.QueryContext, orm.query.SelectionContext]),
make_doc(obj=orm.session, classes=[orm.session.Session, orm.session.SessionTransaction]),
make_doc(obj=pool),
from mako.ext.autohandler import autohandler
%>
<%inherit file="${autohandler(template, context)}"/>
-<%page cached="False" cache_key="${self.filename}"/>
+<%page cached="True" cache_key="${self.filename}"/>
<%doc>
base.html - common to all documentation pages. intentionally separate
<%doc>pydoc.myt - provides formatting functions for printing docstring.AbstractDoc generated python documentation objects.</%doc>
<%!
import docstring
-import sys, re
+from docutils.core import publish_parts
+import re, sys
-def whitespace(docstring):
- if not docstring:
+def whitespace(content):
+ """trim left whitespace."""
+ if not content:
return ''
-
# Convert tabs to spaces (following the normal Python rules)
# and split into a list of lines:
- lines = docstring.expandtabs().splitlines()
+ lines = content.expandtabs().splitlines()
# Determine minimum indentation (first line doesn't count):
indent = sys.maxint
for line in lines[1:]:
# Return a single string:
return '\n'.join(trimmed)
-def convquotes(text):
- return re.sub(r'``(.*?)``', lambda m: "<b>%s</b>" % m.group(1), text)
+def formatdocstring(content):
+ return publish_parts(whitespace(content), writer_name='html')['body']
%>
<%namespace name="formatting" file="formatting.html"/>
<%call expr="formatting.section(toc=toc, path=obj.toc_path, description=htmldescription, paged=paged, extension=extension)">
% if obj.doc:
- <div class="darkcell"><pre>${obj.doc or '' |whitespace, h,convquotes}</pre></div>
+ <div class="darkcell">${obj.doc or '' |formatdocstring}</div>
% endif
% if not obj.isclass and obj.functions:
<A name="${item and item.path or ''}"></a>
<b>def ${func.name}(${", ".join(map(lambda k: "<i>%s</i>" % k, func.arglist))})</b>
<div class="docstring">
- <pre>${func.doc or '' | whitespace, h, convquotes}</pre>
+ ${func.doc or '' | formatdocstring}
</div>
</div>
</%def>
<A name=""></a>
<b>${prop.name} = property()</b>
<div class="docstring">
- <pre>${prop.doc or '' | whitespace, h, convquotes}</pre>
+ ${prop.doc or '' | formatdocstring}
</div>
</div>
</%def>
<%def name="printtoc(root, paged, extension, current=None, children=True, anchor_toplevel=False)">
<ul>
% for item in root.children:
- <li><A style="${item is current and "font-weight:bold;" or "" }" href="${item.get_link(extension=extension,anchor=anchor_toplevel, usefilename=paged) }">${item.description}</a></li>
+ <%
+ anchor = anchor_toplevel
+ if paged and item.filename != root.filename:
+ anchor = False
+ %>
+ <li><A style="${item is current and "font-weight:bold;" or "" }" href="${item.get_link(extension=extension,anchor=anchor, usefilename=paged) }">${item.description}</a></li>
% if children:
${printtoc(item, current=current, children=True,anchor_toplevel=True, paged=paged, extension=extension)}
--- /dev/null
+/*
+:Author: David Goodger <goodger@python.org>
+:Id: $Id: html4css1.css 4993 2007-03-04 21:21:49Z fwiemann $
+:Copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+
+See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
+customize this style sheet.
+*/
+
+/* used to remove borders from tables and images */
+.borderless, table.borderless td, table.borderless th {
+ border: 0 }
+
+table.borderless td, table.borderless th {
+ /* Override padding for "table.docutils td" with "! important".
+ The right padding separates the table cells. */
+ padding: 0 0.5em 0 0 ! important }
+
+.first {
+ /* Override more specific margin styles with "! important". */
+ margin-top: 0 ! important }
+
+.last, .with-subtitle {
+ margin-bottom: 0 ! important }
+
+.hidden {
+ display: none }
+
+a.toc-backref {
+ text-decoration: none ;
+ color: black }
+
+blockquote.epigraph {
+ margin: 2em 5em ; }
+
+dl.docutils dd {
+ margin-bottom: 0.5em }
+
+/* Uncomment (and remove this text!) to get bold-faced definition list terms
+dl.docutils dt {
+ font-weight: bold }
+*/
+
+div.abstract {
+ margin: 2em 5em }
+
+div.abstract p.topic-title {
+ font-weight: bold ;
+ text-align: center }
+
+div.admonition, div.attention, div.caution, div.danger, div.error,
+div.hint, div.important, div.note, div.tip, div.warning {
+ margin: 2em ;
+ border: medium outset ;
+ padding: 1em }
+
+div.admonition p.admonition-title, div.hint p.admonition-title,
+div.important p.admonition-title, div.note p.admonition-title,
+div.tip p.admonition-title {
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+ color: red ;
+ font-weight: bold ;
+ font-family: sans-serif }
+
+/* Uncomment (and remove this text!) to get reduced vertical space in
+ compound paragraphs.
+div.compound .compound-first, div.compound .compound-middle {
+ margin-bottom: 0.5em }
+
+div.compound .compound-last, div.compound .compound-middle {
+ margin-top: 0.5em }
+*/
+
+div.dedication {
+ margin: 2em 5em ;
+ text-align: center ;
+ font-style: italic }
+
+div.dedication p.topic-title {
+ font-weight: bold ;
+ font-style: normal }
+
+div.figure {
+ margin-left: 2em ;
+ margin-right: 2em }
+
+div.footer, div.header {
+ clear: both;
+ font-size: smaller }
+
+div.line-block {
+ display: block ;
+ margin-top: 1em ;
+ margin-bottom: 1em }
+
+div.line-block div.line-block {
+ margin-top: 0 ;
+ margin-bottom: 0 ;
+ margin-left: 1.5em }
+
+div.sidebar {
+ margin-left: 1em ;
+ border: medium outset ;
+ padding: 1em ;
+ background-color: #ffffee ;
+ width: 40% ;
+ float: right ;
+ clear: right }
+
+div.sidebar p.rubric {
+ font-family: sans-serif ;
+ font-size: medium }
+
+div.system-messages {
+ margin: 5em }
+
+div.system-messages h1 {
+ color: red }
+
+div.system-message {
+ border: medium outset ;
+ padding: 1em }
+
+div.system-message p.system-message-title {
+ color: red ;
+ font-weight: bold }
+
+div.topic {
+ margin: 2em }
+
+h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
+h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
+ margin-top: 0.4em }
+
+h1.title {
+ text-align: center }
+
+h2.subtitle {
+ text-align: center }
+
+hr.docutils {
+ width: 75% }
+
+img.align-left {
+ clear: left }
+
+img.align-right {
+ clear: right }
+
+ol.simple, ul.simple {
+ margin-bottom: 1em }
+
+ol.arabic {
+ list-style: decimal }
+
+ol.loweralpha {
+ list-style: lower-alpha }
+
+ol.upperalpha {
+ list-style: upper-alpha }
+
+ol.lowerroman {
+ list-style: lower-roman }
+
+ol.upperroman {
+ list-style: upper-roman }
+
+p.attribution {
+ text-align: right ;
+ margin-left: 50% }
+
+p.caption {
+ font-style: italic }
+
+p.credits {
+ font-style: italic ;
+ font-size: smaller }
+
+p.label {
+ white-space: nowrap }
+
+p.rubric {
+ font-weight: bold ;
+ font-size: larger ;
+ color: maroon ;
+ text-align: center }
+
+p.sidebar-title {
+ font-family: sans-serif ;
+ font-weight: bold ;
+ font-size: larger }
+
+p.sidebar-subtitle {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+p.topic-title {
+ font-weight: bold }
+
+pre.address {
+ margin-bottom: 0 ;
+ margin-top: 0 ;
+ font-family: serif ;
+ font-size: 100% }
+
+pre.literal-block, pre.doctest-block {
+ margin-left: 2em ;
+ margin-right: 2em }
+
+span.classifier {
+ font-family: sans-serif ;
+ font-style: oblique }
+
+span.classifier-delimiter {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+span.interpreted {
+ font-family: sans-serif }
+
+span.option {
+ white-space: nowrap }
+
+span.pre {
+ white-space: pre }
+
+span.problematic {
+ color: red }
+
+span.section-subtitle {
+ /* font-size relative to parent (h1..h6 element) */
+ font-size: 80% }
+
+table.citation {
+ border-left: solid 1px gray;
+ margin-left: 1px }
+
+table.docinfo {
+ margin: 2em 4em }
+
+table.docutils {
+ margin-top: 0.5em ;
+ margin-bottom: 0.5em }
+
+table.footnote {
+ border-left: solid 1px black;
+ margin-left: 1px }
+
+table.docutils td, table.docutils th,
+table.docinfo td, table.docinfo th {
+ padding-left: 0.5em ;
+ padding-right: 0.5em ;
+ vertical-align: top }
+
+table.docutils th.field-name, table.docinfo th.docinfo-name {
+ font-weight: bold ;
+ text-align: left ;
+ white-space: nowrap ;
+ padding-left: 0 }
+
+h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
+h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
+ font-size: 100% }
+
+ul.auto-toc {
+ list-style-type: none }
+
col3 = row[mytable.c.mycol] # access via Column object.
ResultProxy also contains a map of TypeEngine objects and will
- invoke the appropriate ``convert_result_value()` method before
+ invoke the appropriate ``convert_result_value()`` method before
returning columns, as well as the ExecutionContext corresponding
to the statement execution. It provides several methods for which
to obtain information from the underlying ExecutionContext.
return self._col_aggregate(col, sql.func.max)
def sum(self, col):
- """Execute the SQL ``sum``() function against the given column."""
+ """Execute the SQL ``sum()`` function against the given column."""
return self._col_aggregate(col, sql.func.sum)
return new
def outerjoin_to(self, prop):
- """Outer join the table of this ``SelectResults`` to the table located against the given property name.
+ """Outer join the table of this ``SelectResults`` to the
+ table located against the given property name.
Subsequent calls to join_to or outerjoin_to will join against
- the rightmost table located from the previous ``join_to` or
- `outerjoin_to` call, searching for the property starting with
+ the rightmost table located from the previous ``join_to`` or
+ ``outerjoin_to`` call, searching for the property starting with
the rightmost mapper last located.
"""
def compile_mappers():
"""Compile all mappers that have been defined.
- This is equivalent to calling ``compile()` on any individual mapper.
+ This is equivalent to calling ``compile()`` on any individual mapper.
"""
if not len(mapper_registry):
All arguments may be sent to the ``sqlalchemy.orm.mapper()``
function where they are passed through to here.
- class_
+ class\_
The class to be mapped.
local_table
The lead object instance. child items will be processed per
the relations defined for this object's mapper.
- callable_
+ callable\_
The callable function.
recursive
Used by the function for internal context during recursive
calls, leave as None.
+
"""
if recursive is None:
row
The result row from the database
- class_
+ class\_
The class we are mapping.
"""
return hasattr(object, '_entity_name')
def object_mapper(object, raiseerror=True):
- """Given an object, return the primary Mapper associated with the
- object instance.
+ """Given an object, return the primary Mapper associated with the object instance.
+
+ object
+ The object instance.
+
+ raiseerror
+ Defaults to True: raise an ``InvalidRequestError`` if no mapper can
+ be located. If False, return None.
+
"""
try:
return mapper.compile()
def class_mapper(class_, entity_name=None, compile=True):
- """Given a ClassKey, return the primary Mapper associated with the
- key.
+ """Given a class and optional entity_name, return the primary Mapper associated with the key.
+
+ If no mapper can be located, raises ``InvalidRequestError``.
"""
try:
"""Return an array of object instances based on the given
clauses and key/value criterion.
- `*args` is a list of zero or more ``ClauseElements`` which will be
- connected by ``AND`` operators.
+ \*args
+ a list of zero or more ``ClauseElements`` which will be
+ connected by ``AND`` operators.
- `**params` is a set of zero or more key/value parameters which
- are converted into ``ClauseElements``. the keys are mapped to
- property or column names mapped by this mapper's Table, and
- the values are coerced into a ``WHERE`` clause separated by
- ``AND`` operators. If the local property/column names dont
- contain the key, a search will be performed against this
- mapper's immediate list of relations as well, forming the
- appropriate join conditions if a matching property is located.
+ \**params
+ a set of zero or more key/value parameters which
+ are converted into ``ClauseElements``. the keys are mapped to
+ property or column names mapped by this mapper's Table, and
+ the values are coerced into a ``WHERE`` clause separated by
+ ``AND`` operators. If the local property/column names dont
+ contain the key, a search will be performed against this
+ mapper's immediate list of relations as well, forming the
+ appropriate join conditions if a matching property is located.
- if the located property is a column-based property, the comparison
- value should be a scalar with an appropriate type. If the
- property is a relationship-bound property, the comparison value
- should be an instance of the related class.
+ if the located property is a column-based property, the comparison
+ value should be a scalar with an appropriate type. If the
+ property is a relationship-bound property, the comparison value
+ should be an instance of the related class.
- E.g.::
+ E.g.::
+
+ result = usermapper.select_by(user_name = 'fred')
- result = usermapper.select_by(user_name = 'fred')
"""
ret = self.extension.select_by(self, *args, **params)
return self._col_aggregate(col, sql.func.max)
def sum(self, col):
- """Execute the SQL ``sum``() function against the given column."""
+ """Execute the SQL ``sum()`` function against the given column."""
return self._col_aggregate(col, sql.func.sum)
"""Return a list of mapped instances corresponding to the rows
in a given *cursor* (i.e. ``ResultProxy``).
- *mappers_or_columns is an optional list containing one or more of
+ \*mappers_or_columns is an optional list containing one or more of
classes, mappers, strings or sql.ColumnElements which will be
applied to each row and added horizontally to the result set,
which becomes a list of tuples. The first element in each tuple
is the usual result based on the mapper represented by this
``Query``. Each additional element in the tuple corresponds to an
- entry in the *mappers_or_columns list.
+ entry in the \*mappers_or_columns list.
- For each element in *mappers_or_columns, if the element is
+ For each element in \*mappers_or_columns, if the element is
a mapper or mapped class, an additional class instance will be
present in the tuple. If the element is a string or sql.ColumnElement,
the corresponding result column from each row will be present in the tuple.
- Note that when *mappers_or_columns is present, "uniquing" for the result set
+ Note that when \*mappers_or_columns is present, "uniquing" for the result set
is *disabled*, so that the resulting tuples contain entities as they actually
correspond. this indicates that multiple results may be present if this
option is used.
state among all the Mappers and MapperProperty objects used in a
load operation.
- SelectionContext contains these attributes::
+ SelectionContext contains these attributes:
mapper
The Mapper which originated the instances() call.
return self.transaction
def connect(self, mapper=None, **kwargs):
- """Return a unique connection corresponding to the given
- mapper.
+ """Return a unique connection corresponding to the given mapper.
This connection will not be part of any pre-existing
transactional context.
return merged
def identity_key(self, *args, **kwargs):
- """Get an identity key
+ """Get an identity key.
Valid call signatures:
- identity_key(class_, ident, entity_name=None)
- class_ - mapped class
- ident - primary key, if the key is composite this is a tuple
- entity_name - optional entity name. May be given as a
- positional arg or as a keyword arg.
-
- identity_key(instance=instance)
- instance - object instance (must be given as a keyword arg)
-
- identity_key(row=row, class=class_, entity_name=None)
- row - result proxy row (must be given as a keyword arg)
+ identity_key(class\_, ident, entity_name=None)
+ class\_
+ mapped class
+
+ ident
+ primary key, if the key is composite this is a tuple
+
+ entity_name
+ optional entity name. May be given as a
+ positional arg or as a keyword arg.
+
+ identity_key(instance=instance)
+ instance
+ object instance (must be given as a keyword arg)
+
+ identity_key(row=row, class=class\_, entity_name=None)
+ row
+ result proxy row (must be given as a keyword arg)
+
"""
if args:
kw = {}
Further tables constructed with the same name/schema
combination will return the same Table instance.
- *args
+ \*args
Should contain a listing of the Column objects for this table.
- **kwargs
+ \**kwargs
options include:
schema
ForeignKey, the type can also be None, in which case the
type assigned will be that of the referenced column.
- *args
+ \*args
Constraint, ForeignKey, ColumnDefault and Sequence objects
should be added as list values.
- **kwargs
+ \**kwargs
Keyword arguments include:
key
return visitor.visit_sequence(self)
class Constraint(SchemaItem):
- """Represent a table-level ``Constraint`` such as a composite primary
- key, foreign key, or unique constraint.
+ """Represent a table-level ``Constraint`` such as a composite primary key, foreign key, or unique constraint.
Implements a hybrid of dict/setlike behavior with regards to the
list of underying columns.
name
The name of the index
- *columns
+ \*columns
Columns to include in the index. All columns must belong to
the same table, and no column may appear more than once.
- **kwargs
+ \**kwargs
Keyword arguments include:
unique
Defaults to True: create a unique index.
+
"""
self.name = name
class BoundMetaData(MetaData):
"""Build upon ``MetaData`` to provide the capability to bind to an
- ``Engine`` implementation.
+``Engine`` implementation.
"""
def __init__(self, engine_or_url, name=None, **kwargs):
return True
class DynamicMetaData(MetaData):
- """Build upon ``MetaData`` to provide the capability to bind to
- multiple ``Engine`` implementations on a dynamically alterable,
- thread-local basis.
+ """Build upon ``MetaData`` to provide the capability to bind to
+multiple ``Engine`` implementations on a dynamically alterable,
+thread-local basis.
"""
def __init__(self, name=None, threadlocal=True, **kwargs):
which will extend or override the default ``FROM`` objects
created from the column list and the whereclause.
- **kwargs
+ \**kwargs
Additional parameters for the ``Select`` object.
"""
value
Optional for simple case statements.
- else_
+ else\_
Optional as well, for case defaults.
"""
return cc
def cast(clause, totype, **kwargs):
- """ returns CAST function CAST(clause AS totype)
- Use with a sqlalchemy.types.TypeEngine object, i.e
- cast(table.c.unit_price * table.c.qty, Numeric(10,4))
- or
- cast(table.c.timestamp, DATE)
+ """return CAST function CAST(clause AS totype)
+
+ Use with a sqlalchemy.types.TypeEngine object, i.e
+ ``cast(table.c.unit_price * table.c.qty, Numeric(10,4))``
+ or ``cast(table.c.timestamp, DATE)``
+
"""
return _Cast(clause, totype, **kwargs)
is called a ``value-based bindparam``.
shortname
- an ``alias`` for this bind parameter. usually used to alias the ``key`` and
+ an ``alias`` for this bind parameter. usually used to alias the ``key`` and
``label`` of a column, i.e. ``somecolname`` and ``sometable_somecolname``
type
unique
if True, bind params sharing the same name will have their underlying ``key`` modified
to a uniquely generated name. mostly useful with value-based bind params.
+
"""
if isinstance(key, _ColumnClause):
__traverse_options__ = {'column_collections':False}
class Executor(object):
- """Interface representing a *thing that can produce Compiled objects
- and execute them*."""
+ """Interface representing a "thing that can produce Compiled objects
+ and execute them"."""
def execute_compiled(self, compiled, parameters, echo=None, **kwargs):
"""Execute a Compiled object."""
this is used for visit traversal.
- **kwargs may contain flags that change the collection
+ \**kwargs may contain flags that change the collection
that is returned, for example to return a subset of items
in order to cut down on larger traversals, or to return
child items from a different context (such as schema-level
def copy_container(self):
"""Return a copy of this ``ClauseElement``, if this
- ``ClauseElement`` contains other ``ClauseElements`.
+ ``ClauseElement`` contains other ``ClauseElements``.
If this ``ClauseElement`` is not a container, it should return
self. This is used to create copies of expression trees that
doc=\
"""Foreign key accessor. Points to a list of ForeignKey objects
which represents a Foreign Key placed on this column's ultimate
- ancestor.
+ ancestor.
""")
columns = property(lambda self:[self],
doc=\
columns in the column list of the resulting select. this will recursively
apply to any joins directly nested by this one as well.
- **kwargs
+ \**kwargs
all other kwargs are sent to the underlying ``select()`` function
"""
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
