specific lexical element within a SQL string. Composed together
into a larger structure, they form a statement construct that may
be *compiled* into a string representation that can be passed to a database.
-The classes are organized into a
-hierarchy that begins at the basemost ClauseElement class. Key subclasses
-include ColumnElement, which represents the role of any column-based expression
+The classes are organized into a hierarchy that begins at the basemost
+:class:`.ClauseElement` class. Key subclasses include :class:`.ColumnElement`,
+which represents the role of any column-based expression
in a SQL statement, such as in the columns clause, WHERE clause, and ORDER BY
-clause, and FromClause, which represents the role of a token that is placed in
-the FROM clause of a SELECT statement.
+clause, and :class:`.FromClause`, which represents the role of a token that
+is placed in the FROM clause of a SELECT statement.
.. autofunction:: all_
In SQLAlchemy, the "dialect" is a Python object that represents information
and methods that allow database operations to proceed on a particular
kind of database backend and a particular kind of Python driver (or
- :term`DBAPI`) for that database. SQLAlchemy dialects are subclasses
+ :term:`DBAPI`) for that database. SQLAlchemy dialects are subclasses
of the :class:`.Dialect` class.
.. seealso::
what it needs here as well as remove its custom arguments from the
:attr:`.URL.query` collection. The URL can be modified in-place
in any other way as well.
- :param kwargs: The keyword arguments passed to :func`.create_engine`.
+ :param kwargs: The keyword arguments passed to :func:`.create_engine`.
The plugin can read and modify this dictionary in-place, to affect
the ultimate arguments used to create the engine. It should
remove its custom arguments from the dictionary as well.
"""Produce a proxied 'contains' expression using EXISTS.
This expression will be a composed product
- using the :meth:`.RelationshipProperty.Comparator.any`
- , :meth:`.RelationshipProperty.Comparator.has`,
+ using the :meth:`.RelationshipProperty.Comparator.any`,
+ :meth:`.RelationshipProperty.Comparator.has`,
and/or :meth:`.RelationshipProperty.Comparator.contains`
operators of the underlying proxied attributes.
"""
class _ModuleMarker(object):
- """"refers to a module name within
+ """Refers to a module name within
_decl_class_registry.
"""
"""The :class:`expression.Selectable` to which this :class:`_orm.Mapper`
is mapped.
- Typically an instance of :class:`_schema.Table`, :class:`_expression.Join`
- , or
- :class:`_expression.Alias`.
+ Typically an instance of :class:`_schema.Table`,
+ :class:`_expression.Join`, or :class:`_expression.Alias`.
The :attr:`_orm.Mapper.persist_selectable` is separate from
:attr:`_orm.Mapper.selectable` in that the former represents columns
the order in which they correspond to the mapped
:class:`_schema.Table`
object's primary key columns, or if the
- :paramref:`_orm.Mapper.primary_key` configuration parameter were used
- , in
+ :paramref:`_orm.Mapper.primary_key` configuration parameter were
+ used, in
the order used for that parameter. For example, if the primary key
of a row is represented by the integer
digits "5, 10" the call would look like::
sess = Session()
- .. seealso:
+ .. seealso::
:ref:`session_getting` - introductory text on creating
sessions using :class:`.sessionmaker`.
Column('x', Integer(), table=None)
>>> cc['y']
- :class`.ColumnCollection` also indexes the columns in order and allows
+ :class:`.ColumnCollection` also indexes the columns in order and allows
them to be accessible by their integer position::
>>> cc[0]
[Column('x', Integer(), table=None),
Column('y', Integer(), table=None)]
- The base :class:`_expression.ColumnCollection` object can store duplicates
- , which can
+ The base :class:`_expression.ColumnCollection` object can store
+ duplicates, which can
mean either two columns with the same key, in which case the column
returned by key access is **arbitrary**::
ancestor column.
:param column: the target :class:`_expression.ColumnElement`
- to be matched
+ to be matched.
:param require_embedded: only return corresponding columns for
the given :class:`_expression.ColumnElement`, if the given
return cloned_traverse(self, {}, {"bindparam": visit_bindparam})
def compare(self, other, **kw):
- r"""Compare this ClauseElement to the given ClauseElement.
+ r"""Compare this ``ClauseElement`` to the given ``ClauseElement``.
Subclasses should override the default behavior, which is a
straight identity comparison.
- \**kw are arguments consumed by subclass compare() methods and
- may be used to modify the criteria for comparison.
- (see :class:`_expression.ColumnElement`)
+ \**kw are arguments consumed by subclass ``compare()`` methods and
+ may be used to modify the criteria for comparison
+ (see :class:`_expression.ColumnElement`).
"""
return traversals.compare(self, other, **kw)
"""
key = None
- """the 'key' that in some circumstances refers to this object in a
+ """The 'key' that in some circumstances refers to this object in a
Python namespace.
This typically refers to the "key" of the column as present in the
- ``.c`` collection of a selectable, e.g. sometable.c["somekey"] would
- return a Column with a .key of "somekey".
+ ``.c`` collection of a selectable, e.g. ``sometable.c["somekey"]`` would
+ return a :class:`_schema.Column` with a ``.key`` of "somekey".
"""
This is a shortcut to the :func:`_expression.label` function.
- if 'name' is None, an anonymous label name will be generated.
+ If 'name' is ``None``, an anonymous label name will be generated.
"""
return Label(name, self, self.type)
@util.memoized_property
def anon_label(self):
- """provides a constant 'anonymous label' for this ColumnElement.
+ """Provides a constant 'anonymous label' for this ColumnElement.
This is a label() expression which will be named at compile time.
- The same label() is returned each time anon_label is called so
- that expressions can reference anon_label multiple times, producing
- the same label name at compile time.
+ The same label() is returned each time ``anon_label`` is called so
+ that expressions can reference ``anon_label`` multiple times,
+ producing the same label name at compile time.
- the compiler uses this function automatically at compile time
+ The compiler uses this function automatically at compile time
for expressions that are known to be 'unnamed' like binary
expressions and function calls.
be eligible for autocommit if no transaction is in progress.
:param text:
- the text of the SQL statement to be created.
use ``:<param>``
+ the text of the SQL statement to be created.
Use ``:<param>``
to specify bind parameters; they will be compiled to their
engine-specific format.
:param \**types: A mapping of string names to :class:`.TypeEngine`
type objects indicating the datatypes to use for names that are
- SELECTed from the textual string. Prefer to use the ``\*cols``
+ SELECTed from the textual string. Prefer to use the ``*cols``
argument as it also indicates positional ordering.
"""
times against a statement, which will have the effect of each
clause being combined using :func:`.and_`::
- stmt = select([users_table]).\
- where(users_table.c.name == 'wendy').\
- where(users_table.c.enrolled == True)
+ stmt = (
+ select([users_table]).
+ where(users_table.c.name == 'wendy').
+ where(users_table.c.enrolled == True)
+ )
The :func:`.and_` construct must be given at least one positional
argument in order to be valid; a :func:`.and_` construct with no
:param type\_: an optional :class:`~sqlalchemy.types.TypeEngine`
object which will
provide result-set translation and additional expression semantics for
- this column. If left as None the type will be NullType.
+ this column. If left as ``None`` the type will be :class:`.NullType`.
.. seealso::
from sqlalchemy import desc, nullsfirst
- stmt = select([users_table]).\
- order_by(nullsfirst(desc(users_table.c.name)))
+ stmt = select([users_table]).order_by(
+ nullsfirst(desc(users_table.c.name)))
The SQL expression from the above would resemble::
rather than as its standalone
function version, as in::
- stmt = (select([users_table]).
- order_by(users_table.c.name.desc().nullsfirst())
- )
+ stmt = select([users_table]).order_by(
+ users_table.c.name.desc().nullsfirst())
.. seealso::
from sqlalchemy import desc, nullslast
- stmt = select([users_table]).\
- order_by(nullslast(desc(users_table.c.name)))
+ stmt = select([users_table]).order_by(
+ nullslast(desc(users_table.c.name)))
The SQL expression from the above would resemble::
rather than as its standalone
function version, as in::
- stmt = select([users_table]).\
- order_by(users_table.c.name.desc().nullslast())
+ stmt = select([users_table]).order_by(
+ users_table.c.name.desc().nullslast())
.. seealso::
ROW_NUMBER() OVER(ORDER BY some_column
RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW)
- A value of None indicates "unbounded", a
+ A value of ``None`` indicates "unbounded", a
value of zero indicates "current row", and negative / positive
integers indicate "preceding" and "following":
of such, that will be used as the ORDER BY clause
of the OVER construct.
:param range\_: optional range clause for the window. This is a
- tuple value which can contain integer values or None, and will
- render a RANGE BETWEEN PRECEDING / FOLLOWING clause
+ tuple value which can contain integer values or ``None``,
+ and will render a RANGE BETWEEN PRECEDING / FOLLOWING clause.
.. versionadded:: 1.1
def op(
self, opstring, precedence=0, is_comparison=False, return_type=None
):
- """produce a generic operator function.
+ """Produce a generic operator function.
e.g.::
somecolumn LIKE :param || '%' ESCAPE '/'
- With the value of :param as ``"foo/%bar"``.
+ With the value of ``:param`` as ``"foo/%bar"``.
.. versionadded:: 1.2
somecolumn LIKE '%' || :param ESCAPE '/'
- With the value of :param as ``"foo/%bar"``.
+ With the value of ``:param`` as ``"foo/%bar"``.
.. versionadded:: 1.2
somecolumn LIKE '%' || :param || '%' ESCAPE '/'
- With the value of :param as ``"foo/%bar"``.
+ With the value of ``:param`` as ``"foo/%bar"``.
.. versionadded:: 1.2
"""
def __init__(self, arg, **kwargs):
- """"Construct a new :class:`.ColumnDefault`.
+ """Construct a new :class:`.ColumnDefault`.
:param arg: argument representing the default value.
.. versionadded:: 1.4
- .. seealso:
+ .. seealso::
:attr:`_expression.FromClause.exported_columns`
column.
:param column: the target :class:`_expression.ColumnElement`
- to be matched
+ to be matched.
:param require_embedded: only return corresponding columns for
the given :class:`_expression.ColumnElement`, if the given
.. versionadded:: 1.4
- .. seealso:
+ .. seealso::
:attr:`expression.Selectable.exported_columns`
def __init__(self, name, *columns, **kw):
"""Produce a new :class:`_expression.TableClause`.
- The object returned is an instance of :class:`_expression.TableClause`
- , which
+ The object returned is an instance of
+ :class:`_expression.TableClause`, which
represents the "syntactical" portion of the schema-level
:class:`_schema.Table` object.
It may be used to construct lightweight table constructs.
.. versionadded:: 1.4
- .. seealso:
+ .. seealso::
:attr:`expression.Selectable.exported_columns`
A similar :func:`union()` method is available on all
:class:`_expression.FromClause` subclasses.
- \*selects
+ :param \*selects:
a list of :class:`_expression.Select` instances.
- \**kwargs
- available keyword arguments are the same as those of
- :func:`select`.
+ :param \**kwargs:
+ available keyword arguments are the same as those of
+ :func:`select`.
"""
return CompoundSelect(CompoundSelect.UNION, *selects, **kwargs)
A similar :func:`union_all()` method is available on all
:class:`_expression.FromClause` subclasses.
- \*selects
+ :param \*selects:
a list of :class:`_expression.Select` instances.
- \**kwargs
+ :param \**kwargs:
available keyword arguments are the same as those of
:func:`select`.
The returned object is an instance of
:class:`_expression.CompoundSelect`.
- \*selects
+ :param \*selects:
a list of :class:`_expression.Select` instances.
- \**kwargs
+ :param \**kwargs:
available keyword arguments are the same as those of
:func:`select`.
The returned object is an instance of
:class:`_expression.CompoundSelect`.
- \*selects
+ :param \*selects:
a list of :class:`_expression.Select` instances.
- \**kwargs
+ :param \**kwargs:
available keyword arguments are the same as those of
:func:`select`.
The returned object is an instance of
:class:`_expression.CompoundSelect`.
- \*selects
+ :param \*selects:
a list of :class:`_expression.Select` instances.
- \**kwargs
+ :param \**kwargs:
available keyword arguments are the same as those of
:func:`select`.
The returned object is an instance of
:class:`_expression.CompoundSelect`.
- \*selects
+ :param \*selects:
a list of :class:`_expression.Select` instances.
- \**kwargs
+ :param \**kwargs:
available keyword arguments are the same as those of
:func:`select`.
@util.preload_module("sqlalchemy.sql.util")
def reduce_columns(self, only_synonyms=True):
- """Return a new :func`.select` construct with redundantly
+ """Return a new :func:`.select` construct with redundantly
named, equivalently-valued columns removed from the columns clause.
"Redundant" here means two columns where one refers to the
return CompoundSelect._create_union_all(self, other, **kwargs)
def except_(self, other, **kwargs):
- """return a SQL EXCEPT of this select() construct against the given
- selectable."""
+ """Return a SQL ``EXCEPT`` of this select() construct against
+ the given selectable.
+ """
return CompoundSelect._create_except(self, other, **kwargs)
def except_all(self, other, **kwargs):
- """return a SQL EXCEPT ALL of this select() construct against the
- given selectable.
+ """Return a SQL ``EXCEPT ALL`` of this select() construct against
+ the given selectable.
"""
return CompoundSelect._create_except_all(self, other, **kwargs)
)
While it is possible to use :attr:`_types.JSON.NULL` in this context, the
- :attr:`_types.JSON.NULL` value will be returned as the value of the column
- ,
+ :attr:`_types.JSON.NULL` value will be returned as the value of the
+ column,
which in the context of the ORM or other repurposing of the default
value, may not be desirable. Using a SQL expression means the value
will be re-fetched from the database within the context of retrieving
return None
def to_offline_string(self, statement_cache, statement, parameters):
- """generate an "offline string" form of this :class:`.CacheKey`
+ """Generate an "offline string" form of this :class:`.CacheKey`
The "offline string" is basically the string SQL for the
statement plus a repr of the bound parameter values in series.
identities in order to work as a cache key, the "offline" version
is suitable for a cache that will work for other processes as well.
- The given "statement_cache" is a dictionary-like object where the
- string form of the statement itself will be cached. this dictionary
+ The given ``statement_cache`` is a dictionary-like object where the
+ string form of the statement itself will be cached. This dictionary
should be in a longer lived scope in order to reduce the time spent
stringifying statements.
)
def bind_expression(self, bindvalue):
- """"Given a bind value (i.e. a :class:`.BindParameter` instance),
+ """Given a bind value (i.e. a :class:`.BindParameter` instance),
return a SQL expression in its place.
This is typically a SQL function that wraps the existing bound
def copy(self, **kw):
return MyType(self.impl.length)
- The class-level "impl" attribute is required, and can reference any
- TypeEngine class. Alternatively, the load_dialect_impl() method
- can be used to provide different type classes based on the dialect
- given; in this case, the "impl" variable can reference
+ The class-level ``impl`` attribute is required, and can reference any
+ :class:`.TypeEngine` class. Alternatively, the :meth:`load_dialect_impl`
+ method can be used to provide different type classes based on the dialect
+ given; in this case, the ``impl`` variable can reference
``TypeEngine`` as a placeholder.
Types that receive a Python type that isn't similar to the ultimate type
class ProfileStatsFile(object):
- """"Store per-platform/fn profiling results in a file.
+ """Store per-platform/fn profiling results in a file.
There was no json module available when this was written, but now
the file format which is very deterministically line oriented is kind of
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
