summaryrefslogtreecommitdiff
path: root/lib/sqlalchemy/sql
diff options
context:
space:
mode:
authormike bayer <mike_mp@zzzcomputing.com>2020-04-14 19:48:20 +0000
committerGerrit Code Review <gerrit@bbpush.zzzcomputing.com>2020-04-14 19:48:20 +0000
commitd9b230e78c70c17a6856f4ff3b8380b9ce510702 (patch)
tree3e1583daaa76cff27fbdf5de8b3b1f63c00a1225 /lib/sqlalchemy/sql
parentf39cf13680a0ee5b190d498d29ea31c76f546dfb (diff)
parentcea03be855514d592b6671fa6dbc074a19a795fb (diff)
downloadsqlalchemy-d9b230e78c70c17a6856f4ff3b8380b9ce510702.tar.gz
Merge "Run search and replace of symbolic module names"
Diffstat (limited to 'lib/sqlalchemy/sql')
-rw-r--r--lib/sqlalchemy/sql/annotation.py6
-rw-r--r--lib/sqlalchemy/sql/base.py83
-rw-r--r--lib/sqlalchemy/sql/compiler.py17
-rw-r--r--lib/sqlalchemy/sql/crud.py6
-rw-r--r--lib/sqlalchemy/sql/ddl.py76
-rw-r--r--lib/sqlalchemy/sql/dml.py172
-rw-r--r--lib/sqlalchemy/sql/elements.py380
-rw-r--r--lib/sqlalchemy/sql/events.py65
-rw-r--r--lib/sqlalchemy/sql/functions.py40
-rw-r--r--lib/sqlalchemy/sql/operators.py44
-rw-r--r--lib/sqlalchemy/sql/schema.py721
-rw-r--r--lib/sqlalchemy/sql/selectable.py1078
-rw-r--r--lib/sqlalchemy/sql/sqltypes.py132
-rw-r--r--lib/sqlalchemy/sql/traversals.py2
-rw-r--r--lib/sqlalchemy/sql/type_api.py17
-rw-r--r--lib/sqlalchemy/sql/visitors.py70
16 files changed, 1703 insertions, 1206 deletions
diff --git a/lib/sqlalchemy/sql/annotation.py b/lib/sqlalchemy/sql/annotation.py
index d895e730c..891b8ae09 100644
--- a/lib/sqlalchemy/sql/annotation.py
+++ b/lib/sqlalchemy/sql/annotation.py
@@ -64,7 +64,8 @@ class SupportsCloneAnnotations(SupportsAnnotations):
return new
def _deannotate(self, values=None, clone=False):
- """return a copy of this :class:`.ClauseElement` with annotations
+ """return a copy of this :class:`_expression.ClauseElement`
+ with annotations
removed.
:param values: optional tuple of individual values
@@ -98,7 +99,8 @@ class SupportsWrappingAnnotations(SupportsAnnotations):
return Annotated(self, values)
def _deannotate(self, values=None, clone=False):
- """return a copy of this :class:`.ClauseElement` with annotations
+ """return a copy of this :class:`_expression.ClauseElement`
+ with annotations
removed.
:param values: optional tuple of individual values
diff --git a/lib/sqlalchemy/sql/base.py b/lib/sqlalchemy/sql/base.py
index a02955c8c..1b9b20b32 100644
--- a/lib/sqlalchemy/sql/base.py
+++ b/lib/sqlalchemy/sql/base.py
@@ -519,8 +519,9 @@ class Executable(Generative):
execution.
Execution options can be set on a per-statement or
- per :class:`.Connection` basis. Additionally, the
- :class:`.Engine` and ORM :class:`~.orm.query.Query` objects provide
+ per :class:`_engine.Connection` basis. Additionally, the
+ :class:`_engine.Engine` and ORM :class:`~.orm.query.Query`
+ objects provide
access to execution options which they in turn configure upon
connections.
@@ -533,14 +534,14 @@ class Executable(Generative):
Note that only a subset of possible execution options can be applied
to a statement - these include "autocommit" and "stream_results",
but not "isolation_level" or "compiled_cache".
- See :meth:`.Connection.execution_options` for a full list of
+ See :meth:`_engine.Connection.execution_options` for a full list of
possible options.
.. seealso::
- :meth:`.Connection.execution_options`
+ :meth:`_engine.Connection.execution_options`
- :meth:`.Query.execution_options`
+ :meth:`_query.Query.execution_options`
:meth:`.Executable.get_execution_options`
@@ -573,7 +574,8 @@ class Executable(Generative):
@util.deprecated_20(
":meth:`.Executable.execute`",
alternative="All statement execution in SQLAlchemy 2.0 is performed "
- "by the :meth:`.Connection.execute` method of :class:`.Connection`, "
+ "by the :meth:`_engine.Connection.execute` method of "
+ ":class:`_engine.Connection`, "
"or in the ORM by the :meth:`.Session.execute` method of "
":class:`.Session`.",
)
@@ -595,7 +597,8 @@ class Executable(Generative):
@util.deprecated_20(
":meth:`.Executable.scalar`",
alternative="All statement execution in SQLAlchemy 2.0 is performed "
- "by the :meth:`.Connection.execute` method of :class:`.Connection`, "
+ "by the :meth:`_engine.Connection.execute` method of "
+ ":class:`_engine.Connection`, "
"or in the ORM by the :meth:`.Session.execute` method of "
":class:`.Session`; the :meth:`.Result.scalar` method can then be "
"used to return a scalar result.",
@@ -609,7 +612,8 @@ class Executable(Generative):
@property
def bind(self):
- """Returns the :class:`.Engine` or :class:`.Connection` to
+ """Returns the :class:`_engine.Engine` or :class:`_engine.Connection`
+ to
which this :class:`.Executable` is bound, or None if none found.
This is a traversal which checks locally, then
@@ -675,14 +679,19 @@ class SchemaVisitor(ClauseVisitor):
class ColumnCollection(object):
- """Collection of :class:`.ColumnElement` instances, typically for
+ """Collection of :class:`_expression.ColumnElement` instances,
+ typically for
selectables.
- The :class:`.ColumnCollection` has both mapping- and sequence- like
- behaviors. A :class:`.ColumnCollection` usually stores :class:`.Column`
+ The :class:`_expression.ColumnCollection`
+ has both mapping- and sequence- like
+ behaviors. A :class:`_expression.ColumnCollection` usually stores
+ :class:`_schema.Column`
objects, which are then accessible both via mapping style access as well
- as attribute access style. The name for which a :class:`.Column` would
- be present is normally that of the :paramref:`.Column.key` parameter,
+ as attribute access style. The name for which a :class:`_schema.Column`
+ would
+ be present is normally that of the :paramref:`_schema.Column.key`
+ parameter,
however depending on the context, it may be stored under a special label
name::
@@ -706,7 +715,8 @@ class ColumnCollection(object):
>>> cc[1]
Column('y', Integer(), table=None)
- .. versionadded:: 1.4 :class:`.ColumnCollection` allows integer-based
+ .. versionadded:: 1.4 :class:`_expression.ColumnCollection`
+ allows integer-based
index access to the collection.
Iterating the collection yields the column expressions in order::
@@ -715,7 +725,8 @@ class ColumnCollection(object):
[Column('x', Integer(), table=None),
Column('y', Integer(), table=None)]
- The base :class:`.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**::
@@ -730,18 +741,21 @@ class ColumnCollection(object):
True
Or it can also mean the same column multiple times. These cases are
- supported as :class:`.ColumnCollection` is used to represent the columns in
+ supported as :class:`_expression.ColumnCollection`
+ is used to represent the columns in
a SELECT statement which may include duplicates.
A special subclass :class:`.DedupeColumnCollection` exists which instead
maintains SQLAlchemy's older behavior of not allowing duplicates; this
- collection is used for schema level objects like :class:`.Table` and
+ collection is used for schema level objects like :class:`_schema.Table`
+ and
:class:`.PrimaryKeyConstraint` where this deduping is helpful. The
:class:`.DedupeColumnCollection` class also has additional mutation methods
as the schema constructs have more use cases that require removal and
replacement of columns.
- .. versionchanged:: 1.4 :class:`.ColumnCollection` now stores duplicate
+ .. versionchanged:: 1.4 :class:`_expression.ColumnCollection`
+ now stores duplicate
column keys as well as the same column in multiple positions. The
:class:`.DedupeColumnCollection` class is added to maintain the
former behavior in those cases where deduplication as well as
@@ -884,28 +898,34 @@ class ColumnCollection(object):
return ImmutableColumnCollection(self)
def corresponding_column(self, column, require_embedded=False):
- """Given a :class:`.ColumnElement`, return the exported
- :class:`.ColumnElement` object from this :class:`.ColumnCollection`
- which corresponds to that original :class:`.ColumnElement` via a common
+ """Given a :class:`_expression.ColumnElement`, return the exported
+ :class:`_expression.ColumnElement` object from this
+ :class:`_expression.ColumnCollection`
+ which corresponds to that original :class:`_expression.ColumnElement`
+ via a common
ancestor column.
- :param column: the target :class:`.ColumnElement` to be matched
+ :param column: the target :class:`_expression.ColumnElement`
+ to be matched
:param require_embedded: only return corresponding columns for
- the given :class:`.ColumnElement`, if the given
- :class:`.ColumnElement` is actually present within a sub-element
- of this :class:`.Selectable`. Normally the column will match if
+ the given :class:`_expression.ColumnElement`, if the given
+ :class:`_expression.ColumnElement`
+ is actually present within a sub-element
+ of this :class:`expression.Selectable`.
+ Normally the column will match if
it merely shares a common ancestor with one of the exported
- columns of this :class:`.Selectable`.
+ columns of this :class:`expression.Selectable`.
.. seealso::
- :meth:`.Selectable.corresponding_column` - invokes this method
+ :meth:`expression.Selectable.corresponding_column`
+ - invokes this method
against the collection returned by
- :attr:`.Selectable.exported_columns`.
+ :attr:`expression.Selectable.exported_columns`.
.. versionchanged:: 1.4 the implementation for ``corresponding_column``
- was moved onto the :class:`.ColumnCollection` itself.
+ was moved onto the :class:`_expression.ColumnCollection` itself.
"""
@@ -976,9 +996,10 @@ class ColumnCollection(object):
class DedupeColumnCollection(ColumnCollection):
- """A :class:`.ColumnCollection` that maintains deduplicating behavior.
+ """A :class:`_expression.ColumnCollection`
+ that maintains deduplicating behavior.
- This is useful by schema level objects such as :class:`.Table` and
+ This is useful by schema level objects such as :class:`_schema.Table` and
:class:`.PrimaryKeyConstraint`. The collection includes more
sophisticated mutator methods as well to suit schema objects which
require mutable column collections.
diff --git a/lib/sqlalchemy/sql/compiler.py b/lib/sqlalchemy/sql/compiler.py
index 23b15b158..7ef9f7e6d 100644
--- a/lib/sqlalchemy/sql/compiler.py
+++ b/lib/sqlalchemy/sql/compiler.py
@@ -393,7 +393,7 @@ class Compiled(object):
:param dialect: :class:`.Dialect` to compile against.
- :param statement: :class:`.ClauseElement` to be compiled.
+ :param statement: :class:`_expression.ClauseElement` to be compiled.
:param bind: Optional Engine or Connection to compile this
statement against.
@@ -533,7 +533,7 @@ class _CompileLabel(elements.ColumnElement):
class SQLCompiler(Compiled):
"""Default implementation of :class:`.Compiled`.
- Compiles :class:`.ClauseElement` objects into SQL strings.
+ Compiles :class:`_expression.ClauseElement` objects into SQL strings.
"""
@@ -637,8 +637,9 @@ class SQLCompiler(Compiled):
"""Optional :class:`.CompileState` object that maintains additional
state used by the compiler.
- Major executable objects such as :class:`~.sql.expression.Insert`,
- :class:`.Update`, :class:`.Delete`, :class:`.Select` will generate this
+ Major executable objects such as :class:`_expression.Insert`,
+ :class:`_expression.Update`, :class:`_expression.Delete`,
+ :class:`_expression.Select` will generate this
state when compiled in order to calculate additional information about the
object. For the top level object that is to be executed, the state can be
stored here where it can also have applicability towards result set
@@ -662,7 +663,7 @@ class SQLCompiler(Compiled):
:param dialect: :class:`.Dialect` to be used
- :param statement: :class:`.ClauseElement` to be compiled
+ :param statement: :class:`_expression.ClauseElement` to be compiled
:param column_keys: a list of column names to be compiled into an
INSERT or UPDATE statement.
@@ -3351,10 +3352,12 @@ class StrSQLCompiler(SQLCompiler):
The :class:`.StrSQLCompiler` is invoked whenever a Core expression
element is directly stringified without calling upon the
- :meth:`.ClauseElement.compile` method. It can render a limited set
+ :meth:`_expression.ClauseElement.compile` method.
+ It can render a limited set
of non-standard SQL constructs to assist in basic stringification,
however for more substantial custom or dialect-specific SQL constructs,
- it will be necessary to make use of :meth:`.ClauseElement.compile`
+ it will be necessary to make use of
+ :meth:`_expression.ClauseElement.compile`
directly.
.. seealso::
diff --git a/lib/sqlalchemy/sql/crud.py b/lib/sqlalchemy/sql/crud.py
index 114dbec9e..4d14497c1 100644
--- a/lib/sqlalchemy/sql/crud.py
+++ b/lib/sqlalchemy/sql/crud.py
@@ -24,10 +24,10 @@ REQUIRED = util.symbol(
"""
Placeholder for the value within a :class:`.BindParameter`
which is required to be present when the statement is passed
-to :meth:`.Connection.execute`.
+to :meth:`_engine.Connection.execute`.
-This symbol is typically used when a :func:`.expression.insert`
-or :func:`.expression.update` statement is compiled without parameter
+This symbol is typically used when a :func:`_expression.insert`
+or :func:`_expression.update` statement is compiled without parameter
values present.
""",
diff --git a/lib/sqlalchemy/sql/ddl.py b/lib/sqlalchemy/sql/ddl.py
index 5a2095604..4c8250e98 100644
--- a/lib/sqlalchemy/sql/ddl.py
+++ b/lib/sqlalchemy/sql/ddl.py
@@ -138,12 +138,13 @@ class DDLElement(roles.DDLRole, Executable, _DDLCompiles):
This DDL element.
:target:
- The :class:`.Table` or :class:`.MetaData` object which is the
+ The :class:`_schema.Table` or :class:`_schema.MetaData`
+ object which is the
target of this event. May be None if the DDL is executed
explicitly.
:bind:
- The :class:`.Connection` being used for DDL execution
+ The :class:`_engine.Connection` being used for DDL execution
:tables:
Optional keyword argument - a list of Table objects which are to
@@ -216,8 +217,9 @@ class DDL(DDLElement):
Specifies literal SQL DDL to be executed by the database. DDL objects
function as DDL event listeners, and can be subscribed to those events
- listed in :class:`.DDLEvents`, using either :class:`.Table` or
- :class:`.MetaData` objects as targets. Basic templating support allows
+ listed in :class:`.DDLEvents`, using either :class:`_schema.Table` or
+ :class:`_schema.MetaData` objects as targets.
+ Basic templating support allows
a single DDL instance to handle repetitive tasks for multiple tables.
Examples::
@@ -371,12 +373,12 @@ class CreateTable(_CreateDropBase):
):
"""Create a :class:`.CreateTable` construct.
- :param element: a :class:`.Table` that's the subject
+ :param element: a :class:`_schema.Table` that's the subject
of the CREATE
:param on: See the description for 'on' in :class:`.DDL`.
:param bind: See the description for 'bind' in :class:`.DDL`.
:param include_foreign_key_constraints: optional sequence of
- :class:`.ForeignKeyConstraint` objects that will be included
+ :class:`_schema.ForeignKeyConstraint` objects that will be included
inline within the CREATE construct; if omitted, all foreign key
constraints that do not specify use_alter=True are included.
@@ -400,7 +402,8 @@ class _DropView(_CreateDropBase):
class CreateColumn(_DDLCompiles):
- """Represent a :class:`.Column` as rendered in a CREATE TABLE statement,
+ """Represent a :class:`_schema.Column`
+ as rendered in a CREATE TABLE statement,
via the :class:`.CreateTable` construct.
This is provided to support custom column DDL within the generation
@@ -408,7 +411,7 @@ class CreateColumn(_DDLCompiles):
compiler extension documented in :ref:`sqlalchemy.ext.compiler_toplevel`
to extend :class:`.CreateColumn`.
- Typical integration is to examine the incoming :class:`.Column`
+ Typical integration is to examine the incoming :class:`_schema.Column`
object, and to redirect compilation if a particular flag or condition
is found::
@@ -439,7 +442,8 @@ class CreateColumn(_DDLCompiles):
for const in column.constraints)
return text
- The above construct can be applied to a :class:`.Table` as follows::
+ The above construct can be applied to a :class:`_schema.Table`
+ as follows::
from sqlalchemy import Table, Metadata, Column, Integer, String
from sqlalchemy import schema
@@ -454,7 +458,8 @@ class CreateColumn(_DDLCompiles):
metadata.create_all(conn)
- Above, the directives we've added to the :attr:`.Column.info` collection
+ Above, the directives we've added to the :attr:`_schema.Column.info`
+ collection
will be detected by our custom compilation scheme::
CREATE TABLE mytable (
@@ -468,10 +473,11 @@ class CreateColumn(_DDLCompiles):
columns when producing a ``CREATE TABLE``. This is accomplished by
creating a compilation rule that conditionally returns ``None``.
This is essentially how to produce the same effect as using the
- ``system=True`` argument on :class:`.Column`, which marks a column
+ ``system=True`` argument on :class:`_schema.Column`, which marks a column
as an implicitly-present "system" column.
- For example, suppose we wish to produce a :class:`.Table` which skips
+ For example, suppose we wish to produce a :class:`_schema.Table`
+ which skips
rendering of the PostgreSQL ``xmin`` column against the PostgreSQL
backend, but on other backends does render it, in anticipation of a
triggered rule. A conditional compilation rule could skip this name only
@@ -940,13 +946,16 @@ class SchemaDropper(DDLBase):
def sort_tables(tables, skip_fn=None, extra_dependencies=None):
- """sort a collection of :class:`.Table` objects based on dependency.
+ """sort a collection of :class:`_schema.Table` objects based on dependency
+ .
- This is a dependency-ordered sort which will emit :class:`.Table`
- objects such that they will follow their dependent :class:`.Table` objects.
+ This is a dependency-ordered sort which will emit :class:`_schema.Table`
+ objects such that they will follow their dependent :class:`_schema.Table`
+ objects.
Tables are dependent on another based on the presence of
- :class:`.ForeignKeyConstraint` objects as well as explicit dependencies
- added by :meth:`.Table.add_is_dependent_on`.
+ :class:`_schema.ForeignKeyConstraint`
+ objects as well as explicit dependencies
+ added by :meth:`_schema.Table.add_is_dependent_on`.
.. warning::
@@ -954,19 +963,21 @@ def sort_tables(tables, skip_fn=None, extra_dependencies=None):
automatic resolution of dependency cycles between tables, which
are usually caused by mutually dependent foreign key constraints.
To resolve these cycles, either the
- :paramref:`.ForeignKeyConstraint.use_alter` parameter may be applied
+ :paramref:`_schema.ForeignKeyConstraint.use_alter`
+ parameter may be applied
to those constraints, or use the
- :func:`.sql.sort_tables_and_constraints` function which will break
+ :func:`_expression.sort_tables_and_constraints`
+ function which will break
out foreign key constraints involved in cycles separately.
- :param tables: a sequence of :class:`.Table` objects.
+ :param tables: a sequence of :class:`_schema.Table` objects.
:param skip_fn: optional callable which will be passed a
- :class:`.ForeignKey` object; if it returns True, this
+ :class:`_schema.ForeignKey` object; if it returns True, this
constraint will not be considered as a dependency. Note this is
**different** from the same parameter in
:func:`.sort_tables_and_constraints`, which is
- instead passed the owning :class:`.ForeignKeyConstraint` object.
+ instead passed the owning :class:`_schema.ForeignKeyConstraint` object.
:param extra_dependencies: a sequence of 2-tuples of tables which will
also be considered as dependent on each other.
@@ -975,7 +986,7 @@ def sort_tables(tables, skip_fn=None, extra_dependencies=None):
:func:`.sort_tables_and_constraints`
- :meth:`.MetaData.sorted_tables` - uses this function to sort
+ :meth:`_schema.MetaData.sorted_tables` - uses this function to sort
"""
@@ -1004,27 +1015,32 @@ def sort_tables(tables, skip_fn=None, extra_dependencies=None):
def sort_tables_and_constraints(
tables, filter_fn=None, extra_dependencies=None
):
- """sort a collection of :class:`.Table` / :class:`.ForeignKeyConstraint`
+ """sort a collection of :class:`_schema.Table` /
+ :class:`_schema.ForeignKeyConstraint`
objects.
This is a dependency-ordered sort which will emit tuples of
``(Table, [ForeignKeyConstraint, ...])`` such that each
- :class:`.Table` follows its dependent :class:`.Table` objects.
- Remaining :class:`.ForeignKeyConstraint` objects that are separate due to
+ :class:`_schema.Table` follows its dependent :class:`_schema.Table`
+ objects.
+ Remaining :class:`_schema.ForeignKeyConstraint`
+ objects that are separate due to
dependency rules not satisfied by the sort are emitted afterwards
as ``(None, [ForeignKeyConstraint ...])``.
Tables are dependent on another based on the presence of
- :class:`.ForeignKeyConstraint` objects, explicit dependencies
- added by :meth:`.Table.add_is_dependent_on`, as well as dependencies
+ :class:`_schema.ForeignKeyConstraint` objects, explicit dependencies
+ added by :meth:`_schema.Table.add_is_dependent_on`,
+ as well as dependencies
stated here using the :paramref:`~.sort_tables_and_constraints.skip_fn`
and/or :paramref:`~.sort_tables_and_constraints.extra_dependencies`
parameters.
- :param tables: a sequence of :class:`.Table` objects.
+ :param tables: a sequence of :class:`_schema.Table` objects.
:param filter_fn: optional callable which will be passed a
- :class:`.ForeignKeyConstraint` object, and returns a value based on
+ :class:`_schema.ForeignKeyConstraint` object,
+ and returns a value based on
whether this constraint should definitely be included or excluded as
an inline constraint, or neither. If it returns False, the constraint
will definitely be included as a dependency that cannot be subject
diff --git a/lib/sqlalchemy/sql/dml.py b/lib/sqlalchemy/sql/dml.py
index 1ac3acd8a..bc800de42 100644
--- a/lib/sqlalchemy/sql/dml.py
+++ b/lib/sqlalchemy/sql/dml.py
@@ -5,8 +5,8 @@
# This module is part of SQLAlchemy and is released under
# the MIT License: http://www.opensource.org/licenses/mit-license.php
"""
-Provide :class:`~.sql.expression.Insert`, :class:`.Update` and
-:class:`.Delete`.
+Provide :class:`_expression.Insert`, :class:`_expression.Update` and
+:class:`_expression.Delete`.
"""
from sqlalchemy.types import NullType
@@ -303,7 +303,7 @@ class UpdateBase(
def bind(self):
"""Return a 'bind' linked to this :class:`.UpdateBase`
- or a :class:`.Table` associated with it.
+ or a :class:`_schema.Table` associated with it.
"""
return self._bind or self.table.bind
@@ -330,7 +330,8 @@ class UpdateBase(
The given collection of column expressions should be derived from
the table that is
- the target of the INSERT, UPDATE, or DELETE. While :class:`.Column`
+ the target of the INSERT, UPDATE, or DELETE. While
+ :class:`_schema.Column`
objects are typical, the elements can also be expressions::
stmt = table.insert().returning(
@@ -403,9 +404,9 @@ class UpdateBase(
The text of the hint is rendered in the appropriate
location for the database backend in use, relative
- to the :class:`.Table` that is the subject of this
+ to the :class:`_schema.Table` that is the subject of this
statement, or optionally to that of the given
- :class:`.Table` passed as the ``selectable`` argument.
+ :class:`_schema.Table` passed as the ``selectable`` argument.
The ``dialect_name`` option will limit the rendering of a particular
hint to a particular backend. Such as, to add a hint
@@ -414,7 +415,7 @@ class UpdateBase(
mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql")
:param text: Text of the hint.
- :param selectable: optional :class:`.Table` that specifies
+ :param selectable: optional :class:`_schema.Table` that specifies
an element of the FROM clause within an UPDATE or DELETE
to be the subject of the hint - applies only to certain backends.
:param dialect_name: defaults to ``*``, if specified as the name
@@ -457,10 +458,11 @@ class ValuesBase(UpdateBase):
r"""specify a fixed VALUES clause for an INSERT statement, or the SET
clause for an UPDATE.
- Note that the :class:`~.sql.expression.Insert` and :class:`.Update`
+ Note that the :class:`_expression.Insert` and
+ :class:`_expression.Update`
constructs support
per-execution time formatting of the VALUES and/or SET clauses,
- based on the arguments passed to :meth:`.Connection.execute`.
+ based on the arguments passed to :meth:`_engine.Connection.execute`.
However, the :meth:`.ValuesBase.values` method can be used to "fix" a
particular set of parameters into the statement.
@@ -473,7 +475,8 @@ class ValuesBase(UpdateBase):
onto the existing list of values.
:param \**kwargs: key value pairs representing the string key
- of a :class:`.Column` mapped to the value to be rendered into the
+ of a :class:`_schema.Column`
+ mapped to the value to be rendered into the
VALUES or SET clause::
users.insert().values(name="some name")
@@ -484,10 +487,11 @@ class ValuesBase(UpdateBase):
a dictionary, tuple, or list of dictionaries or tuples can be passed
as a single positional argument in order to form the VALUES or
SET clause of the statement. The forms that are accepted vary
- based on whether this is an :class:`~.sql.expression.Insert` or an
- :class:`.Update` construct.
+ based on whether this is an :class:`_expression.Insert` or an
+ :class:`_expression.Update` construct.
- For either an :class:`~.sql.expression.Insert` or :class:`.Update`
+ For either an :class:`_expression.Insert` or
+ :class:`_expression.Update`
construct, a single dictionary can be passed, which works the same as
that of the kwargs form::
@@ -496,12 +500,12 @@ class ValuesBase(UpdateBase):
users.update().values({"name": "some new name"})
Also for either form but more typically for the
- :class:`~.sql.expression.Insert` construct, a tuple that contains an
+ :class:`_expression.Insert` construct, a tuple that contains an
entry for every column in the table is also accepted::
users.insert().values((5, "some name"))
- The :class:`~.sql.expression.Insert` construct also supports being
+ The :class:`_expression.Insert` construct also supports being
passed a list of dictionaries or full-table-tuples, which on the
server will render the less common SQL syntax of "multiple values" -
this syntax is supported on backends such as SQLite, PostgreSQL,
@@ -524,7 +528,8 @@ class ValuesBase(UpdateBase):
NOT the same as using traditional executemany() form**. The above
syntax is a **special** syntax not typically used. To emit an
INSERT statement against multiple rows, the normal method is
- to pass a multiple values list to the :meth:`.Connection.execute`
+ to pass a multiple values list to the
+ :meth:`_engine.Connection.execute`
method, which is supported by all database backends and is generally
more efficient for a very large number of parameters.
@@ -536,7 +541,8 @@ class ValuesBase(UpdateBase):
.. versionchanged:: 1.0.0 an INSERT that uses a multiple-VALUES
clause, even a list of length one,
- implies that the :paramref:`.Insert.inline` flag is set to
+ implies that the :paramref:`_expression.Insert.inline`
+ flag is set to
True, indicating that the statement will not attempt to fetch
the "last inserted primary key" or other defaults. The
statement deals with an arbitrary number of rows, so the
@@ -551,20 +557,20 @@ class ValuesBase(UpdateBase):
The UPDATE construct also supports rendering the SET parameters
in a specific order. For this feature refer to the
- :meth:`.Update.ordered_values` method.
+ :meth:`_expression.Update.ordered_values` method.
.. seealso::
- :meth:`.Update.ordered_values`
+ :meth:`_expression.Update.ordered_values`
.. seealso::
:ref:`inserts_and_updates` - SQL Expression
Language Tutorial
- :func:`~.expression.insert` - produce an ``INSERT`` statement
+ :func:`_expression.insert` - produce an ``INSERT`` statement
- :func:`~.expression.update` - produce an ``UPDATE`` statement
+ :func:`_expression.update` - produce an ``UPDATE`` statement
"""
if self._select_names:
@@ -677,7 +683,8 @@ class ValuesBase(UpdateBase):
:meth:`.UpdateBase.returning` is not used simultaneously. The column
values will then be available on the result using the
:attr:`.ResultProxy.returned_defaults` accessor as a dictionary,
- referring to values keyed to the :class:`.Column` object as well as
+ referring to values keyed to the :class:`_schema.Column`
+ object as well as
its ``.key``.
This method differs from :meth:`.UpdateBase.returning` in these ways:
@@ -711,7 +718,8 @@ class ValuesBase(UpdateBase):
an efficient implementation for the ``eager_defaults`` feature of
:func:`.mapper`.
- :param cols: optional list of column key names or :class:`.Column`
+ :param cols: optional list of column key names or
+ :class:`_schema.Column`
objects. If omitted, all column expressions evaluated on the server
are added to the returning list.
@@ -730,8 +738,8 @@ class ValuesBase(UpdateBase):
class Insert(ValuesBase):
"""Represent an INSERT construct.
- The :class:`~.sql.expression.Insert` object is created using the
- :func:`~.expression.insert()` function.
+ The :class:`_expression.Insert` object is created using the
+ :func:`_expression.insert()` function.
.. seealso::
@@ -787,20 +795,22 @@ class Insert(ValuesBase):
return_defaults=False,
**dialect_kw
):
- """Construct an :class:`~.sql.expression.Insert` object.
+ """Construct an :class:`_expression.Insert` object.
Similar functionality is available via the
- :meth:`~.TableClause.insert` method on
- :class:`~.schema.Table`.
+ :meth:`_expression.TableClause.insert` method on
+ :class:`_schema.Table`.
- :param table: :class:`.TableClause` which is the subject of the
+ :param table: :class:`_expression.TableClause`
+ which is the subject of the
insert.
:param values: collection of values to be inserted; see
- :meth:`.Insert.values` for a description of allowed formats here.
- Can be omitted entirely; a :class:`~.sql.expression.Insert` construct
+ :meth:`_expression.Insert.values`
+ for a description of allowed formats here.
+ Can be omitted entirely; a :class:`_expression.Insert` construct
will also dynamically render the VALUES clause at execution time
- based on the parameters passed to :meth:`.Connection.execute`.
+ based on the parameters passed to :meth:`_engine.Connection.execute`.
:param inline: if True, no attempt will be made to retrieve the
SQL-generated default values to be provided within the statement;
@@ -845,7 +855,7 @@ class Insert(ValuesBase):
@_generative
def inline(self):
- """Make this :class:`~.sql.expression.Insert` construct "inline" .
+ """Make this :class:`_expression.Insert` construct "inline" .
When set, no attempt will be made to retrieve the
SQL-generated default values to be provided within the statement;
@@ -856,15 +866,16 @@ class Insert(ValuesBase):
returning" feature for the statement.
- .. versionchanged:: 1.4 the :paramref:`.Insert.inline` parameter
- is now superseded by the :meth:`.Insert.inline` method.
+ .. versionchanged:: 1.4 the :paramref:`_expression.Insert.inline`
+ parameter
+ is now superseded by the :meth:`_expression.Insert.inline` method.
"""
self._inline = True
@_generative
def from_select(self, names, select, include_defaults=True):
- """Return a new :class:`~.sql.expression.Insert` construct which represents
+ """Return a new :class:`_expression.Insert` construct which represents
an ``INSERT...FROM SELECT`` statement.
e.g.::
@@ -872,19 +883,21 @@ class Insert(ValuesBase):
sel = select([table1.c.a, table1.c.b]).where(table1.c.c > 5)
ins = table2.insert().from_select(['a', 'b'], sel)
- :param names: a sequence of string column names or :class:`.Column`
+ :param names: a sequence of string column names or
+ :class:`_schema.Column`
objects representing the target columns.
- :param select: a :func:`~.sql.expression.select` construct,
- :class:`.FromClause`
- or other construct which resolves into a :class:`.FromClause`,
- such as an ORM :class:`.Query` object, etc. The order of
+ :param select: a :func:`_expression.select` construct,
+ :class:`_expression.FromClause`
+ or other construct which resolves into a
+ :class:`_expression.FromClause`,
+ such as an ORM :class:`_query.Query` object, etc. The order of
columns returned from this FROM clause should correspond to the
order of columns sent as the ``names`` parameter; while this
is not checked before passing along to the database, the database
would normally raise an exception if these column lists don't
correspond.
:param include_defaults: if True, non-server default values and
- SQL expressions as specified on :class:`.Column` objects
+ SQL expressions as specified on :class:`_schema.Column` objects
(as documented in :ref:`metadata_defaults_toplevel`) not
otherwise specified in the list of names will be rendered
into the INSERT and SELECT statements, so that these values are also
@@ -894,13 +907,15 @@ class Insert(ValuesBase):
will only be invoked **once** for the whole statement, and **not
per row**.
- .. versionadded:: 1.0.0 - :meth:`.Insert.from_select` now renders
+ .. versionadded:: 1.0.0 - :meth:`_expression.Insert.from_select`
+ now renders
Python-side and SQL expression column defaults into the
SELECT statement for columns otherwise not included in the
list of column names.
.. versionchanged:: 1.0.0 an INSERT that uses FROM SELECT
- implies that the :paramref:`.insert.inline` flag is set to
+ implies that the :paramref:`_expression.insert.inline`
+ flag is set to
True, indicating that the statement will not attempt to fetch
the "last inserted primary key" or other defaults. The statement
deals with an arbitrary number of rows, so the
@@ -937,7 +952,8 @@ class DMLWhereBase(object):
class Update(DMLWhereBase, ValuesBase):
"""Represent an Update construct.
- The :class:`.Update` object is created using the :func:`update()`
+ The :class:`_expression.Update`
+ object is created using the :func:`update()`
function.
"""
@@ -987,7 +1003,7 @@ class Update(DMLWhereBase, ValuesBase):
preserve_parameter_order=False,
**dialect_kw
):
- r"""Construct an :class:`.Update` object.
+ r"""Construct an :class:`_expression.Update` object.
E.g.::
@@ -997,14 +1013,15 @@ class Update(DMLWhereBase, ValuesBase):
values(name='user #5')
Similar functionality is available via the
- :meth:`~.TableClause.update` method on
- :class:`.Table`::
+ :meth:`_expression.TableClause.update` method on
+ :class:`_schema.Table`::
stmt = users.update().\
where(users.c.id==5).\
values(name='user #5')
- :param table: A :class:`.Table` object representing the database
+ :param table: A :class:`_schema.Table`
+ object representing the database
table to be updated.
:param whereclause: Optional SQL expression describing the ``WHERE``
@@ -1035,11 +1052,11 @@ class Update(DMLWhereBase, ValuesBase):
the ``SET`` clause generates for all columns.
Modern applications may prefer to use the generative
- :meth:`.Update.values` method to set the values of the
+ :meth:`_expression.Update.values` method to set the values of the
UPDATE statement.
:param inline:
- if True, SQL defaults present on :class:`.Column` objects via
+ if True, SQL defaults present on :class:`_schema.Column` objects via
the ``default`` keyword will be compiled 'inline' into the statement
and not pre-executed. This means that their values will not
be available in the dictionary returned from
@@ -1047,7 +1064,8 @@ class Update(DMLWhereBase, ValuesBase):
:param preserve_parameter_order: if True, the update statement is
expected to receive parameters **only** via the
- :meth:`.Update.values` method, and they must be passed as a Python
+ :meth:`_expression.Update.values` method,
+ and they must be passed as a Python
``list`` of 2-tuples. The rendered UPDATE statement will emit the SET
clause for each referenced column maintaining this order.
@@ -1056,18 +1074,18 @@ class Update(DMLWhereBase, ValuesBase):
.. seealso::
:ref:`updates_order_parameters` - illustrates the
- :meth:`.Update.ordered_values` method.
+ :meth:`_expression.Update.ordered_values` method.
If both ``values`` and compile-time bind parameters are present, the
compile-time bind parameters override the information specified
within ``values`` on a per-key basis.
- The keys within ``values`` can be either :class:`.Column`
+ The keys within ``values`` can be either :class:`_schema.Column`
objects or their string identifiers (specifically the "key" of the
- :class:`.Column`, normally but not necessarily equivalent to
+ :class:`_schema.Column`, normally but not necessarily equivalent to
its "name"). Normally, the
- :class:`.Column` objects used here are expected to be
- part of the target :class:`.Table` that is the table
+ :class:`_schema.Column` objects used here are expected to be
+ part of the target :class:`_schema.Table` that is the table
to be updated. However when using MySQL, a multiple-table
UPDATE statement can refer to columns from any of
the tables referred to in the WHERE clause.
@@ -1075,14 +1093,14 @@ class Update(DMLWhereBase, ValuesBase):
The values referred to in ``values`` are typically:
* a literal data value (i.e. string, number, etc.)
- * a SQL expression, such as a related :class:`.Column`,
- a scalar-returning :func:`~.sql.expression.select` construct,
+ * a SQL expression, such as a related :class:`_schema.Column`,
+ a scalar-returning :func:`_expression.select` construct,
etc.
- when combining :func:`~.sql.expression.select` constructs within the
- values clause of an :func:`.update`
+ when combining :func:`_expression.select` constructs within the
+ values clause of an :func:`_expression.update`
construct, the subquery represented
- by the :func:`~.sql.expression.select` should be *correlated* to the
+ by the :func:`_expression.select` should be *correlated* to the
parent table, that is, providing criterion which links the table inside
the subquery to the outer table being updated::
@@ -1127,10 +1145,12 @@ class Update(DMLWhereBase, ValuesBase):
.. seealso::
:ref:`updates_order_parameters` - full example of the
- :meth:`.Update.ordered_values` method.
+ :meth:`_expression.Update.ordered_values` method.
- .. versionchanged:: 1.4 The :meth:`.Update.ordered_values` method
- supersedes the :paramref:`.update.preserve_parameter_order`
+ .. versionchanged:: 1.4 The :meth:`_expression.Update.ordered_values`
+ method
+ supersedes the
+ :paramref:`_expression.update.preserve_parameter_order`
parameter, which will be removed in SQLAlchemy 2.0.
"""
@@ -1158,16 +1178,18 @@ class Update(DMLWhereBase, ValuesBase):
@_generative
def inline(self):
- """Make this :class:`.Update` construct "inline" .
+ """Make this :class:`_expression.Update` construct "inline" .
- When set, SQL defaults present on :class:`.Column` objects via the
+ When set, SQL defaults present on :class:`_schema.Column`
+ objects via the
``default`` keyword will be compiled 'inline' into the statement and
not pre-executed. This means that their values will not be available
in the dictionary returned from
:meth:`.ResultProxy.last_updated_params`.
- .. versionchanged:: 1.4 the :paramref:`.update.inline` parameter
- is now superseded by the :meth:`.Update.inline` method.
+ .. versionchanged:: 1.4 the :paramref:`_expression.update.inline`
+ parameter
+ is now superseded by the :meth:`_expression.Update.inline` method.
"""
self._inline = True
@@ -1176,7 +1198,8 @@ class Update(DMLWhereBase, ValuesBase):
class Delete(DMLWhereBase, UpdateBase):
"""Represent a DELETE construct.
- The :class:`.Delete` object is created using the :func:`delete()`
+ The :class:`_expression.Delete`
+ object is created using the :func:`delete()`
function.
"""
@@ -1210,15 +1233,16 @@ class Delete(DMLWhereBase, UpdateBase):
prefixes=None,
**dialect_kw
):
- r"""Construct :class:`.Delete` object.
+ r"""Construct :class:`_expression.Delete` object.
Similar functionality is available via the
- :meth:`~.TableClause.delete` method on
- :class:`~.schema.Table`.
+ :meth:`_expression.TableClause.delete` method on
+ :class:`_schema.Table`.
:param table: The table to delete rows from.
- :param whereclause: A :class:`.ClauseElement` describing the ``WHERE``
+ :param whereclause: A :class:`_expression.ClauseElement`
+ describing the ``WHERE``
condition of the ``DELETE`` statement. Note that the
:meth:`~Delete.where()` generative method may be used instead.
diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py
index 9689c7a8a..49bb08644 100644
--- a/lib/sqlalchemy/sql/elements.py
+++ b/lib/sqlalchemy/sql/elements.py
@@ -5,8 +5,8 @@
# This module is part of SQLAlchemy and is released under
# the MIT License: http://www.opensource.org/licenses/mit-license.php
-"""Core SQL expression elements, including :class:`.ClauseElement`,
-:class:`.ColumnElement`, and derived classes.
+"""Core SQL expression elements, including :class:`_expression.ClauseElement`,
+:class:`_expression.ColumnElement`, and derived classes.
"""
@@ -88,14 +88,15 @@ def between(expr, lower_bound, upper_bound, symmetric=False):
SELECT id, name FROM user WHERE id BETWEEN :id_1 AND :id_2
The :func:`.between` function is a standalone version of the
- :meth:`.ColumnElement.between` method available on all
+ :meth:`_expression.ColumnElement.between` method available on all
SQL expressions, as in::
stmt = select([users_table]).where(users_table.c.id.between(5, 7))
All arguments passed to :func:`.between`, including the left side
column expression, are coerced from Python scalar values if a
- the value is not a :class:`.ColumnElement` subclass. For example,
+ the value is not a :class:`_expression.ColumnElement` subclass.
+ For example,
three fixed values can be compared as in::
print(between(5, 3, 7))
@@ -104,7 +105,8 @@ def between(expr, lower_bound, upper_bound, symmetric=False):
:param_1 BETWEEN :param_2 AND :param_3
- :param expr: a column expression, typically a :class:`.ColumnElement`
+ :param expr: a column expression, typically a
+ :class:`_expression.ColumnElement`
instance or alternatively a Python scalar expression to be coerced
into a column expression, serving as the left side of the ``BETWEEN``
expression.
@@ -122,7 +124,7 @@ def between(expr, lower_bound, upper_bound, symmetric=False):
.. seealso::
- :meth:`.ColumnElement.between`
+ :meth:`_expression.ColumnElement.between`
"""
expr = coercions.expect(roles.ExpressionElementRole, expr)
@@ -133,8 +135,10 @@ def literal(value, type_=None):
r"""Return a literal clause, bound to a bind parameter.
Literal clauses are created automatically when non-
- :class:`.ClauseElement` objects (such as strings, ints, dates, etc.) are
- used in a comparison operation with a :class:`.ColumnElement` subclass,
+ :class:`_expression.ClauseElement` objects (such as strings, ints, dates,
+ etc.) are
+ used in a comparison operation with a :class:`_expression.ColumnElement`
+ subclass,
such as a :class:`~sqlalchemy.schema.Column` object. Use this function
to force the generation of a literal clause, which will be created as a
:class:`BindParameter` with a bound value.
@@ -166,7 +170,7 @@ def not_(clause):
"""Return a negation of the given clause, i.e. ``NOT(clause)``.
The ``~`` operator is also overloaded on all
- :class:`.ColumnElement` subclasses to produce the
+ :class:`_expression.ColumnElement` subclasses to produce the
same result.
"""
@@ -232,7 +236,7 @@ class ClauseElement(
"""in the context of binary expression, convert the type of this
object to the one given.
- applies only to :class:`.ColumnElement` classes.
+ applies only to :class:`_expression.ColumnElement` classes.
"""
return self
@@ -334,7 +338,7 @@ class ClauseElement(
\**kw are arguments consumed by subclass compare() methods and
may be used to modify the criteria for comparison.
- (see :class:`.ColumnElement`)
+ (see :class:`_expression.ColumnElement`)
"""
return traversals.compare(self, other, **kw)
@@ -396,15 +400,16 @@ class ClauseElement(
def self_group(self, against=None):
# type: (Optional[Any]) -> ClauseElement
- """Apply a 'grouping' to this :class:`.ClauseElement`.
+ """Apply a 'grouping' to this :class:`_expression.ClauseElement`.
This method is overridden by subclasses to return a "grouping"
construct, i.e. parenthesis. In particular it's used by "binary"
expressions to provide a grouping around themselves when placed into a
- larger expression, as well as by :func:`~.sql.expression.select`
+ larger expression, as well as by :func:`_expression.select`
constructs when placed into the FROM clause of another
- :func:`~.sql.expression.select`. (Note that subqueries should be
- normally created using the :meth:`.Select.alias` method, as many
+ :func:`_expression.select`. (Note that subqueries should be
+ normally created using the :meth:`_expression.Select.alias` method,
+ as many
platforms require nested SELECT statements to be named).
As expressions are composed together, the application of
@@ -415,13 +420,15 @@ class ClauseElement(
an expression like ``x OR (y AND z)`` - AND takes precedence
over OR.
- The base :meth:`self_group` method of :class:`.ClauseElement`
+ The base :meth:`self_group` method of
+ :class:`_expression.ClauseElement`
just returns self.
"""
return self
def _ungroup(self):
- """Return this :class:`.ClauseElement` without any groupings."""
+ """Return this :class:`_expression.ClauseElement` """
+ """without any groupings."""
return self
@@ -438,7 +445,7 @@ class ClauseElement(
:param bind: An ``Engine`` or ``Connection`` from which a
``Compiled`` will be acquired. This argument takes precedence over
- this :class:`.ClauseElement`'s bound engine, if any.
+ this :class:`_expression.ClauseElement`'s bound engine, if any.
:param column_keys: Used for INSERT and UPDATE statements, a list of
column names which should be present in the VALUES clause of the
@@ -447,7 +454,8 @@ class ClauseElement(
:param dialect: A ``Dialect`` instance from which a ``Compiled``
will be acquired. This argument takes precedence over the `bind`
- argument as well as this :class:`.ClauseElement`'s bound engine,
+ argument as well as this :class:`_expression.ClauseElement`
+ 's bound engine,
if any.
:param inline: Used for INSERT statements, for a dialect which does
@@ -553,19 +561,23 @@ class ColumnElement(
"""Represent a column-oriented SQL expression suitable for usage in the
"columns" clause, WHERE clause etc. of a statement.
- While the most familiar kind of :class:`.ColumnElement` is the
- :class:`.Column` object, :class:`.ColumnElement` serves as the basis
+ While the most familiar kind of :class:`_expression.ColumnElement` is the
+ :class:`_schema.Column` object, :class:`_expression.ColumnElement`
+ serves as the basis
for any unit that may be present in a SQL expression, including
the expressions themselves, SQL functions, bound parameters,
literal expressions, keywords such as ``NULL``, etc.
- :class:`.ColumnElement` is the ultimate base class for all such elements.
+ :class:`_expression.ColumnElement`
+ is the ultimate base class for all such elements.
A wide variety of SQLAlchemy Core functions work at the SQL expression
- level, and are intended to accept instances of :class:`.ColumnElement` as
+ level, and are intended to accept instances of
+ :class:`_expression.ColumnElement` as
arguments. These functions will typically document that they accept a
"SQL expression" as an argument. What this means in terms of SQLAlchemy
usually refers to an input which is either already in the form of a
- :class:`.ColumnElement` object, or a value which can be **coerced** into
+ :class:`_expression.ColumnElement` object,
+ or a value which can be **coerced** into
one. The coercion rules followed by most, but not all, SQLAlchemy Core
functions with regards to SQL expressions are as follows:
@@ -575,7 +587,8 @@ class ColumnElement(
value". This generally means that a :func:`.bindparam` will be
produced featuring the given value embedded into the construct; the
resulting :class:`.BindParameter` object is an instance of
- :class:`.ColumnElement`. The Python value will ultimately be sent
+ :class:`_expression.ColumnElement`.
+ The Python value will ultimately be sent
to the DBAPI at execution time as a parameterized argument to the
``execute()`` or ``executemany()`` methods, after SQLAlchemy
type-specific converters (e.g. those provided by any associated
@@ -585,25 +598,28 @@ class ColumnElement(
feature an accessor called ``__clause_element__()``. The Core
expression system looks for this method when an object of otherwise
unknown type is passed to a function that is looking to coerce the
- argument into a :class:`.ColumnElement` and sometimes a
- :class:`.SelectBase` expression. It is used within the ORM to
+ argument into a :class:`_expression.ColumnElement` and sometimes a
+ :class:`_expression.SelectBase` expression.
+ It is used within the ORM to
convert from ORM-specific objects like mapped classes and
mapped attributes into Core expression objects.
* The Python ``None`` value is typically interpreted as ``NULL``,
which in SQLAlchemy Core produces an instance of :func:`.null`.
- A :class:`.ColumnElement` provides the ability to generate new
- :class:`.ColumnElement`
+ A :class:`_expression.ColumnElement` provides the ability to generate new
+ :class:`_expression.ColumnElement`
objects using Python expressions. This means that Python operators
such as ``==``, ``!=`` and ``<`` are overloaded to mimic SQL operations,
- and allow the instantiation of further :class:`.ColumnElement` instances
- which are composed from other, more fundamental :class:`.ColumnElement`
+ and allow the instantiation of further :class:`_expression.ColumnElement`
+ instances
+ which are composed from other, more fundamental
+ :class:`_expression.ColumnElement`
objects. For example, two :class:`.ColumnClause` objects can be added
together with the addition operator ``+`` to produce
a :class:`.BinaryExpression`.
Both :class:`.ColumnClause` and :class:`.BinaryExpression` are subclasses
- of :class:`.ColumnElement`::
+ of :class:`_expression.ColumnElement`::
>>> from sqlalchemy.sql import column
>>> column('a') + column('b')
@@ -613,9 +629,9 @@ class ColumnElement(
.. seealso::
- :class:`.Column`
+ :class:`_schema.Column`
- :func:`.expression.column`
+ :func:`_expression.column`
"""
@@ -801,8 +817,8 @@ class ColumnElement(
return s
def shares_lineage(self, othercolumn):
- """Return True if the given :class:`.ColumnElement`
- has a common ancestor to this :class:`.ColumnElement`."""
+ """Return True if the given :class:`_expression.ColumnElement`
+ has a common ancestor to this :class:`_expression.ColumnElement`."""
return bool(self.proxy_set.intersection(othercolumn.proxy_set))
@@ -829,8 +845,9 @@ class ColumnElement(
def _make_proxy(
self, selectable, name=None, name_is_truncatable=False, **kw
):
- """Create a new :class:`.ColumnElement` representing this
- :class:`.ColumnElement` as it appears in the select list of a
+ """Create a new :class:`_expression.ColumnElement` representing this
+ :class:`_expression.ColumnElement`
+ as it appears in the select list of a
descending selectable.
"""
@@ -854,15 +871,15 @@ class ColumnElement(
def cast(self, type_):
"""Produce a type cast, i.e. ``CAST(<expression> AS <type>)``.
- This is a shortcut to the :func:`~.expression.cast` function.
+ This is a shortcut to the :func:`_expression.cast` function.
.. seealso::
:ref:`coretutorial_casts`
- :func:`~.expression.cast`
+ :func:`_expression.cast`
- :func:`~.expression.type_coerce`
+ :func:`_expression.type_coerce`
.. versionadded:: 1.0.7
@@ -872,7 +889,7 @@ class ColumnElement(
def label(self, name):
"""Produce a column label, i.e. ``<columnname> AS <name>``.
- This is a shortcut to the :func:`~.expression.label` function.
+ This is a shortcut to the :func:`_expression.label` function.
if 'name' is None, an anonymous label name will be generated.
@@ -923,7 +940,8 @@ class ColumnElement(
class WrapsColumnExpression(object):
- """Mixin that defines a :class:`.ColumnElement` as a wrapper with special
+ """Mixin that defines a :class:`_expression.ColumnElement`
+ as a wrapper with special
labeling behavior for an expression that already has a name.
.. versionadded:: 1.4
@@ -1011,7 +1029,8 @@ class BindParameter(roles.InElementRole, ColumnElement):
r"""Produce a "bound expression".
The return value is an instance of :class:`.BindParameter`; this
- is a :class:`.ColumnElement` subclass which represents a so-called
+ is a :class:`_expression.ColumnElement`
+ subclass which represents a so-called
"placeholder" value in a SQL expression, the value of which is
supplied at the point at which the statement in executed against a
database connection.
@@ -1041,7 +1060,7 @@ class BindParameter(roles.InElementRole, ColumnElement):
In order to populate the value of ``:username`` above, the value
would typically be applied at execution time to a method
- like :meth:`.Connection.execute`::
+ like :meth:`_engine.Connection.execute`::
result = connection.execute(stmt, username='wendy')
@@ -1070,7 +1089,7 @@ class BindParameter(roles.InElementRole, ColumnElement):
expr = users_table.c.name == 'Wendy'
The above expression will produce a :class:`.BinaryExpression`
- construct, where the left side is the :class:`.Column` object
+ construct, where the left side is the :class:`_schema.Column` object
representing the ``name`` column, and the right side is a
:class:`.BindParameter` representing the literal value::
@@ -1102,7 +1121,7 @@ class BindParameter(roles.InElementRole, ColumnElement):
Similarly, :func:`.bindparam` is invoked automatically when working
with :term:`CRUD` statements as far as the "VALUES" portion is
- concerned. The :func:`~.sql.expression.insert` construct produces an
+ concerned. The :func:`_expression.insert` construct produces an
``INSERT`` expression which will, at statement execution time, generate
bound placeholders based on the arguments passed, as in::
@@ -1114,10 +1133,10 @@ class BindParameter(roles.InElementRole, ColumnElement):
INSERT INTO "user" (name) VALUES (%(name)s)
{'name': 'Wendy'}
- The :class:`~.sql.expression.Insert` construct, at
+ The :class:`_expression.Insert` construct, at
compilation/execution time, rendered a single :func:`.bindparam`
mirroring the column name ``name`` as a result of the single ``name``
- parameter we passed to the :meth:`.Connection.execute` method.
+ parameter we passed to the :meth:`_engine.Connection.execute` method.
:param key:
the key (e.g. the name) for this bind param.
@@ -1440,12 +1459,13 @@ class TextClause(
result = connection.execute(t)
- The :class:`.Text` construct is produced using the :func:`.text`
+ The :class:`_expression.TextClause` construct is produced using the
+ :func:`_expression.text`
function; see that function for full documentation.
.. seealso::
- :func:`.text`
+ :func:`_expression.text`
"""
@@ -1501,7 +1521,8 @@ class TextClause(
@classmethod
@_document_text_coercion("text", ":func:`.text`", ":paramref:`.text.text`")
def _create_text(cls, text, bind=None):
- r"""Construct a new :class:`.TextClause` clause, representing
+ r"""Construct a new :class:`_expression.TextClause` clause,
+ representing
a textual SQL string directly.
E.g.::
@@ -1511,7 +1532,8 @@ class TextClause(
t = text("SELECT * FROM users")
result = connection.execute(t)
- The advantages :func:`.text` provides over a plain string are
+ The advantages :func:`_expression.text`
+ provides over a plain string are
backend-neutral support for bind parameters, per-statement
execution options, as well as
bind parameter and result-column typing behavior, allowing
@@ -1531,12 +1553,15 @@ class TextClause(
t = text("SELECT * FROM users WHERE name='\:username'")
- The :class:`.TextClause` construct includes methods which can
+ The :class:`_expression.TextClause`
+ construct includes methods which can
provide information about the bound parameters as well as the column
values which would be returned from the textual statement, assuming
it's an executable SELECT type of statement. The
- :meth:`.TextClause.bindparams` method is used to provide bound
- parameter detail, and :meth:`.TextClause.columns` method allows
+ :meth:`_expression.TextClause.bindparams`
+ method is used to provide bound
+ parameter detail, and :meth:`_expression.TextClause.columns`
+ method allows
specification of return columns including names and types::
t = text("SELECT * FROM users WHERE id=:user_id").\
@@ -1546,19 +1571,20 @@ class TextClause(
for id, name in connection.execute(t):
print(id, name)
- The :func:`.text` construct is used in cases when
+ The :func:`_expression.text` construct is used in cases when
a literal string SQL fragment is specified as part of a larger query,
such as for the WHERE clause of a SELECT statement::
s = select([users.c.id, users.c.name]).where(text("id=:user_id"))
result = connection.execute(s, user_id=12)
- :func:`.text` is also used for the construction
+ :func:`_expression.text` is also used for the construction
of a full, standalone statement using plain text.
As such, SQLAlchemy refers
to it as an :class:`.Executable` object, and it supports
the :meth:`Executable.execution_options` method. For example,
- a :func:`.text` construct that should be subject to "autocommit"
+ a :func:`_expression.text`
+ construct that should be subject to "autocommit"
can be set explicitly so using the
:paramref:`.Connection.execution_options.autocommit` option::
@@ -1566,7 +1592,8 @@ class TextClause(
execution_options(autocommit=True)
Note that SQLAlchemy's usual "autocommit" behavior applies to
- :func:`.text` constructs implicitly - that is, statements which begin
+ :func:`_expression.text` constructs implicitly - that is,
+ statements which begin
with a phrase such as ``INSERT``, ``UPDATE``, ``DELETE``,
or a variety of other phrases specific to certain backends, will
be eligible for autocommit if no transaction is in progress.
@@ -1591,7 +1618,7 @@ class TextClause(
@_generative
def bindparams(self, *binds, **names_to_values):
"""Establish the values and/or types of bound parameters within
- this :class:`.TextClause` construct.
+ this :class:`_expression.TextClause` construct.
Given a text construct such as::
@@ -1599,7 +1626,8 @@ class TextClause(
stmt = text("SELECT id, name FROM user WHERE name=:name "
"AND timestamp=:timestamp")
- the :meth:`.TextClause.bindparams` method can be used to establish
+ the :meth:`_expression.TextClause.bindparams`
+ method can be used to establish
the initial value of ``:name`` and ``:timestamp``,
using simple keyword arguments::
@@ -1635,10 +1663,12 @@ class TextClause(
result = connection.execute(stmt,
timestamp=datetime.datetime(2012, 10, 8, 15, 12, 5))
- The :meth:`.TextClause.bindparams` method can be called repeatedly,
+ The :meth:`_expression.TextClause.bindparams`
+ method can be called repeatedly,
where it will re-use existing :class:`.BindParameter` objects to add
new information. For example, we can call
- :meth:`.TextClause.bindparams` first with typing information, and a
+ :meth:`_expression.TextClause.bindparams`
+ first with typing information, and a
second time with value information, and it will be combined::
stmt = text("SELECT id, name FROM user WHERE name=:name "
@@ -1652,10 +1682,12 @@ class TextClause(
timestamp=datetime.datetime(2012, 10, 8, 15, 12, 5)
)
- The :meth:`.TextClause.bindparams` method also supports the concept of
+ The :meth:`_expression.TextClause.bindparams`
+ method also supports the concept of
**unique** bound parameters. These are parameters that are
"uniquified" on name at statement compilation time, so that multiple
- :func:`.text` constructs may be combined together without the names
+ :func:`_expression.text`
+ constructs may be combined together without the names
conflicting. To use this feature, specify the
:paramref:`.BindParameter.unique` flag on each :func:`.bindparam`
object::
@@ -1678,7 +1710,8 @@ class TextClause(
UNION ALL select id from table where name=:name_2
.. versionadded:: 1.3.11 Added support for the
- :paramref:`.BindParameter.unique` flag to work with :func:`.text`
+ :paramref:`.BindParameter.unique` flag to work with
+ :func:`_expression.text`
constructs.
"""
@@ -1717,13 +1750,16 @@ class TextClause(
@util.preload_module("sqlalchemy.sql.selectable")
def columns(self, *cols, **types):
- r"""Turn this :class:`.TextClause` object into a
- :class:`.TextualSelect` object that serves the same role as a SELECT
+ r"""Turn this :class:`_expression.TextClause` object into a
+ :class:`_expression.TextualSelect`
+ object that serves the same role as a SELECT
statement.
- The :class:`.TextualSelect` is part of the :class:`.SelectBase`
+ The :class:`_expression.TextualSelect` is part of the
+ :class:`_expression.SelectBase`
hierarchy and can be embedded into another statement by using the
- :meth:`.TextualSelect.subquery` method to produce a :class:`.Subquery`
+ :meth:`_expression.TextualSelect.subquery` method to produce a
+ :class:`.Subquery`
object, which can then be SELECTed from.
This function essentially bridges the gap between an entirely
@@ -1740,14 +1776,17 @@ class TextClause(
mytable.join(stmt, mytable.c.name == stmt.c.name)
).where(stmt.c.id > 5)
- Above, we pass a series of :func:`.column` elements to the
- :meth:`.TextClause.columns` method positionally. These :func:`.column`
+ Above, we pass a series of :func:`_expression.column` elements to the
+ :meth:`_expression.TextClause.columns` method positionally. These
+ :func:`_expression.column`
elements now become first class elements upon the
- :attr:`.TextualSelect.selected_columns` column collection, which then
+ :attr:`_expression.TextualSelect.selected_columns` column collection,
+ which then
become part of the :attr:`.Subquery.c` collection after
- :meth:`.TextualSelect.subquery` is invoked.
+ :meth:`_expression.TextualSelect.subquery` is invoked.
- The column expressions we pass to :meth:`.TextClause.columns` may
+ The column expressions we pass to
+ :meth:`_expression.TextClause.columns` may
also be typed; when we do so, these :class:`.TypeEngine` objects become
the effective return type of the column, so that SQLAlchemy's
result-set-processing systems may be used on the return values.
@@ -1777,10 +1816,12 @@ class TextClause(
for id, name, timestamp in connection.execute(stmt):
print(id, name, timestamp)
- The positional form of :meth:`.TextClause.columns` also provides the
+ The positional form of :meth:`_expression.TextClause.columns`
+ also provides the
unique feature of **positional column targeting**, which is
particularly useful when using the ORM with complex textual queries. If
- we specify the columns from our model to :meth:`.TextClause.columns`,
+ we specify the columns from our model to
+ :meth:`_expression.TextClause.columns`,
the result set will match to those columns positionally, meaning the
name or origin of the column in the textual SQL doesn't matter::
@@ -1798,20 +1839,24 @@ class TextClause(
query = session.query(User).from_statement(stmt).options(
contains_eager(User.addresses))
- .. versionadded:: 1.1 the :meth:`.TextClause.columns` method now
+ .. versionadded:: 1.1 the :meth:`_expression.TextClause.columns`
+ method now
offers positional column targeting in the result set when
the column expressions are passed purely positionally.
- The :meth:`.TextClause.columns` method provides a direct
- route to calling :meth:`.FromClause.subquery` as well as
- :meth:`.SelectBase.cte` against a textual SELECT statement::
+ The :meth:`_expression.TextClause.columns` method provides a direct
+ route to calling :meth:`_expression.FromClause.subquery` as well as
+ :meth:`_expression.SelectBase.cte`
+ against a textual SELECT statement::
stmt = stmt.columns(id=Integer, name=String).cte('st')
stmt = select([sometable]).where(sometable.c.id == stmt.c.id)
- :param \*cols: A series of :class:`.ColumnElement` objects, typically
- :class:`.Column` objects from a :class:`.Table` or ORM level
+ :param \*cols: A series of :class:`_expression.ColumnElement` objects,
+ typically
+ :class:`_schema.Column` objects from a :class:`_schema.Table`
+ or ORM level
column-mapped attributes, representing a set of columns that this
textual string will SELECT from.
@@ -2212,7 +2257,8 @@ class BooleanClauseList(ClauseList, ColumnElement):
)
The :func:`.and_` operation is also implicit in some cases;
- the :meth:`.Select.where` method for example can be invoked multiple
+ the :meth:`_expression.Select.where`
+ method for example can be invoked multiple
times against a statement, which will have the effect of each
clause being combined using :func:`.and_`::
@@ -2477,9 +2523,11 @@ class Case(ColumnElement):
The values which are accepted as result values in
:paramref:`.case.whens` as well as with :paramref:`.case.else_` are
coerced from Python literals into :func:`.bindparam` constructs.
- SQL expressions, e.g. :class:`.ColumnElement` constructs, are accepted
+ SQL expressions, e.g. :class:`_expression.ColumnElement` constructs,
+ are accepted
as well. To coerce a literal string expression into a constant
- expression rendered inline, use the :func:`.literal_column` construct,
+ expression rendered inline, use the :func:`_expression.literal_column`
+ construct,
as in::
from sqlalchemy import case, literal_column
@@ -2595,13 +2643,16 @@ class Case(ColumnElement):
def literal_column(text, type_=None):
r"""Produce a :class:`.ColumnClause` object that has the
- :paramref:`.column.is_literal` flag set to True.
+ :paramref:`_expression.column.is_literal` flag set to True.
- :func:`.literal_column` is similar to :func:`.column`, except that
+ :func:`_expression.literal_column` is similar to
+ :func:`_expression.column`, except that
it is more often used as a "standalone" column expression that renders
- exactly as stated; while :func:`.column` stores a string name that
+ exactly as stated; while :func:`_expression.column`
+ stores a string name that
will be assumed to be part of a table and may be quoted as such,
- :func:`.literal_column` can be that, or any other arbitrary column-oriented
+ :func:`_expression.literal_column` can be that,
+ or any other arbitrary column-oriented
expression.
:param text: the text of the expression; can be any SQL expression.
@@ -2616,9 +2667,9 @@ def literal_column(text, type_=None):
.. seealso::
- :func:`.column`
+ :func:`_expression.column`
- :func:`.text`
+ :func:`_expression.text`
:ref:`sqlexpression_literal_column`
@@ -2695,7 +2746,8 @@ class Cast(WrapsColumnExpression, ColumnElement):
with a specific type, but does not render the ``CAST`` expression
in SQL.
- :param expression: A SQL expression, such as a :class:`.ColumnElement`
+ :param expression: A SQL expression, such as a
+ :class:`_expression.ColumnElement`
expression or a Python string which will be coerced into a bound
literal value.
@@ -2730,7 +2782,7 @@ class Cast(WrapsColumnExpression, ColumnElement):
class TypeCoerce(WrapsColumnExpression, ColumnElement):
"""Represent a Python-side type-coercion wrapper.
- :class:`.TypeCoerce` supplies the :func:`.expression.type_coerce`
+ :class:`.TypeCoerce` supplies the :func:`_expression.type_coerce`
function; see that function for usage details.
.. versionchanged:: 1.1 The :func:`.type_coerce` function now produces
@@ -2739,7 +2791,7 @@ class TypeCoerce(WrapsColumnExpression, ColumnElement):
.. seealso::
- :func:`.expression.type_coerce`
+ :func:`_expression.type_coerce`
:func:`.cast`
@@ -2776,7 +2828,7 @@ class TypeCoerce(WrapsColumnExpression, ColumnElement):
column remains separate in the list of result columns vs. other
type-coerced or direct values of the target column. In order to
provide a named label for the expression, use
- :meth:`.ColumnElement.label`::
+ :meth:`_expression.ColumnElement.label`::
stmt = select([
type_coerce(
@@ -2801,7 +2853,8 @@ class TypeCoerce(WrapsColumnExpression, ColumnElement):
except that it does not render the ``CAST`` expression in the resulting
statement.
- :param expression: A SQL expression, such as a :class:`.ColumnElement`
+ :param expression: A SQL expression, such as a
+ :class:`_expression.ColumnElement`
expression or a Python string which will be coerced into a bound
literal value.
@@ -2961,7 +3014,8 @@ class UnaryExpression(ColumnElement):
Like :func:`.asc` and :func:`.desc`, :func:`.nullsfirst` is typically
invoked from the column expression itself using
- :meth:`.ColumnElement.nullsfirst`, rather than as its standalone
+ :meth:`_expression.ColumnElement.nullsfirst`,
+ rather than as its standalone
function version, as in::
stmt = (select([users_table]).
@@ -2976,7 +3030,7 @@ class UnaryExpression(ColumnElement):
:func:`.nullslast`
- :meth:`.Select.order_by`
+ :meth:`_expression.Select.order_by`
"""
return UnaryExpression(
@@ -3005,7 +3059,8 @@ class UnaryExpression(ColumnElement):
Like :func:`.asc` and :func:`.desc`, :func:`.nullslast` is typically
invoked from the column expression itself using
- :meth:`.ColumnElement.nullslast`, rather than as its standalone
+ :meth:`_expression.ColumnElement.nullslast`,
+ rather than as its standalone
function version, as in::
stmt = select([users_table]).\
@@ -3019,7 +3074,7 @@ class UnaryExpression(ColumnElement):
:func:`.nullsfirst`
- :meth:`.Select.order_by`
+ :meth:`_expression.Select.order_by`
"""
return UnaryExpression(
@@ -3043,13 +3098,15 @@ class UnaryExpression(ColumnElement):
SELECT id, name FROM user ORDER BY name DESC
The :func:`.desc` function is a standalone version of the
- :meth:`.ColumnElement.desc` method available on all SQL expressions,
+ :meth:`_expression.ColumnElement.desc`
+ method available on all SQL expressions,
e.g.::
stmt = select([users_table]).order_by(users_table.c.name.desc())
- :param column: A :class:`.ColumnElement` (e.g. scalar SQL expression)
+ :param column: A :class:`_expression.ColumnElement` (e.g.
+ scalar SQL expression)
with which to apply the :func:`.desc` operation.
.. seealso::
@@ -3060,7 +3117,7 @@ class UnaryExpression(ColumnElement):
:func:`.nullslast`
- :meth:`.Select.order_by`
+ :meth:`_expression.Select.order_by`
"""
return UnaryExpression(
@@ -3083,13 +3140,15 @@ class UnaryExpression(ColumnElement):
SELECT id, name FROM user ORDER BY name ASC
The :func:`.asc` function is a standalone version of the
- :meth:`.ColumnElement.asc` method available on all SQL expressions,
+ :meth:`_expression.ColumnElement.asc`
+ method available on all SQL expressions,
e.g.::
stmt = select([users_table]).order_by(users_table.c.name.asc())
- :param column: A :class:`.ColumnElement` (e.g. scalar SQL expression)
+ :param column: A :class:`_expression.ColumnElement` (e.g.
+ scalar SQL expression)
with which to apply the :func:`.asc` operation.
.. seealso::
@@ -3100,7 +3159,7 @@ class UnaryExpression(ColumnElement):
:func:`.nullslast`
- :meth:`.Select.order_by`
+ :meth:`_expression.Select.order_by`
"""
return UnaryExpression(
@@ -3125,12 +3184,13 @@ class UnaryExpression(ColumnElement):
SELECT COUNT(DISTINCT name) FROM user
The :func:`.distinct` function is also available as a column-level
- method, e.g. :meth:`.ColumnElement.distinct`, as in::
+ method, e.g. :meth:`_expression.ColumnElement.distinct`, as in::
stmt = select([func.count(users_table.c.name.distinct())])
The :func:`.distinct` operator is different from the
- :meth:`.Select.distinct` method of :class:`.Select`,
+ :meth:`_expression.Select.distinct` method of
+ :class:`_expression.Select`,
which produces a ``SELECT`` statement
with ``DISTINCT`` applied to the result set as a whole,
e.g. a ``SELECT DISTINCT`` expression. See that method for further
@@ -3138,9 +3198,9 @@ class UnaryExpression(ColumnElement):
.. seealso::
- :meth:`.ColumnElement.distinct`
+ :meth:`_expression.ColumnElement.distinct`
- :meth:`.Select.distinct`
+ :meth:`_expression.Select.distinct`
:data:`.func`
@@ -3210,7 +3270,7 @@ class CollectionAggregate(UnaryExpression):
.. seealso::
- :func:`.expression.all_`
+ :func:`_expression.all_`
"""
@@ -3241,7 +3301,7 @@ class CollectionAggregate(UnaryExpression):
.. seealso::
- :func:`.expression.any_`
+ :func:`_expression.any_`
"""
@@ -3551,7 +3611,7 @@ class Over(ColumnElement):
Used against aggregate or so-called "window" functions,
for database backends that support window functions.
- :func:`~.expression.over` is usually called using
+ :func:`_expression.over` is usually called using
the :meth:`.FunctionElement.over` method, e.g.::
func.row_number().over(order_by=mytable.c.some_column)
@@ -3623,7 +3683,7 @@ class Over(ColumnElement):
:data:`.expression.func`
- :func:`.expression.within_group`
+ :func:`_expression.within_group`
"""
self.element = element
@@ -3739,7 +3799,7 @@ class WithinGroup(ColumnElement):
set aggregate" functions, including :class:`.percentile_cont`,
:class:`.rank`, :class:`.dense_rank`, etc.
- :func:`~.expression.within_group` is usually called using
+ :func:`_expression.within_group` is usually called using
the :meth:`.FunctionElement.within_group` method, e.g.::
from sqlalchemy import within_group
@@ -3765,7 +3825,7 @@ class WithinGroup(ColumnElement):
:data:`.expression.func`
- :func:`.expression.over`
+ :func:`_expression.over`
"""
self.element = element
@@ -3904,7 +3964,7 @@ class FunctionFilter(ColumnElement):
from sqlalchemy import over, funcfilter
over(funcfilter(func.rank(), MyClass.y > 5), order_by='x')
- See :func:`~.expression.over` for a full description.
+ See :func:`_expression.over` for a full description.
"""
return Over(
@@ -3956,17 +4016,18 @@ class Label(roles.LabeledColumnExprRole, ColumnElement):
def __init__(self, name, element, type_=None):
"""Return a :class:`Label` object for the
- given :class:`.ColumnElement`.
+ given :class:`_expression.ColumnElement`.
A label changes the name of an element in the columns clause of a
``SELECT`` statement, typically via the ``AS`` SQL keyword.
This functionality is more conveniently available via the
- :meth:`.ColumnElement.label` method on :class:`.ColumnElement`.
+ :meth:`_expression.ColumnElement.label` method on
+ :class:`_expression.ColumnElement`.
:param name: label name
- :param obj: a :class:`.ColumnElement`.
+ :param obj: a :class:`_expression.ColumnElement`.
"""
@@ -4070,8 +4131,8 @@ class ColumnClause(
"""Represents a column expression from any textual string.
The :class:`.ColumnClause`, a lightweight analogue to the
- :class:`.Column` class, is typically invoked using the
- :func:`.column` function, as in::
+ :class:`_schema.Column` class, is typically invoked using the
+ :func:`_expression.column` function, as in::
from sqlalchemy import column
@@ -4083,21 +4144,24 @@ class ColumnClause(
SELECT id, name FROM user
:class:`.ColumnClause` is the immediate superclass of the schema-specific
- :class:`.Column` object. While the :class:`.Column` class has all the
+ :class:`_schema.Column` object. While the :class:`_schema.Column`
+ class has all the
same capabilities as :class:`.ColumnClause`, the :class:`.ColumnClause`
class is usable by itself in those cases where behavioral requirements
are limited to simple SQL expression generation. The object has none of
the associations with schema-level metadata or with execution-time
- behavior that :class:`.Column` does, so in that sense is a "lightweight"
- version of :class:`.Column`.
+ behavior that :class:`_schema.Column` does,
+ so in that sense is a "lightweight"
+ version of :class:`_schema.Column`.
- Full details on :class:`.ColumnClause` usage is at :func:`.column`.
+ Full details on :class:`.ColumnClause` usage is at
+ :func:`_expression.column`.
.. seealso::
- :func:`.column`
+ :func:`_expression.column`
- :class:`.Column`
+ :class:`_schema.Column`
"""
@@ -4118,7 +4182,8 @@ class ColumnClause(
"""Produce a :class:`.ColumnClause` object.
The :class:`.ColumnClause` is a lightweight analogue to the
- :class:`.Column` class. The :func:`.column` function can
+ :class:`_schema.Column` class. The :func:`_expression.column`
+ function can
be invoked with just a name alone, as in::
from sqlalchemy import column
@@ -4130,8 +4195,9 @@ class ColumnClause(
SELECT id, name FROM user
- Once constructed, :func:`.column` may be used like any other SQL
- expression element such as within :func:`~.sql.expression.select`
+ Once constructed, :func:`_expression.column`
+ may be used like any other SQL
+ expression element such as within :func:`_expression.select`
constructs::
from sqlalchemy.sql import column
@@ -4139,19 +4205,24 @@ class ColumnClause(
id, name = column("id"), column("name")
stmt = select([id, name]).select_from("user")
- The text handled by :func:`.column` is assumed to be handled
+ The text handled by :func:`_expression.column`
+ is assumed to be handled
like the name of a database column; if the string contains mixed case,
special characters, or matches a known reserved word on the target
backend, the column expression will render using the quoting
behavior determined by the backend. To produce a textual SQL
expression that is rendered exactly without any quoting,
- use :func:`.literal_column` instead, or pass ``True`` as the
- value of :paramref:`.column.is_literal`. Additionally, full SQL
- statements are best handled using the :func:`.text` construct.
+ use :func:`_expression.literal_column` instead,
+ or pass ``True`` as the
+ value of :paramref:`_expression.column.is_literal`. Additionally,
+ full SQL
+ statements are best handled using the :func:`_expression.text`
+ construct.
- :func:`.column` can be used in a table-like
+ :func:`_expression.column` can be used in a table-like
fashion by combining it with the :func:`.table` function
- (which is the lightweight analogue to :class:`.Table`) to produce
+ (which is the lightweight analogue to :class:`_schema.Table`
+ ) to produce
a working table construct with minimal boilerplate::
from sqlalchemy import table, column, select
@@ -4164,36 +4235,37 @@ class ColumnClause(
stmt = select([user.c.description]).where(user.c.name == 'wendy')
- A :func:`.column` / :func:`.table` construct like that illustrated
+ A :func:`_expression.column` / :func:`.table`
+ construct like that illustrated
above can be created in an
ad-hoc fashion and is not associated with any
- :class:`.schema.MetaData`, DDL, or events, unlike its
- :class:`.Table` counterpart.
+ :class:`_schema.MetaData`, DDL, or events, unlike its
+ :class:`_schema.Table` counterpart.
- .. versionchanged:: 1.0.0 :func:`.expression.column` can now
+ .. versionchanged:: 1.0.0 :func:`_expression.column` can now
be imported from the plain ``sqlalchemy`` namespace like any
other SQL element.
:param text: the text of the element.
- :param type: :class:`.types.TypeEngine` object which can associate
+ :param type: :class:`_types.TypeEngine` object which can associate
this :class:`.ColumnClause` with a type.
:param is_literal: if True, the :class:`.ColumnClause` is assumed to
be an exact expression that will be delivered to the output with no
quoting rules applied regardless of case sensitive settings. the
- :func:`.literal_column()` function essentially invokes
- :func:`.column` while passing ``is_literal=True``.
+ :func:`_expression.literal_column()` function essentially invokes
+ :func:`_expression.column` while passing ``is_literal=True``.
.. seealso::
- :class:`.Column`
+ :class:`_schema.Column`
- :func:`.literal_column`
+ :func:`_expression.literal_column`
:func:`.table`
- :func:`.text`
+ :func:`_expression.text`
:ref:`sqlexpression_literal_column`
@@ -4418,9 +4490,11 @@ class quoted_name(util.MemoizedSlots, util.text_type):
The :class:`.quoted_name` object is normally created automatically
when specifying the name for key schema constructs such as
- :class:`.Table`, :class:`.Column`, and others. The class can also be
+ :class:`_schema.Table`, :class:`_schema.Column`, and others.
+ The class can also be
passed explicitly as the name to any function that receives a name which
- can be quoted. Such as to use the :meth:`.Engine.has_table` method with
+ can be quoted. Such as to use the :meth:`_engine.Engine.has_table`
+ method with
an unconditionally quoted name::
from sqlalchemy import create_engine
@@ -4592,7 +4666,7 @@ class conv(_truncated_label):
In some situations, such as in migration scripts, we may be rendering
the above :class:`.CheckConstraint` with a name that's already been
converted. In order to make sure the name isn't double-modified, the
- new name is applied using the :func:`.schema.conv` marker. We can
+ new name is applied using the :func:`_schema.conv` marker. We can
use this explicitly as follows::
@@ -4602,7 +4676,7 @@ class conv(_truncated_label):
t = Table('t', m, Column('x', Integer),
CheckConstraint('x > 5', name=conv('ck_t_x5')))
- Where above, the :func:`.schema.conv` marker indicates that the constraint
+ Where above, the :func:`_schema.conv` marker indicates that the constraint
name here is final, and the name will render as ``"ck_t_x5"`` and not
``"ck_t_ck_t_x5"``
diff --git a/lib/sqlalchemy/sql/events.py b/lib/sqlalchemy/sql/events.py
index cd0ba2640..51556d929 100644
--- a/lib/sqlalchemy/sql/events.py
+++ b/lib/sqlalchemy/sql/events.py
@@ -13,18 +13,19 @@ class DDLEvents(event.Events):
"""
Define event listeners for schema objects,
that is, :class:`.SchemaItem` and other :class:`.SchemaEventTarget`
- subclasses, including :class:`.MetaData`, :class:`.Table`,
- :class:`.Column`.
+ subclasses, including :class:`_schema.MetaData`, :class:`_schema.Table`,
+ :class:`_schema.Column`.
- :class:`.MetaData` and :class:`.Table` support events
+ :class:`_schema.MetaData` and :class:`_schema.Table` support events
specifically regarding when CREATE and DROP
DDL is emitted to the database.
Attachment events are also provided to customize
behavior whenever a child schema element is associated
- with a parent, such as, when a :class:`.Column` is associated
- with its :class:`.Table`, when a :class:`.ForeignKeyConstraint`
- is associated with a :class:`.Table`, etc.
+ with a parent, such as, when a :class:`_schema.Column` is associated
+ with its :class:`_schema.Table`, when a
+ :class:`_schema.ForeignKeyConstraint`
+ is associated with a :class:`_schema.Table`, etc.
Example using the ``after_create`` event::
@@ -59,7 +60,8 @@ class DDLEvents(event.Events):
For all :class:`.DDLEvent` events, the ``propagate=True`` keyword argument
will ensure that a given event handler is propagated to copies of the
- object, which are made when using the :meth:`.Table.tometadata` method::
+ object, which are made when using the :meth:`_schema.Table.tometadata`
+ method::
from sqlalchemy import DDL
event.listen(
@@ -72,7 +74,7 @@ class DDLEvents(event.Events):
new_table = some_table.tometadata(new_metadata)
The above :class:`.DDL` object will also be associated with the
- :class:`.Table` object represented by ``new_table``.
+ :class:`_schema.Table` object represented by ``new_table``.
.. seealso::
@@ -92,9 +94,9 @@ class DDLEvents(event.Events):
def before_create(self, target, connection, **kw):
r"""Called before CREATE statements are emitted.
- :param target: the :class:`.MetaData` or :class:`.Table`
+ :param target: the :class:`_schema.MetaData` or :class:`_schema.Table`
object which is the target of the event.
- :param connection: the :class:`.Connection` where the
+ :param connection: the :class:`_engine.Connection` where the
CREATE statement or statements will be emitted.
:param \**kw: additional keyword arguments relevant
to the event. The contents of this dictionary
@@ -107,16 +109,16 @@ class DDLEvents(event.Events):
modifier for this event; when True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
- :meth:`.Table.tometadata` is used.
+ :meth:`_schema.Table.tometadata` is used.
"""
def after_create(self, target, connection, **kw):
r"""Called after CREATE statements are emitted.
- :param target: the :class:`.MetaData` or :class:`.Table`
+ :param target: the :class:`_schema.MetaData` or :class:`_schema.Table`
object which is the target of the event.
- :param connection: the :class:`.Connection` where the
+ :param connection: the :class:`_engine.Connection` where the
CREATE statement or statements have been emitted.
:param \**kw: additional keyword arguments relevant
to the event. The contents of this dictionary
@@ -129,16 +131,16 @@ class DDLEvents(event.Events):
modifier for this event; when True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
- :meth:`.Table.tometadata` is used.
+ :meth:`_schema.Table.tometadata` is used.
"""
def before_drop(self, target, connection, **kw):
r"""Called before DROP statements are emitted.
- :param target: the :class:`.MetaData` or :class:`.Table`
+ :param target: the :class:`_schema.MetaData` or :class:`_schema.Table`
object which is the target of the event.
- :param connection: the :class:`.Connection` where the
+ :param connection: the :class:`_engine.Connection` where the
DROP statement or statements will be emitted.
:param \**kw: additional keyword arguments relevant
to the event. The contents of this dictionary
@@ -151,16 +153,16 @@ class DDLEvents(event.Events):
modifier for this event; when True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
- :meth:`.Table.tometadata` is used.
+ :meth:`_schema.Table.tometadata` is used.
"""
def after_drop(self, target, connection, **kw):
r"""Called after DROP statements are emitted.
- :param target: the :class:`.MetaData` or :class:`.Table`
+ :param target: the :class:`_schema.MetaData` or :class:`_schema.Table`
object which is the target of the event.
- :param connection: the :class:`.Connection` where the
+ :param connection: the :class:`_engine.Connection` where the
DROP statement or statements have been emitted.
:param \**kw: additional keyword arguments relevant
to the event. The contents of this dictionary
@@ -173,7 +175,7 @@ class DDLEvents(event.Events):
modifier for this event; when True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
- :meth:`.Table.tometadata` is used.
+ :meth:`_schema.Table.tometadata` is used.
"""
@@ -188,7 +190,7 @@ class DDLEvents(event.Events):
modifier for this event; when True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
- :meth:`.Table.tometadata` is used.
+ :meth:`_schema.Table.tometadata` is used.
"""
@@ -203,13 +205,13 @@ class DDLEvents(event.Events):
modifier for this event; when True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
- :meth:`.Table.tometadata` is used.
+ :meth:`_schema.Table.tometadata` is used.
"""
def column_reflect(self, inspector, table, column_info):
"""Called for each unit of 'column info' retrieved when
- a :class:`.Table` is being reflected.
+ a :class:`_schema.Table` is being reflected.
The dictionary of column information as returned by the
dialect is passed, and can be modified. The dictionary
@@ -226,13 +228,13 @@ class DDLEvents(event.Events):
* ``default`` - the column's server default value. This is
normally specified as a plain string SQL expression, however the
event can pass a :class:`.FetchedValue`, :class:`.DefaultClause`,
- or :func:`.sql.expression.text` object as well.
+ or :func:`_expression.text` object as well.
.. versionchanged:: 1.1.6
The :meth:`.DDLEvents.column_reflect` event allows a non
string :class:`.FetchedValue`,
- :func:`.sql.expression.text`, or derived object to be
+ :func:`_expression.text`, or derived object to be
specified as the value of ``default`` in the column
dictionary.
@@ -240,12 +242,12 @@ class DDLEvents(event.Events):
The event is called before any action is taken against
this dictionary, and the contents can be modified.
- The :class:`.Column` specific arguments ``info``, ``key``,
+ The :class:`_schema.Column` specific arguments ``info``, ``key``,
and ``quote`` can also be added to the dictionary and
- will be passed to the constructor of :class:`.Column`.
+ will be passed to the constructor of :class:`_schema.Column`.
Note that this event is only meaningful if either
- associated with the :class:`.Table` class across the
+ associated with the :class:`_schema.Table` class across the
board, e.g.::
from sqlalchemy.schema import Table
@@ -260,7 +262,7 @@ class DDLEvents(event.Events):
'column_reflect',
listen_for_reflect)
- ...or with a specific :class:`.Table` instance using
+ ...or with a specific :class:`_schema.Table` instance using
the ``listeners`` argument::
def listen_for_reflect(inspector, table, column_info):
@@ -275,12 +277,13 @@ class DDLEvents(event.Events):
])
This because the reflection process initiated by ``autoload=True``
- completes within the scope of the constructor for :class:`.Table`.
+ completes within the scope of the constructor for
+ :class:`_schema.Table`.
:func:`.event.listen` also accepts the ``propagate=True``
modifier for this event; when True, the listener function will
be established for any copies made of the target object,
i.e. those copies that are generated when
- :meth:`.Table.tometadata` is used.
+ :meth:`_schema.Table.tometadata` is used.
"""
diff --git a/lib/sqlalchemy/sql/functions.py b/lib/sqlalchemy/sql/functions.py
index 7973871f3..1b10df954 100644
--- a/lib/sqlalchemy/sql/functions.py
+++ b/lib/sqlalchemy/sql/functions.py
@@ -127,7 +127,7 @@ class FunctionElement(Executable, ColumnElement, FromClause):
an anonymously named column.
An interim approach to providing named columns for a function
- as a FROM clause is to build a :func:`~.sql.expression.select` with the
+ as a FROM clause is to build a :func:`_expression.select` with the
desired columns::
from sqlalchemy.sql import column
@@ -163,7 +163,7 @@ class FunctionElement(Executable, ColumnElement, FromClause):
from sqlalchemy import over
over(func.row_number(), order_by='x')
- See :func:`~.expression.over` for a full description.
+ See :func:`_expression.over` for a full description.
"""
return Over(
@@ -181,7 +181,7 @@ class FunctionElement(Executable, ColumnElement, FromClause):
set aggregate" functions, including :class:`.percentile_cont`,
:class:`.rank`, :class:`.dense_rank`, etc.
- See :func:`~.expression.within_group` for a full description.
+ See :func:`_expression.within_group` for a full description.
.. versionadded:: 1.1
@@ -245,7 +245,8 @@ class FunctionElement(Executable, ColumnElement, FromClause):
to manipulate the "left" and "right" sides of the ON clause of a JOIN
expression. The purpose of this method is to provide a SQL function
construct that can also supply this information to the ORM, when used
- with the :paramref:`.relationship.primaryjoin` parameter. The return
+ with the :paramref:`_orm.relationship.primaryjoin` parameter.
+ The return
value is a containment object called :class:`.FunctionAsBinary`.
An ORM example is as follows::
@@ -300,7 +301,7 @@ class FunctionElement(Executable, ColumnElement, FromClause):
return None
def alias(self, name=None, flat=False):
- r"""Produce a :class:`.Alias` construct against this
+ r"""Produce a :class:`_expression.Alias` construct against this
:class:`.FunctionElement`.
This construct wraps the function in a named alias which
@@ -332,7 +333,7 @@ class FunctionElement(Executable, ColumnElement, FromClause):
return Alias._construct(self, name)
def select(self):
- """Produce a :func:`~.expression.select` construct
+ """Produce a :func:`_expression.select` construct
against this :class:`.FunctionElement`.
This is shorthand for::
@@ -353,8 +354,8 @@ class FunctionElement(Executable, ColumnElement, FromClause):
produce a SELECT construct.
Note that :class:`.FunctionElement` can be passed to
- the :meth:`.Connectable.scalar` method of :class:`.Connection`
- or :class:`.Engine`.
+ the :meth:`.Connectable.scalar` method of :class:`_engine.Connection`
+ or :class:`_engine.Engine`.
"""
return self.select().execute().scalar()
@@ -367,8 +368,8 @@ class FunctionElement(Executable, ColumnElement, FromClause):
produce a SELECT construct.
Note that :class:`.FunctionElement` can be passed to
- the :meth:`.Connectable.execute` method of :class:`.Connection`
- or :class:`.Engine`.
+ the :meth:`.Connectable.execute` method of :class:`_engine.Connection`
+ or :class:`_engine.Engine`.
"""
return self.select().execute()
@@ -478,7 +479,8 @@ class _FunctionGenerator(object):
:class:`.Function`.
This object meets the "column" interface, including comparison and labeling
functions. The object can also be passed the :meth:`~.Connectable.execute`
- method of a :class:`.Connection` or :class:`.Engine`, where it will be
+ method of a :class:`_engine.Connection` or :class:`_engine.Engine`,
+ where it will be
wrapped inside of a SELECT statement first::
print(connection.execute(func.current_timestamp()).scalar())
@@ -919,7 +921,7 @@ class array_agg(GenericFunction):
"""support for the ARRAY_AGG function.
The ``func.array_agg(expr)`` construct returns an expression of
- type :class:`.types.ARRAY`.
+ type :class:`_types.ARRAY`.
e.g.::
@@ -929,8 +931,8 @@ class array_agg(GenericFunction):
.. seealso::
- :func:`.postgresql.array_agg` - PostgreSQL-specific version that
- returns :class:`.postgresql.ARRAY`, which has PG-specific operators
+ :func:`_postgresql.array_agg` - PostgreSQL-specific version that
+ returns :class:`_postgresql.ARRAY`, which has PG-specific operators
added.
"""
@@ -988,7 +990,7 @@ class percentile_cont(OrderedSetAgg):
modifier to supply a sort expression to operate upon.
The return type of this function is the same as the sort expression,
- or if the arguments are an array, an :class:`.types.ARRAY` of the sort
+ or if the arguments are an array, an :class:`_types.ARRAY` of the sort
expression's type.
.. versionadded:: 1.1
@@ -1005,7 +1007,7 @@ class percentile_disc(OrderedSetAgg):
modifier to supply a sort expression to operate upon.
The return type of this function is the same as the sort expression,
- or if the arguments are an array, an :class:`.types.ARRAY` of the sort
+ or if the arguments are an array, an :class:`_types.ARRAY` of the sort
expression's type.
.. versionadded:: 1.1
@@ -1079,7 +1081,7 @@ class cube(GenericFunction):
r"""Implement the ``CUBE`` grouping operation.
This function is used as part of the GROUP BY of a statement,
- e.g. :meth:`.Select.group_by`::
+ e.g. :meth:`_expression.Select.group_by`::
stmt = select(
[func.sum(table.c.value), table.c.col_1, table.c.col_2]
@@ -1095,7 +1097,7 @@ class rollup(GenericFunction):
r"""Implement the ``ROLLUP`` grouping operation.
This function is used as part of the GROUP BY of a statement,
- e.g. :meth:`.Select.group_by`::
+ e.g. :meth:`_expression.Select.group_by`::
stmt = select(
[func.sum(table.c.value), table.c.col_1, table.c.col_2]
@@ -1111,7 +1113,7 @@ class grouping_sets(GenericFunction):
r"""Implement the ``GROUPING SETS`` grouping operation.
This function is used as part of the GROUP BY of a statement,
- e.g. :meth:`.Select.group_by`::
+ e.g. :meth:`_expression.Select.group_by`::
stmt = select(
[func.sum(table.c.value), table.c.col_1, table.c.col_2]
diff --git a/lib/sqlalchemy/sql/operators.py b/lib/sqlalchemy/sql/operators.py
index ae56822c2..c0699c2ad 100644
--- a/lib/sqlalchemy/sql/operators.py
+++ b/lib/sqlalchemy/sql/operators.py
@@ -61,7 +61,7 @@ class Operators(object):
When used with SQL expressions, results in an
AND operation, equivalent to
- :func:`~.expression.and_`, that is::
+ :func:`_expression.and_`, that is::
a & b
@@ -85,7 +85,7 @@ class Operators(object):
When used with SQL expressions, results in an
OR operation, equivalent to
- :func:`~.expression.or_`, that is::
+ :func:`_expression.or_`, that is::
a | b
@@ -109,7 +109,7 @@ class Operators(object):
When used with SQL expressions, results in a
NOT operation, equivalent to
- :func:`~.expression.not_`, that is::
+ :func:`_expression.not_`, that is::
~a
@@ -296,7 +296,7 @@ class custom_op(object):
class ColumnOperators(Operators):
"""Defines boolean, comparison, and other operators for
- :class:`.ColumnElement` expressions.
+ :class:`_expression.ColumnElement` expressions.
By default, all methods call down to
:meth:`.operate` or :meth:`.reverse_operate`,
@@ -314,9 +314,9 @@ class ColumnOperators(Operators):
def eq(a, b):
return a == b
- The core column expression unit :class:`.ColumnElement`
+ The core column expression unit :class:`_expression.ColumnElement`
overrides :meth:`.Operators.operate` and others
- to return further :class:`.ColumnElement` constructs,
+ to return further :class:`_expression.ColumnElement` constructs,
so that the ``==`` operation above is replaced by a clause
construct.
@@ -579,7 +579,7 @@ class ColumnOperators(Operators):
.. versionadded:: 1.3 "expanding" bound parameters now support
empty lists
- * a :func:`~.sql.expression.select` construct, which is usually a
+ * a :func:`_expression.select` construct, which is usually a
correlated scalar select::
stmt.where(
@@ -594,7 +594,7 @@ class ColumnOperators(Operators):
WHERE COL IN (SELECT othertable.y
FROM othertable WHERE othertable.x = table.x)
- :param other: a list of literals, a :func:`~.sql.expression.select`
+ :param other: a list of literals, a :func:`_expression.select`
construct, or a :func:`.bindparam` construct that includes the
:paramref:`.bindparam.expanding` flag set to True.
@@ -961,32 +961,32 @@ class ColumnOperators(Operators):
return self.operate(match_op, other, **kwargs)
def desc(self):
- """Produce a :func:`~.expression.desc` clause against the
+ """Produce a :func:`_expression.desc` clause against the
parent object."""
return self.operate(desc_op)
def asc(self):
- """Produce a :func:`~.expression.asc` clause against the
+ """Produce a :func:`_expression.asc` clause against the
parent object."""
return self.operate(asc_op)
def nullsfirst(self):
- """Produce a :func:`~.expression.nullsfirst` clause against the
+ """Produce a :func:`_expression.nullsfirst` clause against the
parent object."""
return self.operate(nullsfirst_op)
def nullslast(self):
- """Produce a :func:`~.expression.nullslast` clause against the
+ """Produce a :func:`_expression.nullslast` clause against the
parent object."""
return self.operate(nullslast_op)
def collate(self, collation):
- """Produce a :func:`~.expression.collate` clause against
+ """Produce a :func:`_expression.collate` clause against
the parent object, given the collation string.
.. seealso::
- :func:`~.expression.collate`
+ :func:`_expression.collate`
"""
return self.operate(collate, collation)
@@ -1032,21 +1032,21 @@ class ColumnOperators(Operators):
return self.reverse_operate(mod, other)
def between(self, cleft, cright, symmetric=False):
- """Produce a :func:`~.expression.between` clause against
+ """Produce a :func:`_expression.between` clause against
the parent object, given the lower and upper range.
"""
return self.operate(between_op, cleft, cright, symmetric=symmetric)
def distinct(self):
- """Produce a :func:`~.expression.distinct` clause against the
+ """Produce a :func:`_expression.distinct` clause against the
parent object.
"""
return self.operate(distinct_op)
def any_(self):
- """Produce a :func:`~.expression.any_` clause against the
+ """Produce a :func:`_expression.any_` clause against the
parent object.
This operator is only appropriate against a scalar subquery
@@ -1061,9 +1061,9 @@ class ColumnOperators(Operators):
.. seealso::
- :func:`~.expression.any_` - standalone version
+ :func:`_expression.any_` - standalone version
- :func:`~.expression.all_` - ALL operator
+ :func:`_expression.all_` - ALL operator
.. versionadded:: 1.1
@@ -1071,7 +1071,7 @@ class ColumnOperators(Operators):
return self.operate(any_op)
def all_(self):
- """Produce a :func:`~.expression.all_` clause against the
+ """Produce a :func:`_expression.all_` clause against the
parent object.
This operator is only appropriate against a scalar subquery
@@ -1086,9 +1086,9 @@ class ColumnOperators(Operators):
.. seealso::
- :func:`~.expression.all_` - standalone version
+ :func:`_expression.all_` - standalone version
- :func:`~.expression.any_` - ANY operator
+ :func:`_expression.any_` - ANY operator
.. versionadded:: 1.1
diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py
index ac3fb9607..ec8d5a458 100644
--- a/lib/sqlalchemy/sql/schema.py
+++ b/lib/sqlalchemy/sql/schema.py
@@ -60,9 +60,9 @@ RETAIN_SCHEMA = util.symbol("retain_schema")
BLANK_SCHEMA = util.symbol(
"blank_schema",
- """Symbol indicating that a :class:`.Table` or :class:`.Sequence`
+ """Symbol indicating that a :class:`_schema.Table` or :class:`.Sequence`
should have 'None' for its schema, even if the parent
- :class:`.MetaData` has specified a schema.
+ :class:`_schema.MetaData` has specified a schema.
.. versionadded:: 1.0.14
@@ -131,7 +131,7 @@ class SchemaItem(SchemaEventTarget, visitors.Visitable):
The dictionary is automatically generated when first accessed.
It can also be specified in the constructor of some objects,
- such as :class:`.Table` and :class:`.Column`.
+ such as :class:`_schema.Table` and :class:`_schema.Column`.
"""
return {}
@@ -155,12 +155,14 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
Column('value', String(50))
)
- The :class:`.Table` object constructs a unique instance of itself based
+ The :class:`_schema.Table`
+ object constructs a unique instance of itself based
on its name and optional schema name within the given
- :class:`.MetaData` object. Calling the :class:`.Table`
- constructor with the same name and same :class:`.MetaData` argument
- a second time will return the *same* :class:`.Table` object - in this way
- the :class:`.Table` constructor acts as a registry function.
+ :class:`_schema.MetaData` object. Calling the :class:`_schema.Table`
+ constructor with the same name and same :class:`_schema.MetaData` argument
+ a second time will return the *same* :class:`_schema.Table`
+ object - in this way
+ the :class:`_schema.Table` constructor acts as a registry function.
.. seealso::
@@ -171,10 +173,12 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
:param name: The name of this table as represented in the database.
The table name, along with the value of the ``schema`` parameter,
- forms a key which uniquely identifies this :class:`.Table` within
- the owning :class:`.MetaData` collection.
- Additional calls to :class:`.Table` with the same name, metadata,
- and schema name will return the same :class:`.Table` object.
+ forms a key which uniquely identifies this :class:`_schema.Table`
+ within
+ the owning :class:`_schema.MetaData` collection.
+ Additional calls to :class:`_schema.Table` with the same name,
+ metadata,
+ and schema name will return the same :class:`_schema.Table` object.
Names which contain no upper case characters
will be treated as case insensitive names, and will not be quoted
@@ -186,26 +190,34 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
``quote=True`` to the constructor, or use the :class:`.quoted_name`
construct to specify the name.
- :param metadata: a :class:`.MetaData` object which will contain this
+ :param metadata: a :class:`_schema.MetaData`
+ object which will contain this
table. The metadata is used as a point of association of this table
with other tables which are referenced via foreign key. It also
may be used to associate this table with a particular
:class:`.Connectable`.
:param \*args: Additional positional arguments are used primarily
- to add the list of :class:`.Column` objects contained within this
+ to add the list of :class:`_schema.Column`
+ objects contained within this
table. Similar to the style of a CREATE TABLE statement, other
:class:`.SchemaItem` constructs may be added here, including
- :class:`.PrimaryKeyConstraint`, and :class:`.ForeignKeyConstraint`.
+ :class:`.PrimaryKeyConstraint`, and
+ :class:`_schema.ForeignKeyConstraint`.
- :param autoload: Defaults to False, unless :paramref:`.Table.autoload_with`
- is set in which case it defaults to True; :class:`.Column` objects
+ :param autoload: Defaults to False, unless
+ :paramref:`_schema.Table.autoload_with`
+ is set in which case it defaults to True; :class:`_schema.Column`
+ objects
for this table should be reflected from the database, possibly
- augmenting or replacing existing :class:`.Column` objects that were
+ augmenting or replacing existing :class:`_schema.Column`
+ objects that were
explicitly specified.
- .. versionchanged:: 1.0.0 setting the :paramref:`.Table.autoload_with`
- parameter implies that :paramref:`.Table.autoload` will default
+ .. versionchanged:: 1.0.0 setting the
+ :paramref:`_schema.Table.autoload_with`
+ parameter implies that :paramref:`_schema.Table.autoload`
+ will default
to True.
.. seealso::
@@ -213,69 +225,90 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
:ref:`metadata_reflection_toplevel`
:param autoload_replace: Defaults to ``True``; when using
- :paramref:`.Table.autoload`
- in conjunction with :paramref:`.Table.extend_existing`, indicates
- that :class:`.Column` objects present in the already-existing
- :class:`.Table` object should be replaced with columns of the same
+ :paramref:`_schema.Table.autoload`
+ in conjunction with :paramref:`_schema.Table.extend_existing`,
+ indicates
+ that :class:`_schema.Column` objects present in the already-existing
+ :class:`_schema.Table`
+ object should be replaced with columns of the same
name retrieved from the autoload process. When ``False``, columns
already present under existing names will be omitted from the
reflection process.
- Note that this setting does not impact :class:`.Column` objects
- specified programmatically within the call to :class:`.Table` that
- also is autoloading; those :class:`.Column` objects will always
+ Note that this setting does not impact :class:`_schema.Column` objects
+ specified programmatically within the call to :class:`_schema.Table`
+ that
+ also is autoloading; those :class:`_schema.Column` objects will always
replace existing columns of the same name when
- :paramref:`.Table.extend_existing` is ``True``.
+ :paramref:`_schema.Table.extend_existing` is ``True``.
.. seealso::
- :paramref:`.Table.autoload`
+ :paramref:`_schema.Table.autoload`
- :paramref:`.Table.extend_existing`
+ :paramref:`_schema.Table.extend_existing`
- :param autoload_with: An :class:`.Engine` or :class:`.Connection` object,
- or a :class:`.Inspector` object as returned by :func:`.inspect`
- against one, with which this :class:`.Table` object will be reflected.
+ :param autoload_with: An :class:`_engine.Engine` or
+ :class:`_engine.Connection` object,
+ or a :class:`_reflection.Inspector` object as returned by
+ :func:`_sa.inspect`
+ against one, with which this :class:`_schema.Table`
+ object will be reflected.
When set to a non-None value, it implies that
- :paramref:`.Table.autoload` is ``True``. If left unset, but
- :paramref:`.Table.autoload` is explicitly set to ``True``, an autoload
- operation will attempt to proceed by locating an :class:`.Engine` or
- :class:`.Connection` bound to the underlying :class:`.MetaData` object.
+ :paramref:`_schema.Table.autoload` is ``True``. If left unset, but
+ :paramref:`_schema.Table.autoload` is explicitly set to ``True``,
+ an autoload
+ operation will attempt to proceed by locating an
+ :class:`_engine.Engine` or
+ :class:`_engine.Connection` bound to the underlying
+ :class:`_schema.MetaData` object.
.. seealso::
- :paramref:`.Table.autoload`
+ :paramref:`_schema.Table.autoload`
:param extend_existing: When ``True``, indicates that if this
- :class:`.Table` is already present in the given :class:`.MetaData`,
+ :class:`_schema.Table` is already present in the given
+ :class:`_schema.MetaData`,
apply further arguments within the constructor to the existing
- :class:`.Table`.
-
- If :paramref:`.Table.extend_existing` or
- :paramref:`.Table.keep_existing` are not set, and the given name
- of the new :class:`.Table` refers to a :class:`.Table` that is
- already present in the target :class:`.MetaData` collection, and
- this :class:`.Table` specifies additional columns or other constructs
+ :class:`_schema.Table`.
+
+ If :paramref:`_schema.Table.extend_existing` or
+ :paramref:`_schema.Table.keep_existing` are not set,
+ and the given name
+ of the new :class:`_schema.Table` refers to a :class:`_schema.Table`
+ that is
+ already present in the target :class:`_schema.MetaData` collection,
+ and
+ this :class:`_schema.Table`
+ specifies additional columns or other constructs
or flags that modify the table's state, an
error is raised. The purpose of these two mutually-exclusive flags
- is to specify what action should be taken when a :class:`.Table`
- is specified that matches an existing :class:`.Table`, yet specifies
+ is to specify what action should be taken when a
+ :class:`_schema.Table`
+ is specified that matches an existing :class:`_schema.Table`,
+ yet specifies
additional constructs.
- :paramref:`.Table.extend_existing` will also work in conjunction
- with :paramref:`.Table.autoload` to run a new reflection
- operation against the database, even if a :class:`.Table`
+ :paramref:`_schema.Table.extend_existing`
+ will also work in conjunction
+ with :paramref:`_schema.Table.autoload` to run a new reflection
+ operation against the database, even if a :class:`_schema.Table`
of the same name is already present in the target
- :class:`.MetaData`; newly reflected :class:`.Column` objects
+ :class:`_schema.MetaData`; newly reflected :class:`_schema.Column`
+ objects
and other options will be added into the state of the
- :class:`.Table`, potentially overwriting existing columns
+ :class:`_schema.Table`, potentially overwriting existing columns
and options of the same name.
- As is always the case with :paramref:`.Table.autoload`,
- :class:`.Column` objects can be specified in the same :class:`.Table`
+ As is always the case with :paramref:`_schema.Table.autoload`,
+ :class:`_schema.Column` objects can be specified in the same
+ :class:`_schema.Table`
constructor, which will take precedence. Below, the existing
- table ``mytable`` will be augmented with :class:`.Column` objects
- both reflected from the database, as well as the given :class:`.Column`
+ table ``mytable`` will be augmented with :class:`_schema.Column`
+ objects
+ both reflected from the database, as well as the given
+ :class:`_schema.Column`
named "y"::
Table("mytable", metadata,
@@ -287,11 +320,11 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
.. seealso::
- :paramref:`.Table.autoload`
+ :paramref:`_schema.Table.autoload`
- :paramref:`.Table.autoload_replace`
+ :paramref:`_schema.Table.autoload_replace`
- :paramref:`.Table.keep_existing`
+ :paramref:`_schema.Table.keep_existing`
:param implicit_returning: True by default - indicates that
@@ -305,15 +338,20 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
``Table`` object. Defaults to ``None`` which indicates all columns
should be reflected.
- :param resolve_fks: Whether or not to reflect :class:`.Table` objects
- related to this one via :class:`.ForeignKey` objects, when
- :paramref:`.Table.autoload` or :paramref:`.Table.autoload_with` is
+ :param resolve_fks: Whether or not to reflect :class:`_schema.Table`
+ objects
+ related to this one via :class:`_schema.ForeignKey` objects, when
+ :paramref:`_schema.Table.autoload` or
+ :paramref:`_schema.Table.autoload_with` is
specified. Defaults to True. Set to False to disable reflection of
- related tables as :class:`.ForeignKey` objects are encountered; may be
+ related tables as :class:`_schema.ForeignKey`
+ objects are encountered; may be
used either to save on SQL calls or to avoid issues with related tables
that can't be accessed. Note that if a related table is already present
- in the :class:`.MetaData` collection, or becomes present later, a
- :class:`.ForeignKey` object associated with this :class:`.Table` will
+ in the :class:`_schema.MetaData` collection, or becomes present later,
+ a
+ :class:`_schema.ForeignKey` object associated with this
+ :class:`_schema.Table` will
resolve to that table normally.
.. versionadded:: 1.3
@@ -327,34 +365,41 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
:attr:`.SchemaItem.info` attribute of this object.
:param keep_existing: When ``True``, indicates that if this Table
- is already present in the given :class:`.MetaData`, ignore
+ is already present in the given :class:`_schema.MetaData`, ignore
further arguments within the constructor to the existing
- :class:`.Table`, and return the :class:`.Table` object as
+ :class:`_schema.Table`, and return the :class:`_schema.Table`
+ object as
originally created. This is to allow a function that wishes
- to define a new :class:`.Table` on first call, but on
- subsequent calls will return the same :class:`.Table`,
+ to define a new :class:`_schema.Table` on first call, but on
+ subsequent calls will return the same :class:`_schema.Table`,
without any of the declarations (particularly constraints)
being applied a second time.
- If :paramref:`.Table.extend_existing` or
- :paramref:`.Table.keep_existing` are not set, and the given name
- of the new :class:`.Table` refers to a :class:`.Table` that is
- already present in the target :class:`.MetaData` collection, and
- this :class:`.Table` specifies additional columns or other constructs
+ If :paramref:`_schema.Table.extend_existing` or
+ :paramref:`_schema.Table.keep_existing` are not set,
+ and the given name
+ of the new :class:`_schema.Table` refers to a :class:`_schema.Table`
+ that is
+ already present in the target :class:`_schema.MetaData` collection,
+ and
+ this :class:`_schema.Table`
+ specifies additional columns or other constructs
or flags that modify the table's state, an
error is raised. The purpose of these two mutually-exclusive flags
- is to specify what action should be taken when a :class:`.Table`
- is specified that matches an existing :class:`.Table`, yet specifies
+ is to specify what action should be taken when a
+ :class:`_schema.Table`
+ is specified that matches an existing :class:`_schema.Table`,
+ yet specifies
additional constructs.
.. seealso::
- :paramref:`.Table.extend_existing`
+ :paramref:`_schema.Table.extend_existing`
:param listeners: A list of tuples of the form ``(<eventname>, <fn>)``
which will be passed to :func:`.event.listen` upon construction.
This alternate hook to :func:`.event.listen` allows the establishment
- of a listener function specific to this :class:`.Table` before
+ of a listener function specific to this :class:`_schema.Table` before
the "autoload" process begins. Particularly useful for
the :meth:`.DDLEvents.column_reflect` event::
@@ -370,7 +415,7 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
])
:param mustexist: When ``True``, indicates that this Table must already
- be present in the given :class:`.MetaData` collection, else
+ be present in the given :class:`_schema.MetaData` collection, else
an exception is raised.
:param prefixes:
@@ -391,16 +436,23 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
the table resides in a schema other than the default selected schema
for the engine's database connection. Defaults to ``None``.
- If the owning :class:`.MetaData` of this :class:`.Table` specifies its
- own :paramref:`.MetaData.schema` parameter, then that schema name will
- be applied to this :class:`.Table` if the schema parameter here is set
- to ``None``. To set a blank schema name on a :class:`.Table` that
- would otherwise use the schema set on the owning :class:`.MetaData`,
+ If the owning :class:`_schema.MetaData` of this :class:`_schema.Table`
+ specifies its
+ own :paramref:`_schema.MetaData.schema` parameter,
+ then that schema name will
+ be applied to this :class:`_schema.Table`
+ if the schema parameter here is set
+ to ``None``. To set a blank schema name on a :class:`_schema.Table`
+ that
+ would otherwise use the schema set on the owning
+ :class:`_schema.MetaData`,
specify the special symbol :attr:`.BLANK_SCHEMA`.
.. versionadded:: 1.0.14 Added the :attr:`.BLANK_SCHEMA` symbol to
- allow a :class:`.Table` to have a blank schema name even when the
- parent :class:`.MetaData` specifies :paramref:`.MetaData.schema`.
+ allow a :class:`_schema.Table`
+ to have a blank schema name even when the
+ parent :class:`_schema.MetaData` specifies
+ :paramref:`_schema.MetaData.schema`.
The quoting rules for the schema name are the same as those for the
``name`` parameter, in that quoting is applied for reserved words or
@@ -411,8 +463,9 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
:param comment: Optional string that will render an SQL comment on table
creation.
- .. versionadded:: 1.2 Added the :paramref:`.Table.comment` parameter
- to :class:`.Table`.
+ .. versionadded:: 1.2 Added the :paramref:`_schema.Table.comment`
+ parameter
+ to :class:`_schema.Table`.
:param \**kw: Additional keyword arguments not mentioned above are
dialect specific, and passed in the form ``<dialectname>_<argname>``.
@@ -482,10 +535,10 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
metadata._remove_table(name, schema)
def __init__(self, *args, **kw):
- """Constructor for :class:`~.schema.Table`.
+ """Constructor for :class:`_schema.Table`.
This method is a no-op. See the top-level
- documentation for :class:`~.schema.Table`
+ documentation for :class:`_schema.Table`
for constructor arguments.
"""
@@ -596,10 +649,11 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
@property
def foreign_key_constraints(self):
- """:class:`.ForeignKeyConstraint` objects referred to by this
- :class:`.Table`.
+ """:class:`_schema.ForeignKeyConstraint` objects referred to by this
+ :class:`_schema.Table`.
- This list is produced from the collection of :class:`.ForeignKey`
+ This list is produced from the collection of
+ :class:`_schema.ForeignKey`
objects currently associated.
.. versionadded:: 1.0.0
@@ -676,12 +730,13 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
@property
def key(self):
- """Return the 'key' for this :class:`.Table`.
+ """Return the 'key' for this :class:`_schema.Table`.
This value is used as the dictionary key within the
- :attr:`.MetaData.tables` collection. It is typically the same
- as that of :attr:`.Table.name` for a table with no
- :attr:`.Table.schema` set; otherwise it is typically of the form
+ :attr:`_schema.MetaData.tables` collection. It is typically the same
+ as that of :attr:`_schema.Table.name` for a table with no
+ :attr:`_schema.Table.schema`
+ set; otherwise it is typically of the form
``schemaname.tablename``.
"""
@@ -719,13 +774,13 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
self._extra_dependencies.add(table)
def append_column(self, column):
- """Append a :class:`~.schema.Column` to this :class:`~.schema.Table`.
+ """Append a :class:`_schema.Column` to this :class:`_schema.Table`.
- The "key" of the newly added :class:`~.schema.Column`, i.e. the
+ The "key" of the newly added :class:`_schema.Column`, i.e. the
value of its ``.key`` attribute, will then be available
- in the ``.c`` collection of this :class:`~.schema.Table`, and the
+ in the ``.c`` collection of this :class:`_schema.Table`, and the
column definition will be included in any CREATE TABLE, SELECT,
- UPDATE, etc. statements generated from this :class:`~.schema.Table`
+ UPDATE, etc. statements generated from this :class:`_schema.Table`
construct.
Note that this does **not** change the definition of the table
@@ -741,13 +796,13 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
column._set_parent_with_dispatch(self)
def append_constraint(self, constraint):
- """Append a :class:`~.schema.Constraint` to this
- :class:`~.schema.Table`.
+ """Append a :class:`_schema.Constraint` to this
+ :class:`_schema.Table`.
This has the effect of the constraint being included in any
future CREATE TABLE statement, assuming specific DDL creation
events have not been associated with the given
- :class:`~.schema.Constraint` object.
+ :class:`_schema.Constraint` object.
Note that this does **not** produce the constraint within the
relational database automatically, for a table that already exists
@@ -782,9 +837,9 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
@util.deprecated(
"1.4",
- "The :meth:`.Table.exists` method is deprecated and will be "
+ "The :meth:`_schema.Table.exists` method is deprecated and will be "
"removed in a future release. Please refer to "
- ":meth:`.Inspector.has_table`.",
+ ":meth:`_reflection.Inspector.has_table`.",
)
def exists(self, bind=None):
"""Return True if this table exists.
@@ -799,12 +854,12 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
def create(self, bind=None, checkfirst=False):
"""Issue a ``CREATE`` statement for this
- :class:`.Table`, using the given :class:`.Connectable`
+ :class:`_schema.Table`, using the given :class:`.Connectable`
for connectivity.
.. seealso::
- :meth:`.MetaData.create_all`.
+ :meth:`_schema.MetaData.create_all`.
"""
@@ -814,12 +869,12 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
def drop(self, bind=None, checkfirst=False):
"""Issue a ``DROP`` statement for this
- :class:`.Table`, using the given :class:`.Connectable`
+ :class:`_schema.Table`, using the given :class:`.Connectable`
for connectivity.
.. seealso::
- :meth:`.MetaData.drop_all`.
+ :meth:`_schema.MetaData.drop_all`.
"""
if bind is None:
@@ -833,8 +888,9 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
referred_schema_fn=None,
name=None,
):
- """Return a copy of this :class:`.Table` associated with a different
- :class:`.MetaData`.
+ """Return a copy of this :class:`_schema.Table`
+ associated with a different
+ :class:`_schema.MetaData`.
E.g.::
@@ -845,16 +901,19 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
m2 = MetaData()
user_copy = user.tometadata(m2)
- :param metadata: Target :class:`.MetaData` object, into which the
- new :class:`.Table` object will be created.
+ :param metadata: Target :class:`_schema.MetaData` object,
+ into which the
+ new :class:`_schema.Table` object will be created.
:param schema: optional string name indicating the target schema.
Defaults to the special symbol :attr:`.RETAIN_SCHEMA` which indicates
that no change to the schema name should be made in the new
- :class:`.Table`. If set to a string name, the new :class:`.Table`
+ :class:`_schema.Table`. If set to a string name, the new
+ :class:`_schema.Table`
will have this new name as the ``.schema``. If set to ``None``, the
schema will be set to that of the schema set on the target
- :class:`.MetaData`, which is typically ``None`` as well, unless
+ :class:`_schema.MetaData`, which is typically ``None`` as well,
+ unless
set explicitly::
m2 = MetaData(schema='newschema')
@@ -869,10 +928,10 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
:param referred_schema_fn: optional callable which can be supplied
in order to provide for the schema name that should be assigned
- to the referenced table of a :class:`.ForeignKeyConstraint`.
- The callable accepts this parent :class:`.Table`, the
+ to the referenced table of a :class:`_schema.ForeignKeyConstraint`.
+ The callable accepts this parent :class:`_schema.Table`, the
target schema that we are changing to, the
- :class:`.ForeignKeyConstraint` object, and the existing
+ :class:`_schema.ForeignKeyConstraint` object, and the existing
"target schema" of that constraint. The function should return the
string schema name that should be applied.
E.g.::
@@ -891,7 +950,8 @@ class Table(DialectKWArgs, SchemaItem, TableClause):
:param name: optional string name indicating the target table name.
If not specified or None, the table name is retained. This allows
- a :class:`.Table` to be copied to the same :class:`.MetaData` target
+ a :class:`_schema.Table` to be copied to the same
+ :class:`_schema.MetaData` target
with a new name.
.. versionadded:: 1.0.0
@@ -985,7 +1045,7 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause):
The name field may be omitted at construction time and applied
later, at any time before the Column is associated with a
- :class:`.Table`. This is to support convenient
+ :class:`_schema.Table`. This is to support convenient
usage within the :mod:`~sqlalchemy.ext.declarative` extension.
:param type\_: The column's type, indicated using an instance which
@@ -1004,21 +1064,24 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause):
If the ``type`` is ``None`` or is omitted, it will first default to
the special type :class:`.NullType`. If and when this
- :class:`.Column` is made to refer to another column using
- :class:`.ForeignKey` and/or :class:`.ForeignKeyConstraint`, the type
+ :class:`_schema.Column` is made to refer to another column using
+ :class:`_schema.ForeignKey` and/or
+ :class:`_schema.ForeignKeyConstraint`, the type
of the remote-referenced column will be copied to this column as
well, at the moment that the foreign key is resolved against that
- remote :class:`.Column` object.
+ remote :class:`_schema.Column` object.
.. versionchanged:: 0.9.0
- Support for propagation of type to a :class:`.Column` from its
- :class:`.ForeignKey` object has been improved and should be
+ Support for propagation of type to a :class:`_schema.Column`
+ from its
+ :class:`_schema.ForeignKey` object has been improved and should be
more reliable and timely.
:param \*args: Additional positional arguments include various
:class:`.SchemaItem` derived constructs which will be applied
as options to the column. These include instances of
- :class:`.Constraint`, :class:`.ForeignKey`, :class:`.ColumnDefault`,
+ :class:`.Constraint`, :class:`_schema.ForeignKey`,
+ :class:`.ColumnDefault`,
:class:`.Sequence`, :class:`.Computed`. In some cases an
equivalent keyword argument is available such as ``server_default``,
``default`` and ``unique``.
@@ -1053,7 +1116,8 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause):
(multi-column) primary keys, autoincrement is never implicitly
enabled; as always, ``autoincrement=True`` will allow for
at most one of those columns to be an "autoincrement" column.
- ``autoincrement=True`` may also be set on a :class:`.Column`
+ ``autoincrement=True`` may also be set on a
+ :class:`_schema.Column`
that has an explicit client-side or server-side default,
subject to limitations of the backend database and dialect.
@@ -1064,7 +1128,8 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause):
* Part of the primary key
- * Not referring to another column via :class:`.ForeignKey`, unless
+ * Not referring to another column via :class:`_schema.ForeignKey`,
+ unless
the value is specified as ``'ignore_fk'``::
# turn on autoincrement for this column despite
@@ -1102,14 +1167,15 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause):
:param default: A scalar, Python callable, or
- :class:`.ColumnElement` expression representing the
+ :class:`_expression.ColumnElement` expression representing the
*default value* for this column, which will be invoked upon insert
if this column is otherwise not specified in the VALUES clause of
the insert. This is a shortcut to using :class:`.ColumnDefault` as
a positional argument; see that class for full detail on the
structure of the argument.
- Contrast this argument to :paramref:`.Column.server_default`
+ Contrast this argument to
+ :paramref:`_schema.Column.server_default`
which creates a default generator on the database side.
.. seealso::
@@ -1118,11 +1184,13 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause):
:param doc: optional String that can be used by the ORM or similar
to document attributes on the Python side. This attribute does
- **not** render SQL comments; use the :paramref:`.Column.comment`
+ **not** render SQL comments; use the
+ :paramref:`_schema.Column.comment`
parameter for this purpose.
:param key: An optional string identifier which will identify this
- ``Column`` object on the :class:`.Table`. When a key is provided,
+ ``Column`` object on the :class:`_schema.Table`.
+ When a key is provided,
this is the only identifier referencing the ``Column`` within the
application, including ORM attribute mapping; the ``name`` field
is used only when rendering SQL.
@@ -1141,7 +1209,8 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause):
``True``, will normally generate nothing (in SQL this defaults to
"NULL"), except in some very specific backend-specific edge cases
where "NULL" may render explicitly. Defaults to ``True`` unless
- :paramref:`~.Column.primary_key` is also ``True``, in which case it
+ :paramref:`_schema.Column.primary_key` is also ``True``,
+ in which case it
defaults to ``False``. This parameter is only used when issuing
CREATE TABLE statements.
@@ -1160,7 +1229,7 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause):
:param primary_key: If ``True``, marks this column as a primary key
column. Multiple columns can have this flag set to specify
composite primary keys. As an alternative, the primary key of a
- :class:`.Table` can be specified via an explicit
+ :class:`_schema.Table` can be specified via an explicit
:class:`.PrimaryKeyConstraint` object.
:param server_default: A :class:`.FetchedValue` instance, str, Unicode
@@ -1233,8 +1302,9 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause):
:param comment: Optional string that will render an SQL comment on
table creation.
- .. versionadded:: 1.2 Added the :paramref:`.Column.comment`
- parameter to :class:`.Column`.
+ .. versionadded:: 1.2 Added the
+ :paramref:`_schema.Column.comment`
+ parameter to :class:`_schema.Column`.
"""
@@ -1600,7 +1670,8 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause):
class ForeignKey(DialectKWArgs, SchemaItem):
"""Defines a dependency between two columns.
- ``ForeignKey`` is specified as an argument to a :class:`.Column` object,
+ ``ForeignKey`` is specified as an argument to a :class:`_schema.Column`
+ object,
e.g.::
t = Table("remote_table", metadata,
@@ -1609,24 +1680,26 @@ class ForeignKey(DialectKWArgs, SchemaItem):
Note that ``ForeignKey`` is only a marker object that defines
a dependency between two columns. The actual constraint
- is in all cases represented by the :class:`.ForeignKeyConstraint`
+ is in all cases represented by the :class:`_schema.ForeignKeyConstraint`
object. This object will be generated automatically when
- a ``ForeignKey`` is associated with a :class:`.Column` which
- in turn is associated with a :class:`.Table`. Conversely,
- when :class:`.ForeignKeyConstraint` is applied to a :class:`.Table`,
+ a ``ForeignKey`` is associated with a :class:`_schema.Column` which
+ in turn is associated with a :class:`_schema.Table`. Conversely,
+ when :class:`_schema.ForeignKeyConstraint` is applied to a
+ :class:`_schema.Table`,
``ForeignKey`` markers are automatically generated to be
- present on each associated :class:`.Column`, which are also
+ present on each associated :class:`_schema.Column`, which are also
associated with the constraint object.
Note that you cannot define a "composite" foreign key constraint,
that is a constraint between a grouping of multiple parent/child
columns, using ``ForeignKey`` objects. To define this grouping,
- the :class:`.ForeignKeyConstraint` object must be used, and applied
- to the :class:`.Table`. The associated ``ForeignKey`` objects
+ the :class:`_schema.ForeignKeyConstraint` object must be used, and applied
+ to the :class:`_schema.Table`. The associated ``ForeignKey`` objects
are created automatically.
The ``ForeignKey`` objects associated with an individual
- :class:`.Column` object are available in the `foreign_keys` collection
+ :class:`_schema.Column`
+ object are available in the `foreign_keys` collection
of that column.
Further examples of foreign key configuration are in
@@ -1654,12 +1727,13 @@ class ForeignKey(DialectKWArgs, SchemaItem):
r"""
Construct a column-level FOREIGN KEY.
- The :class:`.ForeignKey` object when constructed generates a
- :class:`.ForeignKeyConstraint` which is associated with the parent
- :class:`.Table` object's collection of constraints.
+ The :class:`_schema.ForeignKey` object when constructed generates a
+ :class:`_schema.ForeignKeyConstraint`
+ which is associated with the parent
+ :class:`_schema.Table` object's collection of constraints.
:param column: A single target column for the key relationship. A
- :class:`.Column` object or a column name as a string:
+ :class:`_schema.Column` object or a column name as a string:
``tablename.columnkey`` or ``schema.tablename.columnkey``.
``columnkey`` is the ``key`` which has been assigned to the column
(defaults to the column name itself), unless ``link_to_name`` is
@@ -1687,14 +1761,15 @@ class ForeignKey(DialectKWArgs, SchemaItem):
assigned ``key``.
:param use_alter: passed to the underlying
- :class:`.ForeignKeyConstraint` to indicate the constraint should
+ :class:`_schema.ForeignKeyConstraint`
+ to indicate the constraint should
be generated/dropped externally from the CREATE TABLE/ DROP TABLE
- statement. See :paramref:`.ForeignKeyConstraint.use_alter`
+ statement. See :paramref:`_schema.ForeignKeyConstraint.use_alter`
for further description.
.. seealso::
- :paramref:`.ForeignKeyConstraint.use_alter`
+ :paramref:`_schema.ForeignKeyConstraint.use_alter`
:ref:`use_alter`
@@ -1710,7 +1785,8 @@ class ForeignKey(DialectKWArgs, SchemaItem):
:param \**dialect_kw: Additional keyword arguments are dialect
specific, and passed in the form ``<dialectname>_<argname>``. The
arguments are ultimately handled by a corresponding
- :class:`.ForeignKeyConstraint`. See the documentation regarding
+ :class:`_schema.ForeignKeyConstraint`.
+ See the documentation regarding
an individual dialect at :ref:`dialect_toplevel` for detail on
documented arguments.
@@ -1756,16 +1832,16 @@ class ForeignKey(DialectKWArgs, SchemaItem):
return "ForeignKey(%r)" % self._get_colspec()
def copy(self, schema=None):
- """Produce a copy of this :class:`.ForeignKey` object.
+ """Produce a copy of this :class:`_schema.ForeignKey` object.
- The new :class:`.ForeignKey` will not be bound
- to any :class:`.Column`.
+ The new :class:`_schema.ForeignKey` will not be bound
+ to any :class:`_schema.Column`.
This method is usually used by the internal
- copy procedures of :class:`.Column`, :class:`.Table`,
- and :class:`.MetaData`.
+ copy procedures of :class:`_schema.Column`, :class:`_schema.Table`,
+ and :class:`_schema.MetaData`.
- :param schema: The returned :class:`.ForeignKey` will
+ :param schema: The returned :class:`_schema.ForeignKey` will
reference the original table and column name, qualified
by the given string schema name.
@@ -1787,7 +1863,7 @@ class ForeignKey(DialectKWArgs, SchemaItem):
def _get_colspec(self, schema=None, table_name=None):
"""Return a string based 'column specification' for this
- :class:`.ForeignKey`.
+ :class:`_schema.ForeignKey`.
This is usually the equivalent of the string-based "tablename.colname"
argument first passed to the object's constructor.
@@ -1829,17 +1905,20 @@ class ForeignKey(DialectKWArgs, SchemaItem):
target_fullname = property(_get_colspec)
def references(self, table):
- """Return True if the given :class:`.Table` is referenced by this
- :class:`.ForeignKey`."""
+ """Return True if the given :class:`_schema.Table`
+ is referenced by this
+ :class:`_schema.ForeignKey`."""
return table.corresponding_column(self.column) is not None
def get_referent(self, table):
- """Return the :class:`.Column` in the given :class:`.Table`
- referenced by this :class:`.ForeignKey`.
+ """Return the :class:`_schema.Column` in the given
+ :class:`_schema.Table`
+ referenced by this :class:`_schema.ForeignKey`.
- Returns None if this :class:`.ForeignKey` does not reference the given
- :class:`.Table`.
+ Returns None if this :class:`_schema.ForeignKey`
+ does not reference the given
+ :class:`_schema.Table`.
"""
@@ -1966,8 +2045,8 @@ class ForeignKey(DialectKWArgs, SchemaItem):
@util.memoized_property
def column(self):
- """Return the target :class:`.Column` referenced by this
- :class:`.ForeignKey`.
+ """Return the target :class:`_schema.Column` referenced by this
+ :class:`_schema.ForeignKey`.
If no target column has been established, an exception
is raised.
@@ -2097,7 +2176,8 @@ class DefaultGenerator(SchemaItem):
@util.deprecated_20(
":meth:`.DefaultGenerator.execute`",
alternative="All statement execution in SQLAlchemy 2.0 is performed "
- "by the :meth:`.Connection.execute` method of :class:`.Connection`, "
+ "by the :meth:`_engine.Connection.execute` method of "
+ ":class:`_engine.Connection`, "
"or in the ORM by the :meth:`.Session.execute` method of "
":class:`.Session`.",
)
@@ -2126,7 +2206,7 @@ class ColumnDefault(DefaultGenerator):
:class:`.ColumnDefault` is generated automatically
whenever the ``default``, ``onupdate`` arguments of
- :class:`.Column` are used. A :class:`.ColumnDefault`
+ :class:`_schema.Column` are used. A :class:`.ColumnDefault`
can be passed positionally as well.
For example, the following::
@@ -2151,7 +2231,7 @@ class ColumnDefault(DefaultGenerator):
string, integer, boolean, or other simple type.
The default value will be used as is each time.
* a SQL expression, that is one which derives from
- :class:`.ColumnElement`. The SQL expression will
+ :class:`_expression.ColumnElement`. The SQL expression will
be rendered into the INSERT or UPDATE statement,
or in the case of a primary key column when
RETURNING is not used may be
@@ -2162,7 +2242,7 @@ class ColumnDefault(DefaultGenerator):
zero or one positional arguments. The one-argument form
will receive an instance of the :class:`.ExecutionContext`,
which provides contextual information as to the current
- :class:`.Connection` in use as well as the current
+ :class:`_engine.Connection` in use as well as the current
statement and parameters.
"""
@@ -2236,8 +2316,9 @@ class Sequence(roles.StatementRole, DefaultGenerator):
The :class:`.Sequence` object represents the name and configurational
parameters of a database sequence. It also represents
- a construct that can be "executed" by a SQLAlchemy :class:`.Engine`
- or :class:`.Connection`, rendering the appropriate "next value" function
+ a construct that can be "executed" by a SQLAlchemy :class:`_engine.Engine`
+ or :class:`_engine.Connection`,
+ rendering the appropriate "next value" function
for the target database and returning a result.
The :class:`.Sequence` is typically associated with a primary key column::
@@ -2248,7 +2329,7 @@ class Sequence(roles.StatementRole, DefaultGenerator):
primary_key=True)
)
- When CREATE TABLE is emitted for the above :class:`.Table`, if the
+ When CREATE TABLE is emitted for the above :class:`_schema.Table`, if the
target platform supports sequences, a CREATE SEQUENCE statement will
be emitted as well. For platforms that don't support sequences,
the :class:`.Sequence` construct is ignored.
@@ -2348,8 +2429,9 @@ class Sequence(roles.StatementRole, DefaultGenerator):
:param schema: Optional schema name for the sequence, if located
in a schema other than the default. The rules for selecting the
- schema name when a :class:`.MetaData` is also present are the same
- as that of :paramref:`.Table.schema`.
+ schema name when a :class:`_schema.MetaData`
+ is also present are the same
+ as that of :paramref:`_schema.Table.schema`.
:param cache: optional integer value; number of future values in the
sequence which are calculated in advance. Renders the CACHE keyword
@@ -2377,27 +2459,32 @@ class Sequence(roles.StatementRole, DefaultGenerator):
:param quote_schema: set the quoting preferences for the ``schema``
name.
- :param metadata: optional :class:`.MetaData` object which this
+ :param metadata: optional :class:`_schema.MetaData` object which this
:class:`.Sequence` will be associated with. A :class:`.Sequence`
- that is associated with a :class:`.MetaData` gains the following
+ that is associated with a :class:`_schema.MetaData`
+ gains the following
capabilities:
- * The :class:`.Sequence` will inherit the :paramref:`.MetaData.schema`
- parameter specified to the target :class:`.MetaData`, which
+ * The :class:`.Sequence` will inherit the
+ :paramref:`_schema.MetaData.schema`
+ parameter specified to the target :class:`_schema.MetaData`, which
affects the production of CREATE / DROP DDL, if any.
* The :meth:`.Sequence.create` and :meth:`.Sequence.drop` methods
- automatically use the engine bound to the :class:`.MetaData`
+ automatically use the engine bound to the :class:`_schema.MetaData`
object, if any.
- * The :meth:`.MetaData.create_all` and :meth:`.MetaData.drop_all`
+ * The :meth:`_schema.MetaData.create_all` and
+ :meth:`_schema.MetaData.drop_all`
methods will emit CREATE / DROP for this :class:`.Sequence`,
even if the :class:`.Sequence` is not associated with any
- :class:`.Table` / :class:`.Column` that's a member of this
- :class:`.MetaData`.
+ :class:`_schema.Table` / :class:`_schema.Column`
+ that's a member of this
+ :class:`_schema.MetaData`.
The above behaviors can only occur if the :class:`.Sequence` is
- explicitly associated with the :class:`.MetaData` via this parameter.
+ explicitly associated with the :class:`_schema.MetaData`
+ via this parameter.
.. seealso::
@@ -2405,7 +2492,8 @@ class Sequence(roles.StatementRole, DefaultGenerator):
:paramref:`.Sequence.metadata` parameter.
:param for_update: Indicates this :class:`.Sequence`, when associated
- with a :class:`.Column`, should be invoked for UPDATE statements
+ with a :class:`_schema.Column`,
+ should be invoked for UPDATE statements
on that column's table, rather than for INSERT statements, when
no value is otherwise present for that column in the statement.
@@ -2555,7 +2643,7 @@ class DefaultClause(FetchedValue):
:class:`.DefaultClause` is generated automatically
whenever the ``server_default``, ``server_onupdate`` arguments of
- :class:`.Column` are used. A :class:`.DefaultClause`
+ :class:`_schema.Column` are used. A :class:`.DefaultClause`
can be passed positionally as well.
For example, the following::
@@ -2672,7 +2760,8 @@ class Constraint(DialectKWArgs, SchemaItem):
class ColumnCollectionMixin(object):
columns = None
- """A :class:`.ColumnCollection` of :class:`.Column` objects.
+ """A :class:`_expression.ColumnCollection` of :class:`_schema.Column`
+ objects.
This collection represents the columns which are referred to by
this object.
@@ -2799,7 +2888,7 @@ class ColumnCollectionConstraint(ColumnCollectionMixin, Constraint):
)
columns = None
- """A :class:`.ColumnCollection` representing the set of columns
+ """A :class:`_expression.ColumnCollection` representing the set of columns
for this constraint.
"""
@@ -2824,7 +2913,8 @@ class ColumnCollectionConstraint(ColumnCollectionMixin, Constraint):
"""Return True if this constraint contains the given column.
Note that this object also contains an attribute ``.columns``
- which is a :class:`.ColumnCollection` of :class:`.Column` objects.
+ which is a :class:`_expression.ColumnCollection` of
+ :class:`_schema.Column` objects.
"""
@@ -2870,7 +2960,8 @@ class CheckConstraint(ColumnCollectionConstraint):
:param sqltext:
A string containing the constraint definition, which will be used
verbatim, or a SQL expression construct. If given as a string,
- the object is converted to a :func:`.text` object. If the textual
+ the object is converted to a :func:`_expression.text` object.
+ If the textual
string includes a colon character, escape this using a backslash::
CheckConstraint(r"foo ~ E'a(?\:b|c)d")
@@ -2938,9 +3029,10 @@ class ForeignKeyConstraint(ColumnCollectionConstraint):
Defines a single column or composite FOREIGN KEY ... REFERENCES
constraint. For a no-frills, single column foreign key, adding a
- :class:`.ForeignKey` to the definition of a :class:`.Column` is a
+ :class:`_schema.ForeignKey` to the definition of a :class:`_schema.Column`
+ is a
shorthand equivalent for an unnamed, single column
- :class:`.ForeignKeyConstraint`.
+ :class:`_schema.ForeignKeyConstraint`.
Examples of foreign key configuration are in :ref:`metadata_foreignkeys`.
@@ -3000,16 +3092,17 @@ class ForeignKeyConstraint(ColumnCollectionConstraint):
have been created, and drop it via an ALTER TABLE statement before
the full collection of tables are dropped.
- The use of :paramref:`.ForeignKeyConstraint.use_alter` is
+ The use of :paramref:`_schema.ForeignKeyConstraint.use_alter` is
particularly geared towards the case where two or more tables
are established within a mutually-dependent foreign key constraint
- relationship; however, the :meth:`.MetaData.create_all` and
- :meth:`.MetaData.drop_all` methods will perform this resolution
+ relationship; however, the :meth:`_schema.MetaData.create_all` and
+ :meth:`_schema.MetaData.drop_all`
+ methods will perform this resolution
automatically, so the flag is normally not needed.
.. versionchanged:: 1.0.0 Automatic resolution of foreign key
cycles has been added, removing the need to use the
- :paramref:`.ForeignKeyConstraint.use_alter` in typical use
+ :paramref:`_schema.ForeignKeyConstraint.use_alter` in typical use
cases.
.. seealso::
@@ -3097,15 +3190,16 @@ class ForeignKeyConstraint(ColumnCollectionConstraint):
self.elements.append(fk)
columns = None
- """A :class:`.ColumnCollection` representing the set of columns
+ """A :class:`_expression.ColumnCollection` representing the set of columns
for this constraint.
"""
elements = None
- """A sequence of :class:`.ForeignKey` objects.
+ """A sequence of :class:`_schema.ForeignKey` objects.
- Each :class:`.ForeignKey` represents a single referring column/referred
+ Each :class:`_schema.ForeignKey`
+ represents a single referring column/referred
column pair.
This collection is intended to be read-only.
@@ -3126,8 +3220,8 @@ class ForeignKeyConstraint(ColumnCollectionConstraint):
@property
def referred_table(self):
- """The :class:`.Table` object to which this
- :class:`.ForeignKeyConstraint` references.
+ """The :class:`_schema.Table` object to which this
+ :class:`_schema.ForeignKeyConstraint` references.
This is a dynamically calculated attribute which may not be available
if the constraint and/or parent table is not yet associated with
@@ -3151,11 +3245,11 @@ class ForeignKeyConstraint(ColumnCollectionConstraint):
@property
def column_keys(self):
"""Return a list of string keys representing the local
- columns in this :class:`.ForeignKeyConstraint`.
+ columns in this :class:`_schema.ForeignKeyConstraint`.
This list is either the original string arguments sent
- to the constructor of the :class:`.ForeignKeyConstraint`,
- or if the constraint has been initialized with :class:`.Column`
+ to the constructor of the :class:`_schema.ForeignKeyConstraint`,
+ or if the constraint has been initialized with :class:`_schema.Column`
objects, is the string .key of each element.
.. versionadded:: 1.0.0
@@ -3225,9 +3319,9 @@ class PrimaryKeyConstraint(ColumnCollectionConstraint):
"""A table-level PRIMARY KEY constraint.
The :class:`.PrimaryKeyConstraint` object is present automatically
- on any :class:`.Table` object; it is assigned a set of
- :class:`.Column` objects corresponding to those marked with
- the :paramref:`.Column.primary_key` flag::
+ on any :class:`_schema.Table` object; it is assigned a set of
+ :class:`_schema.Column` objects corresponding to those marked with
+ the :paramref:`_schema.Column.primary_key` flag::
>>> my_table = Table('mytable', metadata,
... Column('id', Integer, primary_key=True),
@@ -3242,7 +3336,7 @@ class PrimaryKeyConstraint(ColumnCollectionConstraint):
primary_key=True, nullable=False)
)
- The primary key of a :class:`.Table` can also be specified by using
+ The primary key of a :class:`_schema.Table` can also be specified by using
a :class:`.PrimaryKeyConstraint` object explicitly; in this mode of usage,
the "name" of the constraint can also be specified, as well as other
options which may be recognized by dialects::
@@ -3275,7 +3369,7 @@ class PrimaryKeyConstraint(ColumnCollectionConstraint):
:class:`.PrimaryKeyConstraint`, but the usual style of using
``primary_key=True`` flags is still desirable, an empty
:class:`.PrimaryKeyConstraint` may be specified, which will take on the
- primary key column collection from the :class:`.Table` based on the
+ primary key column collection from the :class:`_schema.Table` based on the
flags::
my_table = Table('mytable', metadata,
@@ -3289,7 +3383,7 @@ class PrimaryKeyConstraint(ColumnCollectionConstraint):
.. versionadded:: 0.9.2 an empty :class:`.PrimaryKeyConstraint` may now
be specified for the purposes of establishing keyword arguments with
the constraint, independently of the specification of "primary key"
- columns within the :class:`.Table` itself; columns marked as
+ columns within the :class:`_schema.Table` itself; columns marked as
``primary_key=True`` will be gathered into the empty constraint's
column collection.
@@ -3342,7 +3436,7 @@ class PrimaryKeyConstraint(ColumnCollectionConstraint):
This is basically like putting a whole new
:class:`.PrimaryKeyConstraint` object on the parent
- :class:`.Table` object without actually replacing the object.
+ :class:`_schema.Table` object without actually replacing the object.
The ordering of the given list of columns is also maintained; these
columns will be appended to the list of columns after any which
@@ -3457,7 +3551,7 @@ class Index(DialectKWArgs, ColumnCollectionMixin, SchemaItem):
Index("some_index", sometable.c.name)
For a no-frills, single column index, adding
- :class:`.Column` also supports ``index=True``::
+ :class:`_schema.Column` also supports ``index=True``::
sometable = Table("sometable", metadata,
Column("name", String(50), index=True)
@@ -3469,13 +3563,15 @@ class Index(DialectKWArgs, ColumnCollectionMixin, SchemaItem):
Functional indexes are supported as well, typically by using the
:data:`.func` construct in conjunction with table-bound
- :class:`.Column` objects::
+ :class:`_schema.Column` objects::
Index("some_index", func.lower(sometable.c.name))
- An :class:`.Index` can also be manually associated with a :class:`.Table`,
+ An :class:`.Index` can also be manually associated with a
+ :class:`_schema.Table`,
either through inline declaration or using
- :meth:`.Table.append_constraint`. When this approach is used, the names
+ :meth:`_schema.Table.append_constraint`. When this approach is used,
+ the names
of the indexed columns can be specified as strings::
Table("sometable", metadata,
@@ -3485,7 +3581,7 @@ class Index(DialectKWArgs, ColumnCollectionMixin, SchemaItem):
)
To support functional or expression-based indexes in this form, the
- :func:`.text` construct may be used::
+ :func:`_expression.text` construct may be used::
from sqlalchemy import text
@@ -3495,9 +3591,10 @@ class Index(DialectKWArgs, ColumnCollectionMixin, SchemaItem):
Index("some_index", text("lower(name)"))
)
- .. versionadded:: 0.9.5 the :func:`.text` construct may be used to
+ .. versionadded:: 0.9.5 the :func:`_expression.text`
+ construct may be used to
specify :class:`.Index` expressions, provided the :class:`.Index`
- is explicitly associated with the :class:`.Table`.
+ is explicitly associated with the :class:`_schema.Table`.
.. seealso::
@@ -3525,9 +3622,9 @@ class Index(DialectKWArgs, ColumnCollectionMixin, SchemaItem):
:param \*expressions:
Column expressions to include in the index. The expressions
- are normally instances of :class:`.Column`, but may also
+ are normally instances of :class:`_schema.Column`, but may also
be arbitrary SQL expressions which ultimately refer to a
- :class:`.Column`.
+ :class:`_schema.Column`.
:param unique=False:
Keyword only argument; if True, create a unique index.
@@ -3535,7 +3632,7 @@ class Index(DialectKWArgs, ColumnCollectionMixin, SchemaItem):
:param quote=None:
Keyword only argument; whether to apply quoting to the name of
the index. Works in the same manner as that of
- :paramref:`.Column.quote`.
+ :paramref:`_schema.Column.quote`.
:param info=None: Optional data dictionary which will be populated
into the :attr:`.SchemaItem.info` attribute of this object.
@@ -3610,7 +3707,7 @@ class Index(DialectKWArgs, ColumnCollectionMixin, SchemaItem):
.. seealso::
- :meth:`.MetaData.create_all`.
+ :meth:`_schema.MetaData.create_all`.
"""
if bind is None:
@@ -3625,7 +3722,7 @@ class Index(DialectKWArgs, ColumnCollectionMixin, SchemaItem):
.. seealso::
- :meth:`.MetaData.drop_all`.
+ :meth:`_schema.MetaData.drop_all`.
"""
if bind is None:
@@ -3646,20 +3743,22 @@ DEFAULT_NAMING_CONVENTION = util.immutabledict({"ix": "ix_%(column_0_label)s"})
class MetaData(SchemaItem):
- """A collection of :class:`.Table` objects and their associated schema
+ """A collection of :class:`_schema.Table`
+ objects and their associated schema
constructs.
- Holds a collection of :class:`.Table` objects as well as
- an optional binding to an :class:`.Engine` or
- :class:`.Connection`. If bound, the :class:`.Table` objects
+ Holds a collection of :class:`_schema.Table` objects as well as
+ an optional binding to an :class:`_engine.Engine` or
+ :class:`_engine.Connection`. If bound, the :class:`_schema.Table` objects
in the collection and their columns may participate in implicit SQL
execution.
- The :class:`.Table` objects themselves are stored in the
- :attr:`.MetaData.tables` dictionary.
+ The :class:`_schema.Table` objects themselves are stored in the
+ :attr:`_schema.MetaData.tables` dictionary.
- :class:`.MetaData` is a thread-safe object for read operations.
- Construction of new tables within a single :class:`.MetaData` object,
+ :class:`_schema.MetaData` is a thread-safe object for read operations.
+ Construction of new tables within a single :class:`_schema.MetaData`
+ object,
either explicitly or via reflection, may not be completely thread-safe.
.. seealso::
@@ -3690,37 +3789,46 @@ class MetaData(SchemaItem):
Defaults to False. ``bind`` is required when this option is set.
:param schema:
- The default schema to use for the :class:`.Table`,
+ The default schema to use for the :class:`_schema.Table`,
:class:`.Sequence`, and potentially other objects associated with
- this :class:`.MetaData`. Defaults to ``None``.
+ this :class:`_schema.MetaData`. Defaults to ``None``.
- When this value is set, any :class:`.Table` or :class:`.Sequence`
+ When this value is set, any :class:`_schema.Table` or
+ :class:`.Sequence`
which specifies ``None`` for the schema parameter will instead
- have this schema name defined. To build a :class:`.Table`
+ have this schema name defined. To build a :class:`_schema.Table`
or :class:`.Sequence` that still has ``None`` for the schema
even when this parameter is present, use the :attr:`.BLANK_SCHEMA`
symbol.
.. note::
- As referred above, the :paramref:`.MetaData.schema` parameter
+ As referred above, the :paramref:`_schema.MetaData.schema`
+ parameter
only refers to the **default value** that will be applied to
- the :paramref:`.Table.schema` parameter of an incoming
- :class:`.Table` object. It does not refer to how the
- :class:`.Table` is catalogued within the :class:`.MetaData`,
- which remains consistent vs. a :class:`.MetaData` collection
- that does not define this parameter. The :class:`.Table`
- within the :class:`.MetaData` will still be keyed based on its
+ the :paramref:`_schema.Table.schema` parameter of an incoming
+ :class:`_schema.Table` object. It does not refer to how the
+ :class:`_schema.Table` is catalogued within the
+ :class:`_schema.MetaData`,
+ which remains consistent vs. a :class:`_schema.MetaData`
+ collection
+ that does not define this parameter. The
+ :class:`_schema.Table`
+ within the :class:`_schema.MetaData`
+ will still be keyed based on its
schema-qualified name, e.g.
``my_metadata.tables["some_schema.my_table"]``.
- The current behavior of the :class:`.ForeignKey` object is to
+ The current behavior of the :class:`_schema.ForeignKey`
+ object is to
circumvent this restriction, where it can locate a table given
the table name alone, where the schema will be assumed to be
present from this value as specified on the owning
- :class:`.MetaData` collection. However, this implies that a
+ :class:`_schema.MetaData` collection. However,
+ this implies that a
table qualified with BLANK_SCHEMA cannot currently be referred
- to by string name from :class:`.ForeignKey`. Other parts of
+ to by string name from :class:`_schema.ForeignKey`.
+ Other parts of
SQLAlchemy such as Declarative may not have similar behaviors
built in, however may do so in a future release, along with a
consistent method of referring to a table in BLANK_SCHEMA.
@@ -3728,12 +3836,12 @@ class MetaData(SchemaItem):
.. seealso::
- :paramref:`.Table.schema`
+ :paramref:`_schema.Table.schema`
:paramref:`.Sequence.schema`
:param quote_schema:
- Sets the ``quote_schema`` flag for those :class:`.Table`,
+ Sets the ``quote_schema`` flag for those :class:`_schema.Table`,
:class:`.Sequence`, and other objects which make usage of the
local ``schema`` name.
@@ -3750,7 +3858,8 @@ class MetaData(SchemaItem):
The keys of this dictionary may be:
* a constraint or Index class, e.g. the :class:`.UniqueConstraint`,
- :class:`.ForeignKeyConstraint` class, the :class:`.Index` class
+ :class:`_schema.ForeignKeyConstraint` class, the :class:`.Index`
+ class
* a string mnemonic for one of the known constraint classes;
``"fk"``, ``"pk"``, ``"ix"``, ``"ck"``, ``"uq"`` for foreign key,
@@ -3765,45 +3874,49 @@ class MetaData(SchemaItem):
which describe how the name should be composed. The values
associated with user-defined "token" keys should be callables of the
form ``fn(constraint, table)``, which accepts the constraint/index
- object and :class:`.Table` as arguments, returning a string
+ object and :class:`_schema.Table` as arguments, returning a string
result.
The built-in names are as follows, some of which may only be
available for certain types of constraint:
- * ``%(table_name)s`` - the name of the :class:`.Table` object
+ * ``%(table_name)s`` - the name of the :class:`_schema.Table`
+ object
associated with the constraint.
- * ``%(referred_table_name)s`` - the name of the :class:`.Table`
+ * ``%(referred_table_name)s`` - the name of the
+ :class:`_schema.Table`
object associated with the referencing target of a
- :class:`.ForeignKeyConstraint`.
+ :class:`_schema.ForeignKeyConstraint`.
- * ``%(column_0_name)s`` - the name of the :class:`.Column` at
+ * ``%(column_0_name)s`` - the name of the :class:`_schema.Column`
+ at
index position "0" within the constraint.
- * ``%(column_0N_name)s`` - the name of all :class:`.Column`
+ * ``%(column_0N_name)s`` - the name of all :class:`_schema.Column`
objects in order within the constraint, joined without a
separator.
- * ``%(column_0_N_name)s`` - the name of all :class:`.Column`
+ * ``%(column_0_N_name)s`` - the name of all
+ :class:`_schema.Column`
objects in order within the constraint, joined with an
underscore as a separator.
* ``%(column_0_label)s``, ``%(column_0N_label)s``,
``%(column_0_N_label)s`` - the label of either the zeroth
- :class:`.Column` or all :class:`.Columns`, separated with
+ :class:`_schema.Column` or all :class:`.Columns`, separated with
or without an underscore
* ``%(column_0_key)s``, ``%(column_0N_key)s``,
``%(column_0_N_key)s`` - the key of either the zeroth
- :class:`.Column` or all :class:`.Columns`, separated with
+ :class:`_schema.Column` or all :class:`.Columns`, separated with
or without an underscore
* ``%(referred_column_0_name)s``, ``%(referred_column_0N_name)s``
``%(referred_column_0_N_name)s``, ``%(referred_column_0_key)s``,
``%(referred_column_0N_key)s``, ... column tokens which
render the names/keys/labels of columns that are referenced
- by a :class:`.ForeignKeyConstraint`.
+ by a :class:`_schema.ForeignKeyConstraint`.
* ``%(constraint_name)s`` - a special key that refers to the
existing name given to the constraint. When this key is
@@ -3843,16 +3956,20 @@ class MetaData(SchemaItem):
self.bind = bind
tables = None
- """A dictionary of :class:`.Table` objects keyed to their name or "table key".
-
- The exact key is that determined by the :attr:`.Table.key` attribute;
- for a table with no :attr:`.Table.schema` attribute, this is the same
- as :attr:`.Table.name`. For a table with a schema, it is typically of the
+ """A dictionary of :class:`_schema.Table`
+ objects keyed to their name or "table key".
+
+ The exact key is that determined by the :attr:`_schema.Table.key`
+ attribute;
+ for a table with no :attr:`_schema.Table.schema` attribute,
+ this is the same
+ as :attr:`_schema.Table.name`. For a table with a schema,
+ it is typically of the
form ``schemaname.tablename``.
.. seealso::
- :attr:`.MetaData.sorted_tables`
+ :attr:`_schema.MetaData.sorted_tables`
"""
@@ -3910,10 +4027,11 @@ class MetaData(SchemaItem):
return self._bind is not None
def bind(self):
- """An :class:`.Engine` or :class:`.Connection` to which this
- :class:`.MetaData` is bound.
+ """An :class:`_engine.Engine` or :class:`_engine.Connection`
+ to which this
+ :class:`_schema.MetaData` is bound.
- Typically, a :class:`.Engine` is assigned to this attribute
+ Typically, a :class:`_engine.Engine` is assigned to this attribute
so that "implicit execution" may be used, or alternatively
as a means of providing engine binding information to an
ORM :class:`.Session` object::
@@ -3953,10 +4071,11 @@ class MetaData(SchemaItem):
@property
def sorted_tables(self):
- """Returns a list of :class:`.Table` objects sorted in order of
+ """Returns a list of :class:`_schema.Table` objects sorted in order of
foreign key dependency.
- The sorting will place :class:`.Table` objects that have dependencies
+ The sorting will place :class:`_schema.Table`
+ objects that have dependencies
first, before the dependencies themselves, representing the
order in which they can be created. To get the order in which
the tables would be dropped, use the ``reversed()`` Python built-in.
@@ -3967,22 +4086,23 @@ class MetaData(SchemaItem):
automatic resolution of dependency cycles between tables, which
are usually caused by mutually dependent foreign key constraints.
To resolve these cycles, either the
- :paramref:`.ForeignKeyConstraint.use_alter` parameter may be
+ :paramref:`_schema.ForeignKeyConstraint.use_alter`
+ parameter may be
applied to those constraints, or use the
- :func:`.schema.sort_tables_and_constraints` function which will
+ :func:`_schema.sort_tables_and_constraints` function which will
break out foreign key constraints involved in cycles separately.
.. seealso::
- :func:`.schema.sort_tables`
+ :func:`_schema.sort_tables`
- :func:`.schema.sort_tables_and_constraints`
+ :func:`_schema.sort_tables_and_constraints`
- :attr:`.MetaData.tables`
+ :attr:`_schema.MetaData.tables`
- :meth:`.Inspector.get_table_names`
+ :meth:`_reflection.Inspector.get_table_names`
- :meth:`.Inspector.get_sorted_table_and_fkc_names`
+ :meth:`_reflection.Inspector.get_sorted_table_and_fkc_names`
"""
@@ -4015,7 +4135,7 @@ class MetaData(SchemaItem):
:param schema:
Optional, query and reflect tables from an alternate schema.
- If None, the schema associated with this :class:`.MetaData`
+ If None, the schema associated with this :class:`_schema.MetaData`
is used, if any.
:param views:
@@ -4035,35 +4155,41 @@ class MetaData(SchemaItem):
with a table name and this ``MetaData`` instance as positional
arguments and should return a true value for any table to reflect.
- :param extend_existing: Passed along to each :class:`.Table` as
- :paramref:`.Table.extend_existing`.
+ :param extend_existing: Passed along to each :class:`_schema.Table` as
+ :paramref:`_schema.Table.extend_existing`.
.. versionadded:: 0.9.1
- :param autoload_replace: Passed along to each :class:`.Table` as
- :paramref:`.Table.autoload_replace`.
+ :param autoload_replace: Passed along to each :class:`_schema.Table`
+ as
+ :paramref:`_schema.Table.autoload_replace`.
.. versionadded:: 0.9.1
- :param resolve_fks: if True, reflect :class:`.Table` objects linked
- to :class:`.ForeignKey` objects located in each :class:`.Table`.
- For :meth:`.MetaData.reflect`, this has the effect of reflecting
+ :param resolve_fks: if True, reflect :class:`_schema.Table`
+ objects linked
+ to :class:`_schema.ForeignKey` objects located in each
+ :class:`_schema.Table`.
+ For :meth:`_schema.MetaData.reflect`,
+ this has the effect of reflecting
related tables that might otherwise not be in the list of tables
being reflected, for example if the referenced table is in a
different schema or is omitted via the
:paramref:`.MetaData.reflect.only` parameter. When False,
- :class:`.ForeignKey` objects are not followed to the :class:`.Table`
+ :class:`_schema.ForeignKey` objects are not followed to the
+ :class:`_schema.Table`
in which they link, however if the related table is also part of the
list of tables that would be reflected in any case, the
- :class:`.ForeignKey` object will still resolve to its related
- :class:`.Table` after the :meth:`.MetaData.reflect` operation is
+ :class:`_schema.ForeignKey` object will still resolve to its related
+ :class:`_schema.Table` after the :meth:`_schema.MetaData.reflect`
+ operation is
complete. Defaults to True.
.. versionadded:: 1.3.0
.. seealso::
- :paramref:`.Table.resolve_fks`
+ :paramref:`_schema.Table.resolve_fks`
:param \**dialect_kwargs: Additional keyword arguments not mentioned
above are dialect specific, and passed in the form
@@ -4073,7 +4199,7 @@ class MetaData(SchemaItem):
.. versionadded:: 0.9.2 - Added
:paramref:`.MetaData.reflect.**dialect_kwargs` to support
- dialect-level reflection options for all :class:`.Table`
+ dialect-level reflection options for all :class:`_schema.Table`
objects reflected.
"""
@@ -4273,7 +4399,7 @@ class Computed(FetchedValue, SchemaItem):
"""Defines a generated column, i.e. "GENERATED ALWAYS AS" syntax.
The :class:`.Computed` construct is an inline construct added to the
- argument list of a :class:`.Column` object::
+ argument list of a :class:`_schema.Column` object::
from sqlalchemy import Computed
@@ -4299,13 +4425,14 @@ class Computed(FetchedValue, SchemaItem):
)
def __init__(self, sqltext, persisted=None):
"""Construct a GENERATED ALWAYS AS DDL construct to accompany a
- :class:`.Column`.
+ :class:`_schema.Column`.
:param sqltext:
A string containing the column generation expression, which will be
- used verbatim, or a SQL expression construct, such as a :func:`.text`
+ used verbatim, or a SQL expression construct, such as a
+ :func:`_expression.text`
object. If given as a string, the object is converted to a
- :func:`.text` object.
+ :func:`_expression.text` object.
:param persisted:
Optional, controls how this column should be persisted by the
diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index 08a237636..bfe5d80ad 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -5,7 +5,8 @@
# This module is part of SQLAlchemy and is released under
# the MIT License: http://www.opensource.org/licenses/mit-license.php
-"""The :class:`.FromClause` class of SQL expression elements, representing
+"""The :class:`_expression.FromClause` class of SQL expression elements,
+representing
SQL tables and derived rowsets.
"""
@@ -70,12 +71,12 @@ class _OffsetLimitParam(BindParameter):
)
def subquery(alias, *args, **kwargs):
r"""Return an :class:`.Subquery` object derived
- from a :class:`.Select`.
+ from a :class:`_expression.Select`.
:param name: the alias name for the subquery
:param \*args, \**kwargs: all other arguments are passed through to the
- :func:`~.sql.expression.select` function.
+ :func:`_expression.select` function.
"""
return Select(*args, **kwargs).subquery(alias)
@@ -107,26 +108,29 @@ class ReturnsRows(roles.ReturnsRowsRole, ClauseElement):
def _exported_columns_iterator(self):
"""An iterator of column objects that represents the "exported"
- columns of this :class:`.ReturnsRows`.
+ columns of this :class:`_expression.ReturnsRows`.
This is the same set of columns as are returned by
- :meth:`.ReturnsRows.exported_columns` except they are returned
+ :meth:`_expression.ReturnsRows.exported_columns`
+ except they are returned
as a simple iterator or sequence, rather than as a
- :class:`.ColumnCollection` namespace.
+ :class:`_expression.ColumnCollection` namespace.
Subclasses should re-implement this method to bypass the interim
- creation of the :class:`.ColumnCollection` if appropriate.
+ creation of the :class:`_expression.ColumnCollection` if appropriate.
"""
return iter(self.exported_columns)
@property
def exported_columns(self):
- """A :class:`.ColumnCollection` that represents the "exported"
- columns of this :class:`.ReturnsRows`.
+ """A :class:`_expression.ColumnCollection`
+ that represents the "exported"
+ columns of this :class:`_expression.ReturnsRows`.
The "exported" columns represent the collection of
- :class:`.ColumnElement` expressions that are rendered by this SQL
+ :class:`_expression.ColumnElement`
+ expressions that are rendered by this SQL
construct. There are primary varieties which are the
"FROM clause columns" of a FROM clause, such as a table, join,
or subquery, the "SELECTed columns", which are the columns in
@@ -137,9 +141,9 @@ class ReturnsRows(roles.ReturnsRowsRole, ClauseElement):
.. seealso:
- :attr:`.FromClause.exported_columns`
+ :attr:`_expression.FromClause.exported_columns`
- :attr:`.SelectBase.exported_columns`
+ :attr:`_expression.SelectBase.exported_columns`
"""
raise NotImplementedError()
@@ -162,10 +166,10 @@ class Selectable(ReturnsRows):
raise NotImplementedError()
def lateral(self, name=None):
- """Return a LATERAL alias of this :class:`.Selectable`.
+ """Return a LATERAL alias of this :class:`expression.Selectable`.
- The return value is the :class:`.Lateral` construct also
- provided by the top-level :func:`~.expression.lateral` function.
+ The return value is the :class:`_expression.Lateral` construct also
+ provided by the top-level :func:`_expression.lateral` function.
.. versionadded:: 1.1
@@ -185,34 +189,40 @@ class Selectable(ReturnsRows):
@util.preload_module("sqlalchemy.sql.util")
def replace_selectable(self, old, alias):
"""replace all occurrences of FromClause 'old' with the given Alias
- object, returning a copy of this :class:`.FromClause`.
+ object, returning a copy of this :class:`_expression.FromClause`.
"""
return util.preloaded.sql_util.ClauseAdapter(alias).traverse(self)
def corresponding_column(self, column, require_embedded=False):
- """Given a :class:`.ColumnElement`, return the exported
- :class:`.ColumnElement` object from the
- :attr:`.Selectable.exported_columns`
- collection of this :class:`.Selectable` which corresponds to that
- original :class:`.ColumnElement` via a common ancestor
+ """Given a :class:`_expression.ColumnElement`, return the exported
+ :class:`_expression.ColumnElement` object from the
+ :attr:`expression.Selectable.exported_columns`
+ collection of this :class:`expression.Selectable`
+ which corresponds to that
+ original :class:`_expression.ColumnElement` via a common ancestor
column.
- :param column: the target :class:`.ColumnElement` to be matched
+ :param column: the target :class:`_expression.ColumnElement`
+ to be matched
:param require_embedded: only return corresponding columns for
- the given :class:`.ColumnElement`, if the given
- :class:`.ColumnElement` is actually present within a sub-element
- of this :class:`.Selectable`. Normally the column will match if
+ the given :class:`_expression.ColumnElement`, if the given
+ :class:`_expression.ColumnElement`
+ is actually present within a sub-element
+ of this :class:`expression.Selectable`.
+ Normally the column will match if
it merely shares a common ancestor with one of the exported
- columns of this :class:`.Selectable`.
+ columns of this :class:`expression.Selectable`.
.. seealso::
- :attr:`.Selectable.exported_columns` - the
- :class:`.ColumnCollection` that is used for the operation
+ :attr:`expression.Selectable.exported_columns` - the
+ :class:`_expression.ColumnCollection`
+ that is used for the operation
- :meth:`.ColumnCollection.corresponding_column` - implementation
+ :meth:`_expression.ColumnCollection.corresponding_column`
+ - implementation
method.
"""
@@ -232,7 +242,7 @@ class HasPrefixes(object):
@_generative
@_document_text_coercion(
"expr",
- ":meth:`.HasPrefixes.prefix_with`",
+ ":meth:`_expression.HasPrefixes.prefix_with`",
":paramref:`.HasPrefixes.prefix_with.*expr`",
)
def prefix_with(self, *expr, **kw):
@@ -251,9 +261,10 @@ class HasPrefixes(object):
"/*+ BKA(t1) */", dialect="mysql")
Multiple prefixes can be specified by multiple calls
- to :meth:`.prefix_with`.
+ to :meth:`_expression.HasPrefixes.prefix_with`.
- :param \*expr: textual or :class:`.ClauseElement` construct which
+ :param \*expr: textual or :class:`_expression.ClauseElement`
+ construct which
will be rendered following the INSERT, UPDATE, or DELETE
keyword.
:param \**kw: A single keyword 'dialect' is accepted. This is an
@@ -287,7 +298,7 @@ class HasSuffixes(object):
@_generative
@_document_text_coercion(
"expr",
- ":meth:`.HasSuffixes.suffix_with`",
+ ":meth:`_expression.HasSuffixes.suffix_with`",
":paramref:`.HasSuffixes.suffix_with.*expr`",
)
def suffix_with(self, *expr, **kw):
@@ -302,9 +313,10 @@ class HasSuffixes(object):
"cycle empno set y_cycle to 1 default 0", dialect="oracle")
Multiple suffixes can be specified by multiple calls
- to :meth:`.suffix_with`.
+ to :meth:`_expression.HasSuffixes.suffix_with`.
- :param \*expr: textual or :class:`.ClauseElement` construct which
+ :param \*expr: textual or :class:`_expression.ClauseElement`
+ construct which
will be rendered following the target clause.
:param \**kw: A single keyword 'dialect' is accepted. This is an
optional string dialect name which will
@@ -331,17 +343,19 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable):
"""Represent an element that can be used within the ``FROM``
clause of a ``SELECT`` statement.
- The most common forms of :class:`.FromClause` are the
- :class:`.Table` and the :func:`~.sql.expression.select` constructs. Key
- features common to all :class:`.FromClause` objects include:
+ The most common forms of :class:`_expression.FromClause` are the
+ :class:`_schema.Table` and the :func:`_expression.select` constructs. Key
+ features common to all :class:`_expression.FromClause` objects include:
* a :attr:`.c` collection, which provides per-name access to a collection
- of :class:`.ColumnElement` objects.
+ of :class:`_expression.ColumnElement` objects.
* a :attr:`.primary_key` attribute, which is a collection of all those
- :class:`.ColumnElement` objects that indicate the ``primary_key`` flag.
+ :class:`_expression.ColumnElement`
+ objects that indicate the ``primary_key`` flag.
* Methods to generate various derivations of a "from" clause, including
- :meth:`.FromClause.alias`, :meth:`.FromClause.join`,
- :meth:`.FromClause.select`.
+ :meth:`_expression.FromClause.alias`,
+ :meth:`_expression.FromClause.join`,
+ :meth:`_expression.FromClause.select`.
"""
@@ -351,11 +365,11 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable):
_hide_froms = []
schema = None
- """Define the 'schema' attribute for this :class:`.FromClause`.
+ """Define the 'schema' attribute for this :class:`_expression.FromClause`.
This is typically ``None`` for most objects except that of
- :class:`.Table`, where it is taken as the value of the
- :paramref:`.Table.schema` argument.
+ :class:`_schema.Table`, where it is taken as the value of the
+ :paramref:`_schema.Table.schema` argument.
"""
@@ -366,11 +380,11 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable):
_use_schema_map = False
def select(self, whereclause=None, **params):
- """return a SELECT of this :class:`.FromClause`.
+ """return a SELECT of this :class:`_expression.FromClause`.
.. seealso::
- :func:`~.sql.expression.select` - general purpose
+ :func:`_expression.select` - general purpose
method which allows for arbitrary column lists.
"""
@@ -378,7 +392,8 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable):
return Select([self], whereclause, **params)
def join(self, right, onclause=None, isouter=False, full=False):
- """Return a :class:`.Join` from this :class:`.FromClause`
+ """Return a :class:`_expression.Join` from this
+ :class:`_expression.FromClause`
to another :class:`FromClause`.
E.g.::
@@ -395,12 +410,14 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable):
JOIN address ON user.id = address.user_id
:param right: the right side of the join; this is any
- :class:`.FromClause` object such as a :class:`.Table` object, and
+ :class:`_expression.FromClause` object such as a
+ :class:`_schema.Table` object, and
may also be a selectable-compatible object such as an ORM-mapped
class.
:param onclause: a SQL expression representing the ON clause of the
- join. If left at ``None``, :meth:`.FromClause.join` will attempt to
+ join. If left at ``None``, :meth:`_expression.FromClause.join`
+ will attempt to
join the two tables based on a foreign key relationship.
:param isouter: if True, render a LEFT OUTER JOIN, instead of JOIN.
@@ -412,16 +429,17 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable):
.. seealso::
- :func:`.join` - standalone function
+ :func:`_expression.join` - standalone function
- :class:`.Join` - the type of object produced
+ :class:`_expression.Join` - the type of object produced
"""
return Join(self, right, onclause, isouter, full)
def outerjoin(self, right, onclause=None, full=False):
- """Return a :class:`.Join` from this :class:`.FromClause`
+ """Return a :class:`_expression.Join` from this
+ :class:`_expression.FromClause`
to another :class:`FromClause`, with the "isouter" flag set to
True.
@@ -440,12 +458,14 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable):
isouter=True)
:param right: the right side of the join; this is any
- :class:`.FromClause` object such as a :class:`.Table` object, and
+ :class:`_expression.FromClause` object such as a
+ :class:`_schema.Table` object, and
may also be a selectable-compatible object such as an ORM-mapped
class.
:param onclause: a SQL expression representing the ON clause of the
- join. If left at ``None``, :meth:`.FromClause.join` will attempt to
+ join. If left at ``None``, :meth:`_expression.FromClause.join`
+ will attempt to
join the two tables based on a foreign key relationship.
:param full: if True, render a FULL OUTER JOIN, instead of
@@ -455,45 +475,47 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable):
.. seealso::
- :meth:`.FromClause.join`
+ :meth:`_expression.FromClause.join`
- :class:`.Join`
+ :class:`_expression.Join`
"""
return Join(self, right, onclause, True, full)
def alias(self, name=None, flat=False):
- """return an alias of this :class:`.FromClause`.
+ """return an alias of this :class:`_expression.FromClause`.
E.g.::
a2 = some_table.alias('a2')
- The above code creates an :class:`.Alias` object which can be used
+ The above code creates an :class:`_expression.Alias`
+ object which can be used
as a FROM clause in any SELECT statement.
.. seealso::
:ref:`core_tutorial_aliases`
- :func:`~.expression.alias`
+ :func:`_expression.alias`
"""
return Alias._construct(self, name)
def tablesample(self, sampling, name=None, seed=None):
- """Return a TABLESAMPLE alias of this :class:`.FromClause`.
+ """Return a TABLESAMPLE alias of this :class:`_expression.FromClause`.
- The return value is the :class:`.TableSample` construct also
- provided by the top-level :func:`~.expression.tablesample` function.
+ The return value is the :class:`_expression.TableSample`
+ construct also
+ provided by the top-level :func:`_expression.tablesample` function.
.. versionadded:: 1.1
.. seealso::
- :func:`~.expression.tablesample` - usage guidelines and parameters
+ :func:`_expression.tablesample` - usage guidelines and parameters
"""
return TableSample._construct(self, sampling, name, seed)
@@ -536,19 +558,21 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable):
@property
def exported_columns(self):
- """A :class:`.ColumnCollection` that represents the "exported"
- columns of this :class:`.Selectable`.
+ """A :class:`_expression.ColumnCollection`
+ that represents the "exported"
+ columns of this :class:`expression.Selectable`.
- The "exported" columns for a :class:`.FromClause` object are synonymous
- with the :attr:`.FromClause.columns` collection.
+ The "exported" columns for a :class:`_expression.FromClause`
+ object are synonymous
+ with the :attr:`_expression.FromClause.columns` collection.
.. versionadded:: 1.4
.. seealso:
- :attr:`.Selectable.exported_columns`
+ :attr:`expression.Selectable.exported_columns`
- :attr:`.SelectBase.exported_columns`
+ :attr:`_expression.SelectBase.exported_columns`
"""
@@ -556,8 +580,9 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable):
@util.memoized_property
def columns(self):
- """A named-based collection of :class:`.ColumnElement` objects
- maintained by this :class:`.FromClause`.
+ """A named-based collection of :class:`_expression.ColumnElement`
+ objects
+ maintained by this :class:`_expression.FromClause`.
The :attr:`.columns`, or :attr:`.c` collection, is the gateway
to the construction of SQL expressions using table-bound or
@@ -663,18 +688,22 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable):
class Join(FromClause):
- """represent a ``JOIN`` construct between two :class:`.FromClause`
+ """represent a ``JOIN`` construct between two
+ :class:`_expression.FromClause`
elements.
- The public constructor function for :class:`.Join` is the module-level
- :func:`.join()` function, as well as the :meth:`.FromClause.join` method
- of any :class:`.FromClause` (e.g. such as :class:`.Table`).
+ The public constructor function for :class:`_expression.Join`
+ is the module-level
+ :func:`_expression.join()` function, as well as the
+ :meth:`_expression.FromClause.join` method
+ of any :class:`_expression.FromClause` (e.g. such as
+ :class:`_schema.Table`).
.. seealso::
- :func:`.join`
+ :func:`_expression.join`
- :meth:`.FromClause.join`
+ :meth:`_expression.FromClause.join`
"""
@@ -691,11 +720,11 @@ class Join(FromClause):
_is_join = True
def __init__(self, left, right, onclause=None, isouter=False, full=False):
- """Construct a new :class:`.Join`.
+ """Construct a new :class:`_expression.Join`.
- The usual entrypoint here is the :func:`~.expression.join`
- function or the :meth:`.FromClause.join` method of any
- :class:`.FromClause` object.
+ The usual entrypoint here is the :func:`_expression.join`
+ function or the :meth:`_expression.FromClause.join` method of any
+ :class:`_expression.FromClause` object.
"""
self.left = coercions.expect(roles.FromClauseRole, left)
@@ -713,11 +742,11 @@ class Join(FromClause):
def _create_outerjoin(cls, left, right, onclause=None, full=False):
"""Return an ``OUTER JOIN`` clause element.
- The returned object is an instance of :class:`.Join`.
+ The returned object is an instance of :class:`_expression.Join`.
Similar functionality is also available via the
- :meth:`~.FromClause.outerjoin()` method on any
- :class:`.FromClause`.
+ :meth:`_expression.FromClause.outerjoin()` method on any
+ :class:`_expression.FromClause`.
:param left: The left side of the join.
@@ -727,9 +756,10 @@ class Join(FromClause):
derived from foreign key relationships established between
left and right otherwise.
- To chain joins together, use the :meth:`.FromClause.join` or
- :meth:`.FromClause.outerjoin` methods on the resulting
- :class:`.Join` object.
+ To chain joins together, use the :meth:`_expression.FromClause.join`
+ or
+ :meth:`_expression.FromClause.outerjoin` methods on the resulting
+ :class:`_expression.Join` object.
"""
return cls(left, right, onclause, isouter=True, full=full)
@@ -738,7 +768,8 @@ class Join(FromClause):
def _create_join(
cls, left, right, onclause=None, isouter=False, full=False
):
- """Produce a :class:`.Join` object, given two :class:`.FromClause`
+ """Produce a :class:`_expression.Join` object, given two
+ :class:`_expression.FromClause`
expressions.
E.g.::
@@ -753,18 +784,21 @@ class Join(FromClause):
JOIN address ON user.id = address.user_id
Similar functionality is available given any
- :class:`.FromClause` object (e.g. such as a :class:`.Table`) using
- the :meth:`.FromClause.join` method.
+ :class:`_expression.FromClause` object (e.g. such as a
+ :class:`_schema.Table`) using
+ the :meth:`_expression.FromClause.join` method.
:param left: The left side of the join.
:param right: the right side of the join; this is any
- :class:`.FromClause` object such as a :class:`.Table` object, and
+ :class:`_expression.FromClause` object such as a
+ :class:`_schema.Table` object, and
may also be a selectable-compatible object such as an ORM-mapped
class.
:param onclause: a SQL expression representing the ON clause of the
- join. If left at ``None``, :meth:`.FromClause.join` will attempt to
+ join. If left at ``None``, :meth:`_expression.FromClause.join`
+ will attempt to
join the two tables based on a foreign key relationship.
:param isouter: if True, render a LEFT OUTER JOIN, instead of JOIN.
@@ -775,9 +809,10 @@ class Join(FromClause):
.. seealso::
- :meth:`.FromClause.join` - method form, based on a given left side
+ :meth:`_expression.FromClause.join` - method form,
+ based on a given left side
- :class:`.Join` - the type of object produced
+ :class:`_expression.Join` - the type of object produced
"""
@@ -989,9 +1024,11 @@ class Join(FromClause):
)
def select(self, whereclause=None, **kwargs):
- r"""Create a :class:`.Select` from this :class:`.Join`.
+ r"""Create a :class:`_expression.Select` from this
+ :class:`_expression.Join`.
- The equivalent long-hand form, given a :class:`.Join` object
+ The equivalent long-hand form, given a :class:`_expression.Join`
+ object
``j``, is::
from sqlalchemy import select
@@ -1020,11 +1057,11 @@ class Join(FromClause):
@util.preload_module("sqlalchemy.sql.util")
def alias(self, name=None, flat=False):
- r"""return an alias of this :class:`.Join`.
+ r"""return an alias of this :class:`_expression.Join`.
The default behavior here is to first produce a SELECT
- construct from this :class:`.Join`, then to produce an
- :class:`.Alias` from that. So given a join of the form::
+ construct from this :class:`_expression.Join`, then to produce an
+ :class:`_expression.Alias` from that. So given a join of the form::
j = table_a.join(table_b, table_a.c.id == table_b.c.a_id)
@@ -1040,7 +1077,8 @@ class Join(FromClause):
FROM table_a
JOIN table_b ON table_a.id = table_b.a_id) AS anon_1
- The equivalent long-hand form, given a :class:`.Join` object
+ The equivalent long-hand form, given a :class:`_expression.Join`
+ object
``j``, is::
from sqlalchemy import select, alias
@@ -1052,20 +1090,22 @@ class Join(FromClause):
name=name
)
- The selectable produced by :meth:`.Join.alias` features the same
+ The selectable produced by :meth:`_expression.Join.alias`
+ features the same
columns as that of the two individual selectables presented under
a single name - the individual columns are "auto-labeled", meaning
- the ``.c.`` collection of the resulting :class:`.Alias` represents
+ the ``.c.`` collection of the resulting :class:`_expression.Alias`
+ represents
the names of the individual columns using a
``<tablename>_<columname>`` scheme::
j.c.table_a_id
j.c.table_b_a_id
- :meth:`.Join.alias` also features an alternate
+ :meth:`_expression.Join.alias` also features an alternate
option for aliasing joins which produces no enclosing SELECT and
does not normally apply labels to the column names. The
- ``flat=True`` option will call :meth:`.FromClause.alias`
+ ``flat=True`` option will call :meth:`_expression.FromClause.alias`
against the left and right sides individually.
Using this option, no new ``SELECT`` is produced;
we instead, from a construct as below::
@@ -1094,15 +1134,16 @@ class Join(FromClause):
ON table_b_1.id = table_c_1.b_id
) ON table_a_1.id = table_b_1.a_id
- The standalone :func:`~.expression.alias` function as well as the
- base :meth:`.FromClause.alias` method also support the ``flat=True``
+ The standalone :func:`_expression.alias` function as well as the
+ base :meth:`_expression.FromClause.alias`
+ method also support the ``flat=True``
argument as a no-op, so that the argument can be passed to the
``alias()`` method of any selectable.
:param name: name given to the alias.
:param flat: if True, produce an alias of the left and right
- sides of this :class:`.Join` and return the join of those
+ sides of this :class:`_expression.Join` and return the join of those
two selectables. This produces join expression that does not
include an enclosing SELECT.
@@ -1110,7 +1151,7 @@ class Join(FromClause):
:ref:`core_tutorial_aliases`
- :func:`~.expression.alias`
+ :func:`_expression.alias`
"""
sqlutil = util.preloaded.sql_util
@@ -1260,13 +1301,14 @@ class Alias(AliasedReturnsRows):
sub-select within a SQL statement using the ``AS`` keyword (or
without the keyword on certain databases such as Oracle).
- This object is constructed from the :func:`~.expression.alias` module
- level function as well as the :meth:`.FromClause.alias` method available
- on all :class:`.FromClause` subclasses.
+ This object is constructed from the :func:`_expression.alias` module
+ level function as well as the :meth:`_expression.FromClause.alias`
+ method available
+ on all :class:`_expression.FromClause` subclasses.
.. seealso::
- :meth:`.FromClause.alias`
+ :meth:`_expression.FromClause.alias`
"""
@@ -1274,24 +1316,28 @@ class Alias(AliasedReturnsRows):
@classmethod
def _factory(cls, selectable, name=None, flat=False):
- """Return an :class:`.Alias` object.
+ """Return an :class:`_expression.Alias` object.
- An :class:`.Alias` represents any :class:`.FromClause`
+ An :class:`_expression.Alias` represents any
+ :class:`_expression.FromClause`
with an alternate name assigned within SQL, typically using the ``AS``
clause when generated, e.g. ``SELECT * FROM table AS aliasname``.
- Similar functionality is available via the :meth:`~.FromClause.alias`
- method available on all :class:`.FromClause` subclasses. In terms of
- a SELECT object as generated from the :func:`~.sql.expression.select`
- function, the :meth:`.SelectBase.alias` method returns an
- :class:`.Alias` or similar object which represents a named,
+ Similar functionality is available via the
+ :meth:`_expression.FromClause.alias`
+ method available on all :class:`_expression.FromClause` subclasses.
+ In terms of
+ a SELECT object as generated from the :func:`_expression.select`
+ function, the :meth:`_expression.SelectBase.alias` method returns an
+ :class:`_expression.Alias` or similar object which represents a named,
parenthesized subquery.
- When an :class:`.Alias` is created from a :class:`.Table` object,
+ When an :class:`_expression.Alias` is created from a
+ :class:`_schema.Table` object,
this has the effect of the table being rendered
as ``tablename AS aliasname`` in a SELECT statement.
- For :func:`~.sql.expression.select` objects, the effect is that of
+ For :func:`_expression.select` objects, the effect is that of
creating a named subquery, i.e. ``(select ...) AS aliasname``.
The ``name`` parameter is optional, and provides the name
@@ -1302,7 +1348,7 @@ class Alias(AliasedReturnsRows):
same name for each successive compilation of the same statement
object.
- :param selectable: any :class:`.FromClause` subclass,
+ :param selectable: any :class:`_expression.FromClause` subclass,
such as a table, select statement, etc.
:param name: string name to be assigned as the alias.
@@ -1310,7 +1356,8 @@ class Alias(AliasedReturnsRows):
at compile time.
:param flat: Will be passed through to if the given selectable
- is an instance of :class:`.Join` - see :meth:`.Join.alias`
+ is an instance of :class:`_expression.Join` - see
+ :meth:`_expression.Join.alias`
for details.
"""
@@ -1322,9 +1369,10 @@ class Alias(AliasedReturnsRows):
class Lateral(AliasedReturnsRows):
"""Represent a LATERAL subquery.
- This object is constructed from the :func:`~.expression.lateral` module
- level function as well as the :meth:`.FromClause.lateral` method available
- on all :class:`.FromClause` subclasses.
+ This object is constructed from the :func:`_expression.lateral` module
+ level function as well as the :meth:`_expression.FromClause.lateral`
+ method available
+ on all :class:`_expression.FromClause` subclasses.
While LATERAL is part of the SQL standard, currently only more recent
PostgreSQL versions provide support for this keyword.
@@ -1342,9 +1390,10 @@ class Lateral(AliasedReturnsRows):
@classmethod
def _factory(cls, selectable, name=None):
- """Return a :class:`.Lateral` object.
+ """Return a :class:`_expression.Lateral` object.
- :class:`.Lateral` is an :class:`.Alias` subclass that represents
+ :class:`_expression.Lateral` is an :class:`_expression.Alias`
+ subclass that represents
a subquery with the LATERAL keyword applied to it.
The special behavior of a LATERAL subquery is that it appears in the
@@ -1368,15 +1417,16 @@ class Lateral(AliasedReturnsRows):
class TableSample(AliasedReturnsRows):
"""Represent a TABLESAMPLE clause.
- This object is constructed from the :func:`~.expression.tablesample` module
- level function as well as the :meth:`.FromClause.tablesample` method
- available on all :class:`.FromClause` subclasses.
+ This object is constructed from the :func:`_expression.tablesample` module
+ level function as well as the :meth:`_expression.FromClause.tablesample`
+ method
+ available on all :class:`_expression.FromClause` subclasses.
.. versionadded:: 1.1
.. seealso::
- :func:`~.expression.tablesample`
+ :func:`_expression.tablesample`
"""
@@ -1389,13 +1439,15 @@ class TableSample(AliasedReturnsRows):
@classmethod
def _factory(cls, selectable, sampling, name=None, seed=None):
- """Return a :class:`.TableSample` object.
+ """Return a :class:`_expression.TableSample` object.
- :class:`.TableSample` is an :class:`.Alias` subclass that represents
+ :class:`_expression.TableSample` is an :class:`_expression.Alias`
+ subclass that represents
a table with the TABLESAMPLE clause applied to it.
- :func:`~.expression.tablesample`
- is also available from the :class:`.FromClause` class via the
- :meth:`.FromClause.tablesample` method.
+ :func:`_expression.tablesample`
+ is also available from the :class:`_expression.FromClause`
+ class via the
+ :meth:`_expression.FromClause.tablesample` method.
The TABLESAMPLE clause allows selecting a randomly selected approximate
percentage of rows from a table. It supports multiple sampling methods,
@@ -1421,7 +1473,7 @@ class TableSample(AliasedReturnsRows):
.. versionadded:: 1.1
:param sampling: a ``float`` percentage between 0 and 100 or
- :class:`.functions.Function`.
+ :class:`_functions.Function`.
:param name: optional alias name
@@ -1450,8 +1502,8 @@ class TableSample(AliasedReturnsRows):
class CTE(Generative, HasPrefixes, HasSuffixes, AliasedReturnsRows):
"""Represent a Common Table Expression.
- The :class:`.CTE` object is obtained using the
- :meth:`.SelectBase.cte` method from any selectable.
+ The :class:`_expression.CTE` object is obtained using the
+ :meth:`_expression.SelectBase.cte` method from any selectable.
See that method for complete examples.
"""
@@ -1471,9 +1523,10 @@ class CTE(Generative, HasPrefixes, HasSuffixes, AliasedReturnsRows):
@classmethod
def _factory(cls, selectable, name=None, recursive=False):
- r"""Return a new :class:`.CTE`, or Common Table Expression instance.
+ r"""Return a new :class:`_expression.CTE`,
+ or Common Table Expression instance.
- Please see :meth:`.HasCte.cte` for detail on CTE usage.
+ Please see :meth:`_expression.HasCTE.cte` for detail on CTE usage.
"""
return coercions.expect(roles.HasCTERole, selectable).cte(
@@ -1500,16 +1553,17 @@ class CTE(Generative, HasPrefixes, HasSuffixes, AliasedReturnsRows):
super(CTE, self)._init(selectable, name=name)
def alias(self, name=None, flat=False):
- """Return an :class:`.Alias` of this :class:`.CTE`.
+ """Return an :class:`_expression.Alias` of this
+ :class:`_expression.CTE`.
This method is a CTE-specific specialization of the
- :class:`.FromClause.alias` method.
+ :class:`_expression.FromClause.alias` method.
.. seealso::
:ref:`core_tutorial_aliases`
- :func:`~.expression.alias`
+ :func:`_expression.alias`
"""
return CTE._construct(
@@ -1550,7 +1604,8 @@ class HasCTE(roles.HasCTERole):
"""
def cte(self, name=None, recursive=False):
- r"""Return a new :class:`.CTE`, or Common Table Expression instance.
+ r"""Return a new :class:`_expression.CTE`,
+ or Common Table Expression instance.
Common table expressions are a SQL standard whereby SELECT
statements can draw upon secondary statements specified along
@@ -1567,13 +1622,14 @@ class HasCTE(roles.HasCTERole):
.. versionchanged:: 1.1 Added support for UPDATE/INSERT/DELETE as
CTE, CTEs added to UPDATE/INSERT/DELETE.
- SQLAlchemy detects :class:`.CTE` objects, which are treated
- similarly to :class:`.Alias` objects, as special elements
+ SQLAlchemy detects :class:`_expression.CTE` objects, which are treated
+ similarly to :class:`_expression.Alias` objects, as special elements
to be delivered to the FROM clause of the statement as well
as to a WITH clause at the top of the statement.
For special prefixes such as PostgreSQL "MATERIALIZED" and
- "NOT MATERIALIZED", the :meth:`.CTE.prefix_with` method may be
+ "NOT MATERIALIZED", the :meth:`_expression.CTE.prefix_with`
+ method may be
used to establish these.
.. versionchanged:: 1.3.13 Added support for prefixes.
@@ -1711,7 +1767,7 @@ class HasCTE(roles.HasCTERole):
.. seealso::
:meth:`.orm.query.Query.cte` - ORM version of
- :meth:`.HasCTE.cte`.
+ :meth:`_expression.HasCTE.cte`.
"""
return CTE._construct(self, name=name, recursive=recursive)
@@ -1721,18 +1777,24 @@ class Subquery(AliasedReturnsRows):
"""Represent a subquery of a SELECT.
A :class:`.Subquery` is created by invoking the
- :meth:`.SelectBase.subquery` method, or for convenience the
- :class:`.SelectBase.alias` method, on any :class:`.SelectBase` subclass
- which includes :class:`.Select`, :class:`.CompoundSelect`, and
- :class:`.TextualSelect`. As rendered in a FROM clause, it represents the
+ :meth:`_expression.SelectBase.subquery` method, or for convenience the
+ :class:`_expression.SelectBase.alias` method, on any
+ :class:`_expression.SelectBase` subclass
+ which includes :class:`_expression.Select`,
+ :class:`_expression.CompoundSelect`, and
+ :class:`_expression.TextualSelect`. As rendered in a FROM clause,
+ it represents the
body of the SELECT statement inside of parenthesis, followed by the usual
"AS <somename>" that defines all "alias" objects.
- The :class:`.Subquery` object is very similar to the :class:`.Alias`
+ The :class:`.Subquery` object is very similar to the
+ :class:`_expression.Alias`
object and can be used in an equivalent way. The difference between
- :class:`.Alias` and :class:`.Subquery` is that :class:`.Alias` always
- contains a :class:`.FromClause` object whereas :class:`.Subquery`
- always contains a :class:`.SelectBase` object.
+ :class:`_expression.Alias` and :class:`.Subquery` is that
+ :class:`_expression.Alias` always
+ contains a :class:`_expression.FromClause` object whereas
+ :class:`.Subquery`
+ always contains a :class:`_expression.SelectBase` object.
.. versionadded:: 1.4 The :class:`.Subquery` class was added which now
serves the purpose of providing an aliased version of a SELECT
@@ -1758,10 +1820,10 @@ class Subquery(AliasedReturnsRows):
"The :meth:`.Subquery.as_scalar` method, which was previously "
"``Alias.as_scalar()`` prior to version 1.4, is deprecated and "
"will be removed in a future release; Please use the "
- ":meth:`.Select.scalar_subquery` method of the "
- ":func:`~.sql.expression.select` "
+ ":meth:`_expression.Select.scalar_subquery` method of the "
+ ":func:`_expression.select` "
"construct before constructing a subquery object, or with the ORM "
- "use the :meth:`.Query.scalar_subquery` method.",
+ "use the :meth:`_query.Query.scalar_subquery` method.",
)
def as_scalar(self):
return self.element._set_label_style(
@@ -1818,7 +1880,7 @@ class TableClause(Immutable, FromClause):
This is a lightweight table object that has only a name and a
collection of columns, which are typically produced
- by the :func:`.expression.column` function::
+ by the :func:`_expression.column` function::
from sqlalchemy import table, column
@@ -1828,16 +1890,17 @@ class TableClause(Immutable, FromClause):
column("description"),
)
- The :class:`.TableClause` construct serves as the base for
- the more commonly used :class:`~.schema.Table` object, providing
- the usual set of :class:`~.expression.FromClause` services including
+ The :class:`_expression.TableClause` construct serves as the base for
+ the more commonly used :class:`_schema.Table` object, providing
+ the usual set of :class:`_expression.FromClause` services including
the ``.c.`` collection and statement generation methods.
It does **not** provide all the additional schema-level services
- of :class:`~.schema.Table`, including constraints, references to other
- tables, or support for :class:`.MetaData`-level services. It's useful
+ of :class:`_schema.Table`, including constraints, references to other
+ tables, or support for :class:`_schema.MetaData`-level services.
+ It's useful
on its own as an ad-hoc construct used to generate quick SQL
- statements when a more fully fledged :class:`~.schema.Table`
+ statements when a more fully fledged :class:`_schema.Table`
is not on hand.
"""
@@ -1855,27 +1918,29 @@ class TableClause(Immutable, FromClause):
named_with_column = True
implicit_returning = False
- """:class:`.TableClause` doesn't support having a primary key or column
+ """:class:`_expression.TableClause`
+ doesn't support having a primary key or column
-level defaults, so implicit returning doesn't apply."""
_autoincrement_column = None
"""No PK or default support so no autoincrement column."""
def __init__(self, name, *columns):
- """Produce a new :class:`.TableClause`.
+ """Produce a new :class:`_expression.TableClause`.
- The object returned is an instance of :class:`.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.
+ :class:`_schema.Table` object.
It may be used to construct lightweight table constructs.
- .. versionchanged:: 1.0.0 :func:`.expression.table` can now
+ .. versionchanged:: 1.0.0 :func:`_expression.table` can now
be imported from the plain ``sqlalchemy`` namespace like any
other SQL element.
:param name: Name of the table.
- :param columns: A collection of :func:`.expression.column` constructs.
+ :param columns: A collection of :func:`_expression.column` constructs.
"""
@@ -1906,14 +1971,14 @@ class TableClause(Immutable, FromClause):
@util.preload_module("sqlalchemy.sql.dml")
def insert(self, values=None, inline=False, **kwargs):
- """Generate an :func:`~.sql.expression.insert` construct against this
- :class:`.TableClause`.
+ """Generate an :func:`_expression.insert` construct against this
+ :class:`_expression.TableClause`.
E.g.::
table.insert().values(name='foo')
- See :func:`~.sql.expression.insert` for argument and usage information.
+ See :func:`_expression.insert` for argument and usage information.
"""
return util.preloaded.sql_dml.Insert(
@@ -1922,14 +1987,14 @@ class TableClause(Immutable, FromClause):
@util.preload_module("sqlalchemy.sql.dml")
def update(self, whereclause=None, values=None, inline=False, **kwargs):
- """Generate an :func:`.update` construct against this
- :class:`.TableClause`.
+ """Generate an :func:`_expression.update` construct against this
+ :class:`_expression.TableClause`.
E.g.::
table.update().where(table.c.id==7).values(name='foo')
- See :func:`.update` for argument and usage information.
+ See :func:`_expression.update` for argument and usage information.
"""
return util.preloaded.sql_dml.Update(
@@ -1942,14 +2007,14 @@ class TableClause(Immutable, FromClause):
@util.preload_module("sqlalchemy.sql.dml")
def delete(self, whereclause=None, **kwargs):
- """Generate a :func:`.delete` construct against this
- :class:`.TableClause`.
+ """Generate a :func:`_expression.delete` construct against this
+ :class:`_expression.TableClause`.
E.g.::
table.delete().where(table.c.id==7)
- See :func:`.delete` for argument and usage information.
+ See :func:`_expression.delete` for argument and usage information.
"""
return util.preloaded.sql_dml.Delete(self, whereclause, **kwargs)
@@ -1991,7 +2056,8 @@ class ForUpdateArg(ClauseElement):
skip_locked=False,
key_share=False,
):
- """Represents arguments specified to :meth:`.Select.for_update`.
+ """Represents arguments specified to
+ :meth:`_expression.Select.for_update`.
"""
@@ -2012,8 +2078,8 @@ class Values(Generative, FromClause):
"""represent a ``VALUES`` construct that can be used as a FROM element
in a statement.
- The :class:`.Values` object is created from the
- :func:`~.sql.expression.values` function.
+ The :class:`_expression.Values` object is created from the
+ :func:`_expression.values` function.
.. versionadded:: 1.4
@@ -2032,13 +2098,15 @@ class Values(Generative, FromClause):
]
def __init__(self, *columns, **kw):
- r"""Construct a :class:`.Values` construct.
+ r"""Construct a :class:`_expression.Values` construct.
The column expressions and the actual data for
- :class:`.Values` are given in two separate steps. The
+ :class:`_expression.Values` are given in two separate steps. The
constructor receives the column expressions typically as
- :func:`.column` constructs, and the data is then passed via the
- :meth:`.Values.data` method as a list, which can be called multiple
+ :func:`_expression.column` constructs,
+ and the data is then passed via the
+ :meth:`_expression.Values.data` method as a list,
+ which can be called multiple
times to add more data, e.g.::
from sqlalchemy import column
@@ -2053,7 +2121,7 @@ class Values(Generative, FromClause):
)
:param \*columns: column expressions, typically composed using
- :func:`.column` objects.
+ :func:`_expression.column` objects.
:param name: the name for this VALUES construct. If omitted, the
VALUES construct will be unnamed in a SQL expression. Different
@@ -2073,17 +2141,18 @@ class Values(Generative, FromClause):
@_generative
def alias(self, name, **kw):
- """Return a new :class:`.Values` construct that is a copy of this
+ """Return a new :class:`_expression.Values`
+ construct that is a copy of this
one with the given name.
This method is a VALUES-specific specialization of the
- :class:`.FromClause.alias` method.
+ :class:`_expression.FromClause.alias` method.
.. seealso::
:ref:`core_tutorial_aliases`
- :func:`~.expression.alias`
+ :func:`_expression.alias`
"""
self.name = name
@@ -2091,12 +2160,13 @@ class Values(Generative, FromClause):
@_generative
def lateral(self, name=None):
- """Return a new :class:`.Values` with the lateral flag set, so that
+ """Return a new :class:`_expression.Values` with the lateral flag set,
+ so that
it renders as LATERAL.
.. seealso::
- :func:`~.expression.lateral`
+ :func:`_expression.lateral`
"""
self._is_lateral = True
@@ -2105,7 +2175,8 @@ class Values(Generative, FromClause):
@_generative
def data(self, values):
- """Return a new :class:`.Values` construct, adding the given data
+ """Return a new :class:`_expression.Values` construct,
+ adding the given data
to the data list.
E.g.::
@@ -2113,7 +2184,8 @@ class Values(Generative, FromClause):
my_values = my_values.data([(1, 'value 1'), (2, 'value2')])
:param values: a sequence (i.e. list) of tuples that map to the
- column expressions given in the :class:`.Values` constructor.
+ column expressions given in the :class:`_expression.Values`
+ constructor.
"""
@@ -2142,8 +2214,9 @@ class SelectBase(
"""Base class for SELECT statements.
- This includes :class:`.Select`, :class:`.CompoundSelect` and
- :class:`.TextualSelect`.
+ This includes :class:`_expression.Select`,
+ :class:`_expression.CompoundSelect` and
+ :class:`_expression.TextualSelect`.
"""
@@ -2159,11 +2232,14 @@ class SelectBase(
@property
def selected_columns(self):
- """A :class:`.ColumnCollection` representing the columns that
+ """A :class:`_expression.ColumnCollection`
+ representing the columns that
this SELECT statement or similar construct returns in its result set.
- This collection differs from the :attr:`.FromClause.columns` collection
- of a :class:`.FromClause` in that the columns within this collection
+ This collection differs from the
+ :attr:`_expression.FromClause.columns` collection
+ of a :class:`_expression.FromClause`
+ in that the columns within this collection
cannot be directly nested inside another SELECT statement; a subquery
must be applied first which provides for the necessary parenthesization
required by SQL.
@@ -2175,19 +2251,21 @@ class SelectBase(
@property
def exported_columns(self):
- """A :class:`.ColumnCollection` that represents the "exported"
- columns of this :class:`.Selectable`.
+ """A :class:`_expression.ColumnCollection`
+ that represents the "exported"
+ columns of this :class:`expression.Selectable`.
- The "exported" columns for a :class:`.SelectBase` object are synonymous
- with the :attr:`.SelectBase.selected_columns` collection.
+ The "exported" columns for a :class:`_expression.SelectBase`
+ object are synonymous
+ with the :attr:`_expression.SelectBase.selected_columns` collection.
.. versionadded:: 1.4
.. seealso:
- :attr:`.Selectable.exported_columns`
+ :attr:`expression.Selectable.exported_columns`
- :attr:`.FromClause.exported_columns`
+ :attr:`_expression.FromClause.exported_columns`
"""
@@ -2196,13 +2274,16 @@ class SelectBase(
@property
@util.deprecated(
"1.4",
- "The :attr:`.SelectBase.c` and :attr:`.SelectBase.columns` attributes "
+ "The :attr:`_expression.SelectBase.c` and "
+ ":attr:`_expression.SelectBase.columns` attributes "
"are deprecated and will be removed in a future release; these "
"attributes implicitly create a subquery that should be explicit. "
- "Please call :meth:`.SelectBase.subquery` first in order to create "
+ "Please call :meth:`_expression.SelectBase.subquery` "
+ "first in order to create "
"a subquery, which then contains this attribute. To access the "
"columns that this SELECT object SELECTs "
- "from, use the :attr:`.SelectBase.selected_columns` attribute.",
+ "from, use the :attr:`_expression.SelectBase.selected_columns` "
+ "attribute.",
)
def c(self):
return self._implicit_subquery.columns
@@ -2213,10 +2294,11 @@ class SelectBase(
@util.deprecated(
"1.4",
- "The :meth:`.SelectBase.select` method is deprecated "
+ "The :meth:`_expression.SelectBase.select` method is deprecated "
"and will be removed in a future release; this method implicitly "
"creates a subquery that should be explicit. "
- "Please call :meth:`.SelectBase.subquery` first in order to create "
+ "Please call :meth:`_expression.SelectBase.subquery` "
+ "first in order to create "
"a subquery, which then can be seleted.",
)
def select(self, *arg, **kw):
@@ -2224,10 +2306,11 @@ class SelectBase(
@util.deprecated(
"1.4",
- "The :meth:`.SelectBase.join` method is deprecated "
+ "The :meth:`_expression.SelectBase.join` method is deprecated "
"and will be removed in a future release; this method implicitly "
"creates a subquery that should be explicit. "
- "Please call :meth:`.SelectBase.subquery` first in order to create "
+ "Please call :meth:`_expression.SelectBase.subquery` "
+ "first in order to create "
"a subquery, which then can be selected.",
)
def join(self, *arg, **kw):
@@ -2235,10 +2318,11 @@ class SelectBase(
@util.deprecated(
"1.4",
- "The :meth:`.SelectBase.outerjoin` method is deprecated "
+ "The :meth:`_expression.SelectBase.outerjoin` method is deprecated "
"and will be removed in a future release; this method implicitly "
"creates a subquery that should be explicit. "
- "Please call :meth:`.SelectBase.subquery` first in order to create "
+ "Please call :meth:`_expression.SelectBase.subquery` "
+ "first in order to create "
"a subquery, which then can be selected.",
)
def outerjoin(self, *arg, **kw):
@@ -2250,9 +2334,10 @@ class SelectBase(
@util.deprecated(
"1.4",
- "The :meth:`.SelectBase.as_scalar` method is deprecated and will be "
+ "The :meth:`_expression.SelectBase.as_scalar` "
+ "method is deprecated and will be "
"removed in a future release. Please refer to "
- ":meth:`.SelectBase.scalar_subquery`.",
+ ":meth:`_expression.SelectBase.scalar_subquery`.",
)
def as_scalar(self):
return self.scalar_subquery()
@@ -2267,11 +2352,12 @@ class SelectBase(
an enclosing SELECT.
Note that the scalar subquery differentiates from the FROM-level
- subquery that can be produced using the :meth:`.SelectBase.subquery`
+ subquery that can be produced using the
+ :meth:`_expression.SelectBase.subquery`
method.
.. versionchanged: 1.4 - the ``.as_scalar()`` method was renamed to
- :meth:`.SelectBase.scalar_subquery`.
+ :meth:`_expression.SelectBase.scalar_subquery`.
"""
if self._label_style is not LABEL_STYLE_NONE:
@@ -2285,16 +2371,16 @@ class SelectBase(
.. seealso::
- :meth:`~.SelectBase.as_scalar`.
+ :meth:`_expression.SelectBase.as_scalar`.
"""
return self.scalar_subquery().label(name)
def lateral(self, name=None):
- """Return a LATERAL alias of this :class:`.Selectable`.
+ """Return a LATERAL alias of this :class:`expression.Selectable`.
- The return value is the :class:`.Lateral` construct also
- provided by the top-level :func:`~.expression.lateral` function.
+ The return value is the :class:`_expression.Lateral` construct also
+ provided by the top-level :func:`_expression.lateral` function.
.. versionadded:: 1.1
@@ -2310,7 +2396,7 @@ class SelectBase(
return [self]
def subquery(self, name=None):
- """Return a subquery of this :class:`.SelectBase`.
+ """Return a subquery of this :class:`_expression.SelectBase`.
A subquery is from a SQL perspective a parentheized, named construct
that can be placed in the FROM clause of another SELECT statement.
@@ -2335,10 +2421,14 @@ class SelectBase(
SELECT anon_1.id, anon_1.name
FROM (SELECT table.id, table.name FROM table) AS anon_1
- Historically, :meth:`.SelectBase.subquery` is equivalent to calling
- the :meth:`.FromClause.alias` method on a FROM object; however,
- as a :class:`.SelectBase` object is not directly FROM object,
- the :meth:`.SelectBase.subquery` method provides clearer semantics.
+ Historically, :meth:`_expression.SelectBase.subquery`
+ is equivalent to calling
+ the :meth:`_expression.FromClause.alias`
+ method on a FROM object; however,
+ as a :class:`_expression.SelectBase`
+ object is not directly FROM object,
+ the :meth:`_expression.SelectBase.subquery`
+ method provides clearer semantics.
.. versionadded:: 1.4
@@ -2355,22 +2445,25 @@ class SelectBase(
raise NotImplementedError()
def alias(self, name=None, flat=False):
- """Return a named subquery against this :class:`.SelectBase`.
+ """Return a named subquery against this
+ :class:`_expression.SelectBase`.
- For a :class:`.SelectBase` (as opposed to a :class:`.FromClause`),
+ For a :class:`_expression.SelectBase` (as opposed to a
+ :class:`_expression.FromClause`),
this returns a :class:`.Subquery` object which behaves mostly the
- same as the :class:`.Alias` object that is used with a
- :class:`.FromClause`.
+ same as the :class:`_expression.Alias` object that is used with a
+ :class:`_expression.FromClause`.
- .. versionchanged:: 1.4 The :meth:`.SelectBase.alias` method is now
- a synonym for the :meth:`.SelectBase.subquery` method.
+ .. versionchanged:: 1.4 The :meth:`_expression.SelectBase.alias`
+ method is now
+ a synonym for the :meth:`_expression.SelectBase.subquery` method.
"""
return self.subquery(name=name)
class SelectStatementGrouping(GroupedElement, SelectBase):
- """Represent a grouping of a :class:`.SelectBase`.
+ """Represent a grouping of a :class:`_expression.SelectBase`.
This differs from :class:`.Subquery` in that we are still
an "inner" SELECT statement, this is strictly for grouping inside of
@@ -2417,7 +2510,8 @@ class SelectStatementGrouping(GroupedElement, SelectBase):
@property
def selected_columns(self):
- """A :class:`.ColumnCollection` representing the columns that
+ """A :class:`_expression.ColumnCollection`
+ representing the columns that
the embedded SELECT statement returns in its result set.
.. versionadded:: 1.4
@@ -2437,9 +2531,10 @@ class SelectStatementGrouping(GroupedElement, SelectBase):
class DeprecatedSelectBaseGenerations(object):
@util.deprecated(
"1.4",
- "The :meth:`.GenerativeSelect.append_order_by` method is deprecated "
+ "The :meth:`_expression.GenerativeSelect.append_order_by` "
+ "method is deprecated "
"and will be removed in a future release. Use the generative method "
- ":meth:`.GenerativeSelect.order_by`.",
+ ":meth:`_expression.GenerativeSelect.order_by`.",
)
def append_order_by(self, *clauses):
"""Append the given ORDER BY criterion applied to this selectable.
@@ -2447,21 +2542,23 @@ class DeprecatedSelectBaseGenerations(object):
The criterion will be appended to any pre-existing ORDER BY criterion.
This is an **in-place** mutation method; the
- :meth:`~.GenerativeSelect.order_by` method is preferred, as it
+ :meth:`_expression.GenerativeSelect.order_by` method is preferred,
+ as it
provides standard :term:`method chaining`.
.. seealso::
- :meth:`.GenerativeSelect.order_by`
+ :meth:`_expression.GenerativeSelect.order_by`
"""
self.order_by.non_generative(self, *clauses)
@util.deprecated(
"1.4",
- "The :meth:`.GenerativeSelect.append_group_by` method is deprecated "
+ "The :meth:`_expression.GenerativeSelect.append_group_by` "
+ "method is deprecated "
"and will be removed in a future release. Use the generative method "
- ":meth:`.GenerativeSelect.group_by`.",
+ ":meth:`_expression.GenerativeSelect.group_by`.",
)
def append_group_by(self, *clauses):
"""Append the given GROUP BY criterion applied to this selectable.
@@ -2469,12 +2566,13 @@ class DeprecatedSelectBaseGenerations(object):
The criterion will be appended to any pre-existing GROUP BY criterion.
This is an **in-place** mutation method; the
- :meth:`~.GenerativeSelect.group_by` method is preferred, as it
+ :meth:`_expression.GenerativeSelect.group_by` method is preferred,
+ as it
provides standard :term:`method chaining`.
.. seealso::
- :meth:`.GenerativeSelect.group_by`
+ :meth:`_expression.GenerativeSelect.group_by`
"""
self.group_by.non_generative(self, *clauses)
@@ -2489,10 +2587,13 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase):
"""Base class for SELECT statements where additional elements can be
added.
- This serves as the base for :class:`.Select` and :class:`.CompoundSelect`
+ This serves as the base for :class:`_expression.Select` and
+ :class:`_expression.CompoundSelect`
where elements such as ORDER BY, GROUP BY can be added and column
- rendering can be controlled. Compare to :class:`.TextualSelect`, which,
- while it subclasses :class:`.SelectBase` and is also a SELECT construct,
+ rendering can be controlled. Compare to
+ :class:`_expression.TextualSelect`, which,
+ while it subclasses :class:`_expression.SelectBase`
+ and is also a SELECT construct,
represents a fixed textual string which cannot be altered at this level,
only wrapped as a subquery.
@@ -2540,7 +2641,8 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase):
skip_locked=False,
key_share=False,
):
- """Specify a ``FOR UPDATE`` clause for this :class:`.GenerativeSelect`.
+ """Specify a ``FOR UPDATE`` clause for this
+ :class:`_expression.GenerativeSelect`.
E.g.::
@@ -2569,7 +2671,8 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase):
``nowait``, will render ``FOR SHARE NOWAIT``.
:param of: SQL expression or list of SQL expression elements
- (typically :class:`.Column` objects or a compatible expression) which
+ (typically :class:`_schema.Column`
+ objects or a compatible expression) which
will render into a ``FOR UPDATE OF`` clause; supported by PostgreSQL
and Oracle. May render as a table or as a column depending on
backend.
@@ -2708,7 +2811,7 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase):
support ``LIMIT`` will attempt to provide similar
functionality.
- .. versionchanged:: 1.0.0 - :meth:`.Select.limit` can now
+ .. versionchanged:: 1.0.0 - :meth:`_expression.Select.limit` can now
accept arbitrary SQL expressions as well as integer values.
:param limit: an integer LIMIT parameter, or a SQL expression
@@ -2730,7 +2833,7 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase):
functionality.
- .. versionchanged:: 1.0.0 - :meth:`.Select.offset` can now
+ .. versionchanged:: 1.0.0 - :meth:`_expression.Select.offset` can now
accept arbitrary SQL expressions as well as integer values.
:param offset: an integer OFFSET parameter, or a SQL expression
@@ -2749,7 +2852,8 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase):
stmt = select([table]).order_by(table.c.id, table.c.name)
- :param \*order_by: a series of :class:`.ColumnElement` constructs
+ :param \*order_by: a series of :class:`_expression.ColumnElement`
+ constructs
which will be used to generate an ORDER BY clause.
.. seealso::
@@ -2776,7 +2880,8 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase):
stmt = select([table.c.name, func.max(table.c.stat)]).\
group_by(table.c.name)
- :param \*group_by: a series of :class:`.ColumnElement` constructs
+ :param \*group_by: a series of :class:`_expression.ColumnElement`
+ constructs
which will be used to generate an GROUP BY clause.
.. seealso::
@@ -2810,17 +2915,17 @@ class CompoundSelect(HasCompileState, GenerativeSelect):
.. seealso::
- :func:`.union`
+ :func:`_expression.union`
- :func:`.union_all`
+ :func:`_expression.union_all`
- :func:`.intersect`
+ :func:`_expression.intersect`
- :func:`.intersect_all`
+ :func:`_expression.intersect_all`
- :func:`.except`
+ :func:`_expression.except`
- :func:`.except_all`
+ :func:`_expression.except_all`
"""
@@ -2863,13 +2968,13 @@ class CompoundSelect(HasCompileState, GenerativeSelect):
r"""Return a ``UNION`` of multiple selectables.
The returned object is an instance of
- :class:`.CompoundSelect`.
+ :class:`_expression.CompoundSelect`.
A similar :func:`union()` method is available on all
- :class:`.FromClause` subclasses.
+ :class:`_expression.FromClause` subclasses.
\*selects
- a list of :class:`.Select` instances.
+ a list of :class:`_expression.Select` instances.
\**kwargs
available keyword arguments are the same as those of
@@ -2883,13 +2988,13 @@ class CompoundSelect(HasCompileState, GenerativeSelect):
r"""Return a ``UNION ALL`` of multiple selectables.
The returned object is an instance of
- :class:`.CompoundSelect`.
+ :class:`_expression.CompoundSelect`.
A similar :func:`union_all()` method is available on all
- :class:`.FromClause` subclasses.
+ :class:`_expression.FromClause` subclasses.
\*selects
- a list of :class:`.Select` instances.
+ a list of :class:`_expression.Select` instances.
\**kwargs
available keyword arguments are the same as those of
@@ -2903,10 +3008,10 @@ class CompoundSelect(HasCompileState, GenerativeSelect):
r"""Return an ``EXCEPT`` of multiple selectables.
The returned object is an instance of
- :class:`.CompoundSelect`.
+ :class:`_expression.CompoundSelect`.
\*selects
- a list of :class:`.Select` instances.
+ a list of :class:`_expression.Select` instances.
\**kwargs
available keyword arguments are the same as those of
@@ -2920,10 +3025,10 @@ class CompoundSelect(HasCompileState, GenerativeSelect):
r"""Return an ``EXCEPT ALL`` of multiple selectables.
The returned object is an instance of
- :class:`.CompoundSelect`.
+ :class:`_expression.CompoundSelect`.
\*selects
- a list of :class:`.Select` instances.
+ a list of :class:`_expression.Select` instances.
\**kwargs
available keyword arguments are the same as those of
@@ -2937,10 +3042,10 @@ class CompoundSelect(HasCompileState, GenerativeSelect):
r"""Return an ``INTERSECT`` of multiple selectables.
The returned object is an instance of
- :class:`.CompoundSelect`.
+ :class:`_expression.CompoundSelect`.
\*selects
- a list of :class:`.Select` instances.
+ a list of :class:`_expression.Select` instances.
\**kwargs
available keyword arguments are the same as those of
@@ -2954,10 +3059,10 @@ class CompoundSelect(HasCompileState, GenerativeSelect):
r"""Return an ``INTERSECT ALL`` of multiple selectables.
The returned object is an instance of
- :class:`.CompoundSelect`.
+ :class:`_expression.CompoundSelect`.
\*selects
- a list of :class:`.Select` instances.
+ a list of :class:`_expression.Select` instances.
\**kwargs
available keyword arguments are the same as those of
@@ -3035,11 +3140,13 @@ class CompoundSelect(HasCompileState, GenerativeSelect):
@property
def selected_columns(self):
- """A :class:`.ColumnCollection` representing the columns that
+ """A :class:`_expression.ColumnCollection`
+ representing the columns that
this SELECT statement or similar construct returns in its result set.
- For a :class:`.CompoundSelect`, the
- :attr:`.CompoundSelect.selected_columns` attribute returns the selected
+ For a :class:`_expression.CompoundSelect`, the
+ :attr:`_expression.CompoundSelect.selected_columns`
+ attribute returns the selected
columns of the first SELECT statement contained within the series of
statements within the set operation.
@@ -3067,16 +3174,18 @@ class CompoundSelect(HasCompileState, GenerativeSelect):
class DeprecatedSelectGenerations(object):
@util.deprecated(
"1.4",
- "The :meth:`.Select.append_correlation` method is deprecated "
+ "The :meth:`_expression.Select.append_correlation` "
+ "method is deprecated "
"and will be removed in a future release. Use the generative "
- "method :meth:`.Select.correlate`.",
+ "method :meth:`_expression.Select.correlate`.",
)
def append_correlation(self, fromclause):
"""append the given correlation expression to this select()
construct.
This is an **in-place** mutation method; the
- :meth:`~.Select.correlate` method is preferred, as it provides
+ :meth:`_expression.Select.correlate` method is preferred,
+ as it provides
standard :term:`method chaining`.
"""
@@ -3085,9 +3194,9 @@ class DeprecatedSelectGenerations(object):
@util.deprecated(
"1.4",
- "The :meth:`.Select.append_column` method is deprecated "
+ "The :meth:`_expression.Select.append_column` method is deprecated "
"and will be removed in a future release. Use the generative "
- "method :meth:`.Select.column`.",
+ "method :meth:`_expression.Select.column`.",
)
def append_column(self, column):
"""append the given column expression to the columns clause of this
@@ -3098,28 +3207,30 @@ class DeprecatedSelectGenerations(object):
my_select.append_column(some_table.c.new_column)
This is an **in-place** mutation method; the
- :meth:`~.Select.column` method is preferred, as it provides standard
+ :meth:`_expression.Select.column` method is preferred,
+ as it provides standard
:term:`method chaining`.
- See the documentation for :meth:`.Select.with_only_columns`
+ See the documentation for :meth:`_expression.Select.with_only_columns`
for guidelines on adding /replacing the columns of a
- :class:`.Select` object.
+ :class:`_expression.Select` object.
"""
self.add_columns.non_generative(self, column)
@util.deprecated(
"1.4",
- "The :meth:`.Select.append_prefix` method is deprecated "
+ "The :meth:`_expression.Select.append_prefix` method is deprecated "
"and will be removed in a future release. Use the generative "
- "method :meth:`.Select.prefix_with`.",
+ "method :meth:`_expression.Select.prefix_with`.",
)
def append_prefix(self, clause):
"""append the given columns clause prefix expression to this select()
construct.
This is an **in-place** mutation method; the
- :meth:`~.Select.prefix_with` method is preferred, as it provides
+ :meth:`_expression.Select.prefix_with` method is preferred,
+ as it provides
standard :term:`method chaining`.
"""
@@ -3127,9 +3238,10 @@ class DeprecatedSelectGenerations(object):
@util.deprecated(
"1.4",
- "The :meth:`.Select.append_whereclause` method is deprecated "
+ "The :meth:`_expression.Select.append_whereclause` "
+ "method is deprecated "
"and will be removed in a future release. Use the generative "
- "method :meth:`.Select.where`.",
+ "method :meth:`_expression.Select.where`.",
)
def append_whereclause(self, whereclause):
"""append the given expression to this select() construct's WHERE
@@ -3138,7 +3250,8 @@ class DeprecatedSelectGenerations(object):
The expression will be joined to existing WHERE criterion via AND.
This is an **in-place** mutation method; the
- :meth:`~.Select.where` method is preferred, as it provides standard
+ :meth:`_expression.Select.where` method is preferred,
+ as it provides standard
:term:`method chaining`.
"""
@@ -3146,9 +3259,9 @@ class DeprecatedSelectGenerations(object):
@util.deprecated(
"1.4",
- "The :meth:`.Select.append_having` method is deprecated "
+ "The :meth:`_expression.Select.append_having` method is deprecated "
"and will be removed in a future release. Use the generative "
- "method :meth:`.Select.having`.",
+ "method :meth:`_expression.Select.having`.",
)
def append_having(self, having):
"""append the given expression to this select() construct's HAVING
@@ -3157,7 +3270,8 @@ class DeprecatedSelectGenerations(object):
The expression will be joined to existing HAVING criterion via AND.
This is an **in-place** mutation method; the
- :meth:`~.Select.having` method is preferred, as it provides standard
+ :meth:`_expression.Select.having` method is preferred,
+ as it provides standard
:term:`method chaining`.
"""
@@ -3166,16 +3280,17 @@ class DeprecatedSelectGenerations(object):
@util.deprecated(
"1.4",
- "The :meth:`.Select.append_from` method is deprecated "
+ "The :meth:`_expression.Select.append_from` method is deprecated "
"and will be removed in a future release. Use the generative "
- "method :meth:`.Select.select_from`.",
+ "method :meth:`_expression.Select.select_from`.",
)
def append_from(self, fromclause):
"""append the given FromClause expression to this select() construct's
FROM clause.
This is an **in-place** mutation method; the
- :meth:`~.Select.select_from` method is preferred, as it provides
+ :meth:`_expression.Select.select_from` method is preferred,
+ as it provides
standard :term:`method chaining`.
"""
@@ -3353,32 +3468,38 @@ class Select(
@classmethod
def _create_select(cls, *entities):
- r"""Construct a new :class:`.Select` using the 2.x style API.
+ r"""Construct a new :class:`_expression.Select` using the 2.
+ x style API.
.. versionadded:: 2.0 - the :func:`.future.select` construct is
the same construct as the one returned by
- :func:`.sql.expression.select`, except that the function only
+ :func:`_expression.select`, except that the function only
accepts the "columns clause" entities up front; the rest of the
state of the SELECT should be built up using generative methods.
Similar functionality is also available via the
- :meth:`.FromClause.select` method on any :class:`.FromClause`.
+ :meth:`_expression.FromClause.select` method on any
+ :class:`_expression.FromClause`.
.. seealso::
:ref:`coretutorial_selecting` - Core Tutorial description of
- :func:`~.sql.expression.select`.
+ :func:`_expression.select`.
:param \*entities:
Entities to SELECT from. For Core usage, this is typically a series
- of :class:`.ColumnElement` and / or :class:`.FromClause`
+ of :class:`_expression.ColumnElement` and / or
+ :class:`_expression.FromClause`
objects which will form the columns clause of the resulting
statement. For those objects that are instances of
- :class:`.FromClause` (typically :class:`.Table` or :class:`.Alias`
- objects), the :attr:`.FromClause.c` collection is extracted
- to form a collection of :class:`.ColumnElement` objects.
-
- This parameter will also accept :class:`.Text` constructs as
+ :class:`_expression.FromClause` (typically :class:`_schema.Table`
+ or :class:`_expression.Alias`
+ objects), the :attr:`_expression.FromClause.c`
+ collection is extracted
+ to form a collection of :class:`_expression.ColumnElement` objects.
+
+ This parameter will also accept :class:`_expression.TextClause`
+ constructs as
given, as well as ORM-mapped classes.
"""
@@ -3417,82 +3538,102 @@ class Select(
suffixes=None,
**kwargs
):
- """Construct a new :class:`.Select` using the 1.x style API.
+ """Construct a new :class:`_expression.Select` using the 1.x style API
+ .
Similar functionality is also available via the
- :meth:`.FromClause.select` method on any :class:`.FromClause`.
+ :meth:`_expression.FromClause.select` method on any
+ :class:`_expression.FromClause`.
- All arguments which accept :class:`.ClauseElement` arguments also
+ All arguments which accept :class:`_expression.ClauseElement`
+ arguments also
accept string arguments, which will be converted as appropriate into
- either :func:`.text()` or :func:`.literal_column()` constructs.
+ either :func:`_expression.text()` or
+ :func:`_expression.literal_column()` constructs.
.. seealso::
:ref:`coretutorial_selecting` - Core Tutorial description of
- :func:`~.sql.expression.select`.
+ :func:`_expression.select`.
:param columns:
- A list of :class:`.ColumnElement` or :class:`.FromClause`
+ A list of :class:`_expression.ColumnElement` or
+ :class:`_expression.FromClause`
objects which will form the columns clause of the resulting
statement. For those objects that are instances of
- :class:`.FromClause` (typically :class:`.Table` or :class:`.Alias`
- objects), the :attr:`.FromClause.c` collection is extracted
- to form a collection of :class:`.ColumnElement` objects.
-
- This parameter will also accept :class:`.Text` constructs as
+ :class:`_expression.FromClause` (typically :class:`_schema.Table`
+ or :class:`_expression.Alias`
+ objects), the :attr:`_expression.FromClause.c`
+ collection is extracted
+ to form a collection of :class:`_expression.ColumnElement` objects.
+
+ This parameter will also accept :class:`_expression.TextClause`
+ constructs as
given, as well as ORM-mapped classes.
.. note::
- The :paramref:`.select.columns` parameter is not available
- in the method form of :func:`~.sql.expression.select`, e.g.
- :meth:`.FromClause.select`.
+ The :paramref:`_expression.select.columns`
+ parameter is not available
+ in the method form of :func:`_expression.select`, e.g.
+ :meth:`_expression.FromClause.select`.
.. seealso::
- :meth:`.Select.column`
+ :meth:`_expression.Select.column`
- :meth:`.Select.with_only_columns`
+ :meth:`_expression.Select.with_only_columns`
:param whereclause:
- A :class:`.ClauseElement` expression which will be used to form the
+ A :class:`_expression.ClauseElement`
+ expression which will be used to form the
``WHERE`` clause. It is typically preferable to add WHERE
- criterion to an existing :class:`.Select` using method chaining
- with :meth:`.Select.where`.
+ criterion to an existing :class:`_expression.Select`
+ using method chaining
+ with :meth:`_expression.Select.where`.
.. seealso::
- :meth:`.Select.where`
+ :meth:`_expression.Select.where`
:param from_obj:
- A list of :class:`.ClauseElement` objects which will be added to the
+ A list of :class:`_expression.ClauseElement`
+ objects which will be added to the
``FROM`` clause of the resulting statement. This is equivalent
- to calling :meth:`.Select.select_from` using method chaining on
- an existing :class:`.Select` object.
+ to calling :meth:`_expression.Select.select_from`
+ using method chaining on
+ an existing :class:`_expression.Select` object.
.. seealso::
- :meth:`.Select.select_from` - full description of explicit
+ :meth:`_expression.Select.select_from`
+ - full description of explicit
FROM clause specification.
:param bind=None:
- an :class:`~.Engine` or :class:`~.Connection` instance
+ an :class:`_engine.Engine` or :class:`_engine.Connection` instance
to which the
- resulting :class:`.Select` object will be bound. The
- :class:`.Select` object will otherwise automatically bind to
+ resulting :class:`_expression.Select` object will be bound. The
+ :class:`_expression.Select`
+ object will otherwise automatically bind to
whatever :class:`~.base.Connectable` instances can be located within
- its contained :class:`.ClauseElement` members.
+ its contained :class:`_expression.ClauseElement` members.
:param correlate=True:
- indicates that this :class:`.Select` object should have its
- contained :class:`.FromClause` elements "correlated" to an enclosing
- :class:`.Select` object. It is typically preferable to specify
- correlations on an existing :class:`.Select` construct using
- :meth:`.Select.correlate`.
+ indicates that this :class:`_expression.Select`
+ object should have its
+ contained :class:`_expression.FromClause`
+ elements "correlated" to an enclosing
+ :class:`_expression.Select` object.
+ It is typically preferable to specify
+ correlations on an existing :class:`_expression.Select`
+ construct using
+ :meth:`_expression.Select.correlate`.
.. seealso::
- :meth:`.Select.correlate` - full description of correlation.
+ :meth:`_expression.Select.correlate`
+ - full description of correlation.
:param distinct=False:
when ``True``, applies a ``DISTINCT`` qualifier to the columns
@@ -3503,66 +3644,74 @@ class Select(
is understood by the PostgreSQL dialect to render the
``DISTINCT ON (<columns>)`` syntax.
- ``distinct`` is also available on an existing :class:`.Select`
- object via the :meth:`~.Select.distinct` method.
+ ``distinct`` is also available on an existing
+ :class:`_expression.Select`
+ object via the :meth:`_expression.Select.distinct` method.
.. seealso::
- :meth:`.Select.distinct`
+ :meth:`_expression.Select.distinct`
:param group_by:
- a list of :class:`.ClauseElement` objects which will comprise the
+ a list of :class:`_expression.ClauseElement`
+ objects which will comprise the
``GROUP BY`` clause of the resulting select. This parameter
is typically specified more naturally using the
- :meth:`.Select.group_by` method on an existing :class:`.Select`.
+ :meth:`_expression.Select.group_by` method on an existing
+ :class:`_expression.Select`.
.. seealso::
- :meth:`.Select.group_by`
+ :meth:`_expression.Select.group_by`
:param having:
- a :class:`.ClauseElement` that will comprise the ``HAVING`` clause
+ a :class:`_expression.ClauseElement`
+ that will comprise the ``HAVING`` clause
of the resulting select when ``GROUP BY`` is used. This parameter
is typically specified more naturally using the
- :meth:`.Select.having` method on an existing :class:`.Select`.
+ :meth:`_expression.Select.having` method on an existing
+ :class:`_expression.Select`.
.. seealso::
- :meth:`.Select.having`
+ :meth:`_expression.Select.having`
:param limit=None:
a numerical value which usually renders as a ``LIMIT``
expression in the resulting select. Backends that don't
support ``LIMIT`` will attempt to provide similar
functionality. This parameter is typically specified more
- naturally using the :meth:`.Select.limit` method on an existing
- :class:`.Select`.
+ naturally using the :meth:`_expression.Select.limit`
+ method on an existing
+ :class:`_expression.Select`.
.. seealso::
- :meth:`.Select.limit`
+ :meth:`_expression.Select.limit`
:param offset=None:
a numeric value which usually renders as an ``OFFSET``
expression in the resulting select. Backends that don't
support ``OFFSET`` will attempt to provide similar
functionality. This parameter is typically specified more naturally
- using the :meth:`.Select.offset` method on an existing
- :class:`.Select`.
+ using the :meth:`_expression.Select.offset` method on an existing
+ :class:`_expression.Select`.
.. seealso::
- :meth:`.Select.offset`
+ :meth:`_expression.Select.offset`
:param order_by:
- a scalar or list of :class:`.ClauseElement` objects which will
+ a scalar or list of :class:`_expression.ClauseElement`
+ objects which will
comprise the ``ORDER BY`` clause of the resulting select.
This parameter is typically specified more naturally using the
- :meth:`.Select.order_by` method on an existing :class:`.Select`.
+ :meth:`_expression.Select.order_by` method on an existing
+ :class:`_expression.Select`.
.. seealso::
- :meth:`.Select.order_by`
+ :meth:`_expression.Select.order_by`
:param use_labels=False:
when ``True``, the statement will be generated using labels
@@ -3570,16 +3719,18 @@ class Select(
column with its parent table's (or aliases) name so that name
conflicts between columns in different tables don't occur.
The format of the label is <tablename>_<column>. The "c"
- collection of the resulting :class:`.Select` object will use these
+ collection of the resulting :class:`_expression.Select`
+ object will use these
names as well for targeting column members.
This parameter can also be specified on an existing
- :class:`.Select` object using the :meth:`.Select.apply_labels`
+ :class:`_expression.Select` object using the
+ :meth:`_expression.Select.apply_labels`
method.
.. seealso::
- :meth:`.Select.apply_labels`
+ :meth:`_expression.Select.apply_labels`
"""
util.warn_deprecated_20(
@@ -3656,9 +3807,10 @@ class Select(
return self._compile_state_factory(self, None)._get_display_froms()
def with_statement_hint(self, text, dialect_name="*"):
- """add a statement hint to this :class:`.Select`.
+ """add a statement hint to this :class:`_expression.Select`.
- This method is similar to :meth:`.Select.with_hint` except that
+ This method is similar to :meth:`_expression.Select.with_hint`
+ except that
it does not require an individual table, and instead applies to the
statement as a whole.
@@ -3670,7 +3822,7 @@ class Select(
.. seealso::
- :meth:`.Select.with_hint`
+ :meth:`_expression.Select.with_hint`
:meth:.`.Select.prefix_with` - generic SELECT prefixing which also
can suit some database-specific HINT syntaxes such as MySQL
@@ -3682,11 +3834,12 @@ class Select(
@_generative
def with_hint(self, selectable, text, dialect_name="*"):
r"""Add an indexing or other executional context hint for the given
- selectable to this :class:`.Select`.
+ selectable to this :class:`_expression.Select`.
The text of the hint is rendered in the appropriate
location for the database backend in use, relative
- to the given :class:`.Table` or :class:`.Alias` passed as the
+ to the given :class:`_schema.Table` or :class:`_expression.Alias`
+ passed as the
``selectable`` argument. The dialect implementation
typically uses Python string substitution syntax
with the token ``%(name)s`` to render the name of
@@ -3710,7 +3863,7 @@ class Select(
.. seealso::
- :meth:`.Select.with_statement_hint`
+ :meth:`_expression.Select.with_statement_hint`
"""
if selectable is None:
@@ -3724,7 +3877,7 @@ class Select(
be rendered into the columns clause of the resulting SELECT statement.
This method is legacy as of 1.4 and is superseded by the
- :attr:`.Select.exported_columns` collection.
+ :attr:`_expression.Select.exported_columns` collection.
"""
@@ -3795,9 +3948,10 @@ class Select(
my_select = my_select.add_columns(table.c.new_column)
- See the documentation for :meth:`.Select.with_only_columns`
+ See the documentation for
+ :meth:`_expression.Select.with_only_columns`
for guidelines on adding /replacing the columns of a
- :class:`.Select` object.
+ :class:`_expression.Select` object.
"""
# memoizations should be cleared here as of
@@ -3812,9 +3966,9 @@ class Select(
@util.deprecated(
"1.4",
- "The :meth:`.Select.column` method is deprecated and will "
+ "The :meth:`_expression.Select.column` method is deprecated and will "
"be removed in a future release. Please use "
- ":meth:`.Select.add_columns`",
+ ":meth:`_expression.Select.add_columns`",
)
def column(self, column):
"""return a new select() construct with the given column expression
@@ -3824,9 +3978,10 @@ class Select(
my_select = my_select.column(table.c.new_column)
- See the documentation for :meth:`.Select.with_only_columns`
+ See the documentation for
+ :meth:`_expression.Select.with_only_columns`
for guidelines on adding /replacing the columns of a
- :class:`.Select` object.
+ :class:`_expression.Select` object.
"""
return self.add_columns(column)
@@ -3841,7 +3996,8 @@ class Select(
comparison in the WHERE clause of the statement. The primary purpose
of this method is to automatically construct a select statement
with all uniquely-named columns, without the need to use
- table-qualified labels as :meth:`.apply_labels` does.
+ table-qualified labels as :meth:`_expression.Select.apply_labels` does
+ .
When columns are omitted based on foreign key, the referred-to
column is the one that's kept. When columns are omitted based on
@@ -3863,11 +4019,11 @@ class Select(
@_generative
def with_only_columns(self, columns):
- r"""Return a new :func:`~.sql.expression.select` construct with its columns
+ r"""Return a new :func:`_expression.select` construct with its columns
clause replaced with the given columns.
This method is exactly equivalent to as if the original
- :func:`~.sql.expression.select` had been called with the given columns
+ :func:`_expression.select` had been called with the given columns
clause. I.e. a statement::
s = select([table1.c.a, table1.c.b])
@@ -3893,7 +4049,7 @@ class Select(
The preferred way to maintain a specific FROM clause
in the construct, assuming it won't be represented anywhere
else (i.e. not in the WHERE clause, etc.) is to set it using
- :meth:`.Select.select_from`::
+ :meth:`_expression.Select.select_from`::
>>> s1 = select([table1.c.a, table2.c.b]).\
... select_from(table1.join(table2,
@@ -3903,13 +4059,15 @@ class Select(
SELECT t2.b FROM t1 JOIN t2 ON t1.a=t2.a
Care should also be taken to use the correct set of column objects
- passed to :meth:`.Select.with_only_columns`. Since the method is
- essentially equivalent to calling the :func:`~.sql.expression.select`
+ passed to :meth:`_expression.Select.with_only_columns`.
+ Since the method is
+ essentially equivalent to calling the :func:`_expression.select`
construct in the first place with the given columns, the columns passed
- to :meth:`.Select.with_only_columns` should usually be a subset of
- those which were passed to the :func:`~.sql.expression.select`
+ to :meth:`_expression.Select.with_only_columns`
+ should usually be a subset of
+ those which were passed to the :func:`_expression.select`
construct, not those which are available from the ``.c`` collection of
- that :func:`~.sql.expression.select`. That is::
+ that :func:`_expression.select`. That is::
s = select([table1.c.a, table1.c.b]).select_from(table1)
s = s.with_only_columns([table1.c.b])
@@ -3925,7 +4083,7 @@ class Select(
FROM (SELECT t1.a AS a, t1.b AS b
FROM t1), t1
- Since the :func:`~.sql.expression.select` construct is essentially
+ Since the :func:`_expression.select` construct is essentially
being asked to select both from ``table1`` as well as itself.
"""
@@ -3945,7 +4103,8 @@ class Select(
@property
def _whereclause(self):
- """Legacy, return the WHERE clause as a :class:`.BooleanClauseList`"""
+ """Legacy, return the WHERE clause as a """
+ """:class:`_expression.BooleanClauseList`"""
return and_(*self._where_criteria)
@@ -3990,7 +4149,7 @@ class Select(
@_generative
def select_from(self, *froms):
- r"""return a new :func:`~.sql.expression.select` construct with the
+ r"""return a new :func:`_expression.select` construct with the
given FROM expression(s)
merged into its list of FROM objects.
@@ -4004,14 +4163,17 @@ class Select(
)
The "from" list is a unique set on the identity of each element,
- so adding an already present :class:`.Table` or other selectable
- will have no effect. Passing a :class:`.Join` that refers
- to an already present :class:`.Table` or other selectable will have
+ so adding an already present :class:`_schema.Table`
+ or other selectable
+ will have no effect. Passing a :class:`_expression.Join` that refers
+ to an already present :class:`_schema.Table`
+ or other selectable will have
the effect of concealing the presence of that selectable as
an individual element in the rendered FROM list, instead
rendering it into a JOIN clause.
- While the typical purpose of :meth:`.Select.select_from` is to
+ While the typical purpose of :meth:`_expression.Select.select_from`
+ is to
replace the default, derived FROM clause with a join, it can
also be called with individual table elements, multiple times
if desired, in the case that the FROM clause cannot be fully
@@ -4028,41 +4190,52 @@ class Select(
@_generative
def correlate(self, *fromclauses):
- r"""return a new :class:`.Select` which will correlate the given FROM
- clauses to that of an enclosing :class:`.Select`.
+ r"""return a new :class:`_expression.Select`
+ which will correlate the given FROM
+ clauses to that of an enclosing :class:`_expression.Select`.
- Calling this method turns off the :class:`.Select` object's
+ Calling this method turns off the :class:`_expression.Select` object's
default behavior of "auto-correlation". Normally, FROM elements
- which appear in a :class:`.Select` that encloses this one via
+ which appear in a :class:`_expression.Select`
+ that encloses this one via
its :term:`WHERE clause`, ORDER BY, HAVING or
- :term:`columns clause` will be omitted from this :class:`.Select`
+ :term:`columns clause` will be omitted from this
+ :class:`_expression.Select`
object's :term:`FROM clause`.
Setting an explicit correlation collection using the
- :meth:`.Select.correlate` method provides a fixed list of FROM objects
+ :meth:`_expression.Select.correlate`
+ method provides a fixed list of FROM objects
that can potentially take place in this process.
- When :meth:`.Select.correlate` is used to apply specific FROM clauses
+ When :meth:`_expression.Select.correlate`
+ is used to apply specific FROM clauses
for correlation, the FROM elements become candidates for
- correlation regardless of how deeply nested this :class:`.Select`
- object is, relative to an enclosing :class:`.Select` which refers to
+ correlation regardless of how deeply nested this
+ :class:`_expression.Select`
+ object is, relative to an enclosing :class:`_expression.Select`
+ which refers to
the same FROM object. This is in contrast to the behavior of
"auto-correlation" which only correlates to an immediate enclosing
- :class:`.Select`. Multi-level correlation ensures that the link
- between enclosed and enclosing :class:`.Select` is always via
+ :class:`_expression.Select`.
+ Multi-level correlation ensures that the link
+ between enclosed and enclosing :class:`_expression.Select`
+ is always via
at least one WHERE/ORDER BY/HAVING/columns clause in order for
correlation to take place.
- If ``None`` is passed, the :class:`.Select` object will correlate
+ If ``None`` is passed, the :class:`_expression.Select`
+ object will correlate
none of its FROM entries, and all will render unconditionally
in the local FROM clause.
- :param \*fromclauses: a list of one or more :class:`.FromClause`
+ :param \*fromclauses: a list of one or more
+ :class:`_expression.FromClause`
constructs, or other compatible constructs (i.e. ORM-mapped
classes) to become part of the correlate collection.
.. seealso::
- :meth:`.Select.correlate_except`
+ :meth:`_expression.Select.correlate_except`
:ref:`correlated_subqueries`
@@ -4078,26 +4251,29 @@ class Select(
@_generative
def correlate_except(self, *fromclauses):
- r"""return a new :class:`.Select` which will omit the given FROM
+ r"""return a new :class:`_expression.Select`
+ which will omit the given FROM
clauses from the auto-correlation process.
- Calling :meth:`.Select.correlate_except` turns off the
- :class:`.Select` object's default behavior of
+ Calling :meth:`_expression.Select.correlate_except` turns off the
+ :class:`_expression.Select` object's default behavior of
"auto-correlation" for the given FROM elements. An element
specified here will unconditionally appear in the FROM list, while
all other FROM elements remain subject to normal auto-correlation
behaviors.
- If ``None`` is passed, the :class:`.Select` object will correlate
+ If ``None`` is passed, the :class:`_expression.Select`
+ object will correlate
all of its FROM entries.
- :param \*fromclauses: a list of one or more :class:`.FromClause`
+ :param \*fromclauses: a list of one or more
+ :class:`_expression.FromClause`
constructs, or other compatible constructs (i.e. ORM-mapped
classes) to become part of the correlate-exception collection.
.. seealso::
- :meth:`.Select.correlate`
+ :meth:`_expression.Select.correlate`
:ref:`correlated_subqueries`
@@ -4113,18 +4289,22 @@ class Select(
@HasMemoized.memoized_attribute
def selected_columns(self):
- """A :class:`.ColumnCollection` representing the columns that
+ """A :class:`_expression.ColumnCollection`
+ representing the columns that
this SELECT statement or similar construct returns in its result set.
- This collection differs from the :attr:`.FromClause.columns` collection
- of a :class:`.FromClause` in that the columns within this collection
+ This collection differs from the
+ :attr:`_expression.FromClause.columns` collection
+ of a :class:`_expression.FromClause`
+ in that the columns within this collection
cannot be directly nested inside another SELECT statement; a subquery
must be applied first which provides for the necessary parenthesization
required by SQL.
- For a :func:`~.sql.expression.select` construct, the collection here is
+ For a :func:`_expression.select` construct, the collection here is
exactly what would be rendered inside the "SELECT" statement, and the
- :class:`.ColumnElement` objects are directly present as they were
+ :class:`_expression.ColumnElement`
+ objects are directly present as they were
given, e.g.::
col1 = column('q', Integer)
@@ -4133,9 +4313,11 @@ class Select(
Above, ``stmt.selected_columns`` would be a collection that contains
the ``col1`` and ``col2`` objects directly. For a statement that is
- against a :class:`.Table` or other :class:`.FromClause`, the collection
- will use the :class:`.ColumnElement` objects that are in the
- :attr:`.FromClause.c` collection of the from element.
+ against a :class:`_schema.Table` or other
+ :class:`_expression.FromClause`, the collection
+ will use the :class:`_expression.ColumnElement`
+ objects that are in the
+ :attr:`_expression.FromClause.c` collection of the from element.
.. versionadded:: 1.4
@@ -4425,7 +4607,7 @@ class ScalarSelect(roles.InElementRole, Generative, Grouping):
@_generative
def where(self, crit):
"""Apply a WHERE clause to the SELECT statement referred to
- by this :class:`.ScalarSelect`.
+ by this :class:`_expression.ScalarSelect`.
"""
self.element = self.element.where(crit)
@@ -4442,8 +4624,8 @@ class Exists(UnaryExpression):
_from_objects = []
def __init__(self, *args, **kwargs):
- """Construct a new :class:`.Exists` against an existing
- :class:`.Select` object.
+ """Construct a new :class:`_expression.Exists` against an existing
+ :class:`_expression.Select` object.
Calling styles are of the following forms::
@@ -4499,8 +4681,10 @@ class Exists(UnaryExpression):
return e
def select_from(self, clause):
- """return a new :class:`.Exists` construct, applying the given
- expression to the :meth:`.Select.select_from` method of the select
+ """return a new :class:`_expression.Exists` construct,
+ applying the given
+ expression to the :meth:`_expression.Select.select_from`
+ method of the select
statement contained.
"""
@@ -4519,25 +4703,30 @@ class Exists(UnaryExpression):
class TextualSelect(SelectBase):
- """Wrap a :class:`.TextClause` construct within a :class:`.SelectBase`
+ """Wrap a :class:`_expression.TextClause` construct within a
+ :class:`_expression.SelectBase`
interface.
- This allows the :class:`.TextClause` object to gain a ``.c`` collection
- and other FROM-like capabilities such as :meth:`.FromClause.alias`,
- :meth:`.SelectBase.cte`, etc.
+ This allows the :class:`_expression.TextClause` object to gain a ``.
+ c`` collection
+ and other FROM-like capabilities such as
+ :meth:`_expression.FromClause.alias`,
+ :meth:`_expression.SelectBase.cte`, etc.
- The :class:`.TextualSelect` construct is produced via the
- :meth:`.TextClause.columns` method - see that method for details.
+ The :class:`_expression.TextualSelect` construct is produced via the
+ :meth:`_expression.TextClause.columns`
+ method - see that method for details.
- .. versionchanged:: 1.4 the :class:`.TextualSelect` class was renamed
+ .. versionchanged:: 1.4 the :class:`_expression.TextualSelect`
+ class was renamed
from ``TextAsFrom``, to more correctly suit its role as a
SELECT-oriented object and not a FROM clause.
.. seealso::
- :func:`.text`
+ :func:`_expression.text`
- :meth:`.TextClause.columns` - primary creation interface.
+ :meth:`_expression.TextClause.columns` - primary creation interface.
"""
@@ -4562,18 +4751,23 @@ class TextualSelect(SelectBase):
@HasMemoized.memoized_attribute
def selected_columns(self):
- """A :class:`.ColumnCollection` representing the columns that
+ """A :class:`_expression.ColumnCollection`
+ representing the columns that
this SELECT statement or similar construct returns in its result set.
- This collection differs from the :attr:`.FromClause.columns` collection
- of a :class:`.FromClause` in that the columns within this collection
+ This collection differs from the
+ :attr:`_expression.FromClause.columns` collection
+ of a :class:`_expression.FromClause`
+ in that the columns within this collection
cannot be directly nested inside another SELECT statement; a subquery
must be applied first which provides for the necessary parenthesization
required by SQL.
- For a :class:`.TextualSelect` construct, the collection contains the
- :class:`.ColumnElement` objects that were passed to the constructor,
- typically via the :meth:`.TextClause.columns` method.
+ For a :class:`_expression.TextualSelect` construct,
+ the collection contains the
+ :class:`_expression.ColumnElement`
+ objects that were passed to the constructor,
+ typically via the :meth:`_expression.TextClause.columns` method.
.. versionadded:: 1.4
diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py
index 245b809ae..ba8a25821 100644
--- a/lib/sqlalchemy/sql/sqltypes.py
+++ b/lib/sqlalchemy/sql/sqltypes.py
@@ -210,7 +210,8 @@ class String(Concatenable, TypeEngine):
In the vast majority of cases, the :class:`.Unicode` or
:class:`.UnicodeText` datatypes should be used for a
- :class:`.Column` that expects to store non-ascii data. These
+ :class:`_schema.Column` that expects to store non-ascii data.
+ These
datatypes will ensure that the correct types are used on the
database side as well as set up the correct Unicode behaviors
under Python 2.
@@ -218,7 +219,7 @@ class String(Concatenable, TypeEngine):
.. seealso::
:paramref:`.create_engine.convert_unicode` -
- :class:`.Engine`-wide parameter
+ :class:`_engine.Engine`-wide parameter
:param unicode_error: Optional, a method to use to handle Unicode
conversion errors. Behaves like the ``errors`` keyword argument to
@@ -440,7 +441,7 @@ class UnicodeText(Text):
"""
Create a Unicode-converting Text type.
- Parameters are the same as that of :class:`.Text`,
+ Parameters are the same as that of :class:`_expression.TextClause`,
with the exception that ``convert_unicode``
defaults to ``True``.
@@ -774,7 +775,7 @@ class DateTime(_LookupExpressionAdapter, TypeEngine):
backends include additional options, such as timezone support and
fractional seconds support. For fractional seconds, use the
dialect-specific datatype, such as :class:`.mysql.TIME`. For
- timezone support, use at least the :class:`~.types.TIMESTAMP` datatype,
+ timezone support, use at least the :class:`_types.TIMESTAMP` datatype,
if not the dialect-specific datatype object.
"""
@@ -787,7 +788,7 @@ class DateTime(_LookupExpressionAdapter, TypeEngine):
:param timezone: boolean. Indicates that the datetime type should
enable timezone support, if available on the
**base date/time-holding type only**. It is recommended
- to make use of the :class:`~.types.TIMESTAMP` datatype directly when
+ to make use of the :class:`_types.TIMESTAMP` datatype directly when
using this flag, as some databases include separate generic
date/time-holding types distinct from the timezone-capable
TIMESTAMP datatype, such as Oracle.
@@ -980,7 +981,7 @@ class SchemaType(SchemaEventTarget):
:meth:`.DDLEvents.before_parent_attach` and
:meth:`.DDLEvents.after_parent_attach` events, where the events fire off
surrounding the association of the type object with a parent
- :class:`.Column`.
+ :class:`_schema.Column`.
.. seealso::
@@ -1231,7 +1232,7 @@ class Enum(Emulated, String, SchemaType):
.. seealso::
- :class:`.postgresql.ENUM` - PostgreSQL-specific type,
+ :class:`_postgresql.ENUM` - PostgreSQL-specific type,
which has additional functionality.
:class:`.mysql.ENUM` - MySQL-specific type
@@ -1312,16 +1313,17 @@ class Enum(Emulated, String, SchemaType):
The ``schema`` of the :class:`.Enum` type does not
by default make use of the ``schema`` established on the
- owning :class:`.Table`. If this behavior is desired,
+ owning :class:`_schema.Table`. If this behavior is desired,
set the ``inherit_schema`` flag to ``True``.
:param quote: Set explicit quoting preferences for the type's name.
:param inherit_schema: When ``True``, the "schema" from the owning
- :class:`.Table` will be copied to the "schema" attribute of this
+ :class:`_schema.Table`
+ will be copied to the "schema" attribute of this
:class:`.Enum`, replacing whatever value was passed for the
``schema`` attribute. This also takes effect when using the
- :meth:`.Table.tometadata` operation.
+ :meth:`_schema.Table.tometadata` operation.
:param validate_strings: when True, string values that are being
passed to the database in a SQL statement will be checked
@@ -1935,7 +1937,8 @@ class Interval(Emulated, _AbstractInterval, TypeDecorator):
class JSON(Indexable, TypeEngine):
"""Represent a SQL JSON type.
- .. note:: :class:`.types.JSON` is provided as a facade for vendor-specific
+ .. note:: :class:`_types.JSON`
+ is provided as a facade for vendor-specific
JSON types. Since it supports JSON SQL operations, it only
works on backends that have an actual JSON type, currently:
@@ -1945,10 +1948,10 @@ class JSON(Indexable, TypeEngine):
* SQLite as of version 3.9
- :class:`.types.JSON` is part of the Core in support of the growing
+ :class:`_types.JSON` is part of the Core in support of the growing
popularity of native JSON datatypes.
- The :class:`.types.JSON` type stores arbitrary JSON format data, e.g.::
+ The :class:`_types.JSON` type stores arbitrary JSON format data, e.g.::
data_table = Table('data_table', metadata,
Column('id', Integer, primary_key=True),
@@ -1963,7 +1966,8 @@ class JSON(Indexable, TypeEngine):
**JSON-Specific Expression Operators**
- The :class:`.types.JSON` datatype provides these additional SQL operations:
+ The :class:`_types.JSON`
+ datatype provides these additional SQL operations:
* Keyed index operations::
@@ -1985,15 +1989,16 @@ class JSON(Indexable, TypeEngine):
.. versionadded:: 1.3.11
Additional operations may be available from the dialect-specific versions
- of :class:`.types.JSON`, such as :class:`.postgresql.JSON` and
- :class:`.postgresql.JSONB` which both offer additional PostgreSQL-specific
+ of :class:`_types.JSON`, such as :class:`_postgresql.JSON` and
+ :class:`_postgresql.JSONB` which both offer additional PostgreSQL-specific
operations.
**Casting JSON Elements to Other Types**
Index operations, i.e. those invoked by calling upon the expression using
the Python bracket operator as in ``some_column['some key']``, return an
- expression object whose type defaults to :class:`.JSON` by default, so that
+ expression object whose type defaults to :class:`_types.JSON` by default,
+ so that
further JSON-oriented instructions may be called upon the result type.
However, it is likely more common that an index operation is expected
to return a specific scalar element, such as a string or integer. In
@@ -2042,7 +2047,7 @@ class JSON(Indexable, TypeEngine):
**Detecting Changes in JSON columns when using the ORM**
- The :class:`.JSON` type, when used with the SQLAlchemy ORM, does not
+ The :class:`_types.JSON` type, when used with the SQLAlchemy ORM, does not
detect in-place mutations to the structure. In order to detect these, the
:mod:`sqlalchemy.ext.mutable` extension must be used. This extension will
allow "in-place" changes to the datastructure to produce events which
@@ -2051,7 +2056,8 @@ class JSON(Indexable, TypeEngine):
**Support for JSON null vs. SQL NULL**
- When working with NULL values, the :class:`.JSON` type recommends the
+ When working with NULL values, the :class:`_types.JSON`
+ type recommends the
use of two specific constants in order to differentiate between a column
that evaluates to SQL NULL, e.g. no value, vs. the JSON-encoded string
of ``"null"``. To insert or select against a value that is SQL NULL,
@@ -2061,23 +2067,24 @@ class JSON(Indexable, TypeEngine):
conn.execute(table.insert(), json_value=null())
To insert or select against a value that is JSON ``"null"``, use the
- constant :attr:`.JSON.NULL`::
+ constant :attr:`_types.JSON.NULL`::
conn.execute(table.insert(), json_value=JSON.NULL)
- The :class:`.JSON` type supports a flag
- :paramref:`.JSON.none_as_null` which when set to True will result
+ The :class:`_types.JSON` type supports a flag
+ :paramref:`_types.JSON.none_as_null` which when set to True will result
in the Python constant ``None`` evaluating to the value of SQL
NULL, and when set to False results in the Python constant
``None`` evaluating to the value of JSON ``"null"``. The Python
value ``None`` may be used in conjunction with either
- :attr:`.JSON.NULL` and :func:`.null` in order to indicate NULL
+ :attr:`_types.JSON.NULL` and :func:`.null` in order to indicate NULL
values, but care must be taken as to the value of the
- :paramref:`.JSON.none_as_null` in these cases.
+ :paramref:`_types.JSON.none_as_null` in these cases.
**Customizing the JSON Serializer**
- The JSON serializer and deserializer used by :class:`.JSON` defaults to
+ The JSON serializer and deserializer used by :class:`_types.JSON`
+ defaults to
Python's ``json.dumps`` and ``json.loads`` functions; in the case of the
psycopg2 dialect, psycopg2 may be using its own custom loader function.
@@ -2099,13 +2106,13 @@ class JSON(Indexable, TypeEngine):
.. seealso::
- :class:`.postgresql.JSON`
+ :class:`_postgresql.JSON`
- :class:`.postgresql.JSONB`
+ :class:`_postgresql.JSONB`
:class:`.mysql.JSON`
- :class:`.sqlite.JSON`
+ :class:`_sqlite.JSON`
.. versionadded:: 1.1
@@ -2121,9 +2128,11 @@ class JSON(Indexable, TypeEngine):
This value is used to force the JSON value of ``"null"`` to be
used as the value. A value of Python ``None`` will be recognized
either as SQL NULL or JSON ``"null"``, based on the setting
- of the :paramref:`.JSON.none_as_null` flag; the :attr:`.JSON.NULL`
+ of the :paramref:`_types.JSON.none_as_null` flag; the
+ :attr:`_types.JSON.NULL`
constant can be used to always resolve to JSON ``"null"`` regardless
- of this setting. This is in contrast to the :func:`.sql.null` construct,
+ of this setting. This is in contrast to the :func:`_expression.null`
+ construct,
which always resolves to SQL NULL. E.g.::
from sqlalchemy import null
@@ -2139,15 +2148,16 @@ class JSON(Indexable, TypeEngine):
session.commit()
In order to set JSON NULL as a default value for a column, the most
- transparent method is to use :func:`.text`::
+ transparent method is to use :func:`_expression.text`::
Table(
'my_table', metadata,
Column('json_data', JSON, default=text("'null'"))
)
- While it is possible to use :attr:`.JSON.NULL` in this context, the
- :attr:`.JSON.NULL` value will be returned as the value of the column,
+ 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
+ ,
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
@@ -2157,7 +2167,7 @@ class JSON(Indexable, TypeEngine):
"""
def __init__(self, none_as_null=False):
- """Construct a :class:`.types.JSON` type.
+ """Construct a :class:`_types.JSON` type.
:param none_as_null=False: if True, persist the value ``None`` as a
SQL NULL value, not the JSON encoding of ``null``. Note that
@@ -2169,9 +2179,9 @@ class JSON(Indexable, TypeEngine):
.. note::
- :paramref:`.JSON.none_as_null` does **not** apply to the
- values passed to :paramref:`.Column.default` and
- :paramref:`.Column.server_default`; a value of ``None``
+ :paramref:`_types.JSON.none_as_null` does **not** apply to the
+ values passed to :paramref:`_schema.Column.default` and
+ :paramref:`_schema.Column.server_default`; a value of ``None``
passed for these parameters means "no default present".
.. seealso::
@@ -2236,7 +2246,7 @@ class JSON(Indexable, TypeEngine):
"""
class Comparator(Indexable.Comparator, Concatenable.Comparator):
- """Define comparison operations for :class:`.types.JSON`."""
+ """Define comparison operations for :class:`_types.JSON`."""
def _setup_getitem(self, index):
if not isinstance(index, util.string_types) and isinstance(
@@ -2366,7 +2376,7 @@ class JSON(Indexable, TypeEngine):
@property
def should_evaluate_none(self):
- """Alias of :attr:`.JSON.none_as_null`"""
+ """Alias of :attr:`_types.JSON.none_as_null`"""
return not self.none_as_null
@should_evaluate_none.setter
@@ -2417,17 +2427,18 @@ class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine):
.. note:: This type serves as the basis for all ARRAY operations.
However, currently **only the PostgreSQL backend has support
for SQL arrays in SQLAlchemy**. It is recommended to use the
- :class:`.postgresql.ARRAY` type directly when using ARRAY types
+ :class:`_postgresql.ARRAY` type directly when using ARRAY types
with PostgreSQL, as it provides additional operators specific
to that backend.
- :class:`.types.ARRAY` is part of the Core in support of various SQL
- standard functions such as :class:`.array_agg` which explicitly involve
+ :class:`_types.ARRAY` is part of the Core in support of various SQL
+ standard functions such as :class:`_functions.array_agg`
+ which explicitly involve
arrays; however, with the exception of the PostgreSQL backend and possibly
some third-party dialects, no other SQLAlchemy built-in dialect has support
for this type.
- An :class:`.types.ARRAY` type is constructed given the "type"
+ An :class:`_types.ARRAY` type is constructed given the "type"
of element::
mytable = Table("mytable", metadata,
@@ -2444,7 +2455,7 @@ class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine):
data=[1,2,3]
)
- The :class:`.types.ARRAY` type can be constructed given a fixed number
+ The :class:`_types.ARRAY` type can be constructed given a fixed number
of dimensions::
mytable = Table("mytable", metadata,
@@ -2470,10 +2481,10 @@ class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine):
>>> expr = table.c.column[5] # returns ARRAY(Integer, dimensions=1)
>>> expr = expr[6] # returns Integer
- For 1-dimensional arrays, an :class:`.types.ARRAY` instance with no
+ For 1-dimensional arrays, an :class:`_types.ARRAY` instance with no
dimension parameter will generally assume single-dimensional behaviors.
- SQL expressions of type :class:`.types.ARRAY` have support for "index" and
+ SQL expressions of type :class:`_types.ARRAY` have support for "index" and
"slice" behavior. The Python ``[]`` operator works normally here, given
integer indexes or slices. Arrays default to 1-based indexing.
The operator produces binary expression
@@ -2482,7 +2493,8 @@ class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine):
select([mytable.c.data[5], mytable.c.data[2:7]])
- as well as UPDATE statements when the :meth:`.Update.values` method
+ as well as UPDATE statements when the :meth:`_expression.Update.values`
+ method
is used::
mytable.update().values({
@@ -2490,16 +2502,16 @@ class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine):
mytable.c.data[2:7]: [1, 2, 3]
})
- The :class:`.types.ARRAY` type also provides for the operators
+ The :class:`_types.ARRAY` type also provides for the operators
:meth:`.types.ARRAY.Comparator.any` and
:meth:`.types.ARRAY.Comparator.all`. The PostgreSQL-specific version of
- :class:`.types.ARRAY` also provides additional operators.
+ :class:`_types.ARRAY` also provides additional operators.
.. versionadded:: 1.1.0
.. seealso::
- :class:`.postgresql.ARRAY`
+ :class:`_postgresql.ARRAY`
"""
@@ -2511,7 +2523,7 @@ class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine):
class Comparator(Indexable.Comparator, Concatenable.Comparator):
- """Define comparison operations for :class:`.types.ARRAY`.
+ """Define comparison operations for :class:`_types.ARRAY`.
More operators are available on the dialect-specific form
of this type. See :class:`.postgresql.ARRAY.Comparator`.
@@ -2586,7 +2598,7 @@ class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine):
.. seealso::
- :func:`.sql.expression.any_`
+ :func:`_expression.any_`
:meth:`.types.ARRAY.Comparator.all`
@@ -2622,7 +2634,7 @@ class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine):
.. seealso::
- :func:`.sql.expression.all_`
+ :func:`_expression.all_`
:meth:`.types.ARRAY.Comparator.any`
@@ -2639,7 +2651,7 @@ class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine):
def __init__(
self, item_type, as_tuple=False, dimensions=None, zero_indexes=False
):
- """Construct an :class:`.types.ARRAY`.
+ """Construct an :class:`_types.ARRAY`.
E.g.::
@@ -2662,7 +2674,7 @@ class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine):
on the database, how it goes about interpreting Python and
result values, as well as how expression behavior in conjunction
with the "getitem" operator works. See the description at
- :class:`.types.ARRAY` for additional detail.
+ :class:`_types.ARRAY` for additional detail.
:param zero_indexes=False: when True, index values will be converted
between Python zero-based and SQL one-based indexes, e.g.
@@ -2764,7 +2776,7 @@ class TIMESTAMP(DateTime):
"""The SQL TIMESTAMP type.
- :class:`~.types.TIMESTAMP` datatypes have support for timezone
+ :class:`_types.TIMESTAMP` datatypes have support for timezone
storage on some backends, such as PostgreSQL and Oracle. Use the
:paramref:`~types.TIMESTAMP.timezone` argument in order to enable
"TIMESTAMP WITH TIMEZONE" for these backends.
@@ -2774,7 +2786,7 @@ class TIMESTAMP(DateTime):
__visit_name__ = "TIMESTAMP"
def __init__(self, timezone=False):
- """Construct a new :class:`.TIMESTAMP`.
+ """Construct a new :class:`_types.TIMESTAMP`.
:param timezone: boolean. Indicates that the TIMESTAMP type should
enable timezone support, if available on the target database.
@@ -2895,7 +2907,8 @@ class NullType(TypeEngine):
by the :class:`.Dialect`
* When constructing SQL expressions using plain Python objects of
unknown types (e.g. ``somecolumn == my_special_object``)
- * When a new :class:`.Column` is created, and the given type is passed
+ * When a new :class:`_schema.Column` is created,
+ and the given type is passed
as ``None`` or is not passed at all.
The :class:`.NullType` can be used within SQL expression invocation
@@ -2904,7 +2917,8 @@ class NullType(TypeEngine):
:class:`.NullType` will result in a :exc:`.CompileError` if the compiler
is asked to render the type itself, such as if it is used in a
:func:`.cast` operation or within a schema creation operation such as that
- invoked by :meth:`.MetaData.create_all` or the :class:`.CreateTable`
+ invoked by :meth:`_schema.MetaData.create_all` or the
+ :class:`.CreateTable`
construct.
"""
diff --git a/lib/sqlalchemy/sql/traversals.py b/lib/sqlalchemy/sql/traversals.py
index 032488826..4a135538e 100644
--- a/lib/sqlalchemy/sql/traversals.py
+++ b/lib/sqlalchemy/sql/traversals.py
@@ -165,7 +165,7 @@ class HasCacheKey(HasMemoized):
each one; these bound parameters must be consulted in order to
execute the statement with the correct parameters.
- a :class:`.ClauseElement` structure that does not implement
+ a :class:`_expression.ClauseElement` structure that does not implement
a :meth:`._gen_cache_key` method and does not implement a
:attr:`.traverse_internals` attribute will not be cacheable; when
such an element is embedded into a larger structure, this method
diff --git a/lib/sqlalchemy/sql/type_api.py b/lib/sqlalchemy/sql/type_api.py
index e9632c502..ccda21e11 100644
--- a/lib/sqlalchemy/sql/type_api.py
+++ b/lib/sqlalchemy/sql/type_api.py
@@ -82,7 +82,8 @@ class TypeEngine(Traversible):
This method determines the type of a resulting binary expression
given two source types and an operator. For example, two
- :class:`.Column` objects, both of the type :class:`.Integer`, will
+ :class:`_schema.Column` objects, both of the type
+ :class:`.Integer`, will
produce a :class:`.BinaryExpression` that also has the type
:class:`.Integer` when compared via the addition (``+``) operator.
However, using the addition operator with an :class:`.Integer`
@@ -116,7 +117,8 @@ class TypeEngine(Traversible):
comparator_factory = Comparator
"""A :class:`.TypeEngine.Comparator` class which will apply
- to operations performed by owning :class:`.ColumnElement` objects.
+ to operations performed by owning :class:`_expression.ColumnElement`
+ objects.
The :attr:`.comparator_factory` attribute is a hook consulted by
the core expression system when column and SQL expression operations
@@ -195,14 +197,15 @@ class TypeEngine(Traversible):
In all cases, the actual NULL SQL value can be always be
persisted in any column by using
- the :obj:`~.expression.null` SQL construct in an INSERT statement
+ the :obj:`_expression.null` SQL construct in an INSERT statement
or associated with an ORM-mapped attribute.
.. note::
The "evaluates none" flag does **not** apply to a value
- of ``None`` passed to :paramref:`.Column.default` or
- :paramref:`.Column.server_default`; in these cases, ``None``
+ of ``None`` passed to :paramref:`_schema.Column.default` or
+ :paramref:`_schema.Column.server_default`; in these cases,
+ ``None``
still means "no default".
.. versionadded:: 1.1
@@ -676,7 +679,7 @@ class UserDefinedType(util.with_metaclass(VisitableCheckKWArg, TypeEngine)):
The ``get_col_spec()`` method will in most cases receive a keyword
argument ``type_expression`` which refers to the owning expression
- of the type as being compiled, such as a :class:`.Column` or
+ of the type as being compiled, such as a :class:`_schema.Column` or
:func:`.cast` construct. This keyword is only sent if the method
accepts keyword arguments (e.g. ``**kw``) in its argument signature;
introspection is used to check for this in order to support legacy
@@ -859,7 +862,7 @@ class TypeDecorator(SchemaEventTarget, TypeEngine):
If the :class:`.TypeDecorator` is augmenting a
type that requires special logic for certain types of operators,
this method **must** be overridden. A key example is when decorating
- the :class:`.postgresql.JSON` and :class:`.postgresql.JSONB` types;
+ the :class:`_postgresql.JSON` and :class:`_postgresql.JSONB` types;
the default rules of :meth:`.TypeEngine.coerce_compared_value` should
be used in order to deal with operators like index operations::
diff --git a/lib/sqlalchemy/sql/visitors.py b/lib/sqlalchemy/sql/visitors.py
index 29ed01309..8f6bb2333 100644
--- a/lib/sqlalchemy/sql/visitors.py
+++ b/lib/sqlalchemy/sql/visitors.py
@@ -228,35 +228,37 @@ class InternalTraversal(util.with_metaclass(_InternalTraversalType, object)):
"""Visit a :class:`.HasCacheKey` object."""
dp_clauseelement = symbol("CE")
- """Visit a :class:`.ClauseElement` object."""
+ """Visit a :class:`_expression.ClauseElement` object."""
dp_fromclause_canonical_column_collection = symbol("FC")
- """Visit a :class:`.FromClause` object in the context of the
+ """Visit a :class:`_expression.FromClause` object in the context of the
``columns`` attribute.
The column collection is "canonical", meaning it is the originally
defined location of the :class:`.ColumnClause` objects. Right now
- this means that the object being visited is a :class:`.TableClause`
- or :class:`.Table` object only.
+ this means that the object being visited is a
+ :class:`_expression.TableClause`
+ or :class:`_schema.Table` object only.
"""
dp_clauseelement_tuples = symbol("CT")
- """Visit a list of tuples which contain :class:`.ClauseElement`
+ """Visit a list of tuples which contain :class:`_expression.ClauseElement`
objects.
"""
dp_clauseelement_list = symbol("CL")
- """Visit a list of :class:`.ClauseElement` objects.
+ """Visit a list of :class:`_expression.ClauseElement` objects.
"""
dp_clauseelement_unordered_set = symbol("CU")
- """Visit an unordered set of :class:`.ClauseElement` objects. """
+ """Visit an unordered set of :class:`_expression.ClauseElement`
+ objects. """
dp_fromclause_ordered_set = symbol("CO")
- """Visit an ordered set of :class:`.FromClause` objects. """
+ """Visit an ordered set of :class:`_expression.FromClause` objects. """
dp_string = symbol("S")
"""Visit a plain string value.
@@ -320,7 +322,7 @@ class InternalTraversal(util.with_metaclass(_InternalTraversalType, object)):
"""visit a dialect options structure."""
dp_string_clauseelement_dict = symbol("CD")
- """Visit a dictionary of string keys to :class:`.ClauseElement`
+ """Visit a dictionary of string keys to :class:`_expression.ClauseElement`
objects.
"""
@@ -361,18 +363,20 @@ class InternalTraversal(util.with_metaclass(_InternalTraversalType, object)):
"""
dp_prefix_sequence = symbol("PS")
- """Visit the sequence represented by :class:`.HasPrefixes`
- or :class:`.HasSuffixes`.
+ """Visit the sequence represented by :class:`_expression.HasPrefixes`
+ or :class:`_expression.HasSuffixes`.
"""
dp_table_hint_list = symbol("TH")
- """Visit the ``_hints`` collection of a :class:`.Select` object.
+ """Visit the ``_hints`` collection of a :class:`_expression.Select` object
+ .
"""
dp_statement_hint_list = symbol("SH")
- """Visit the ``_statement_hints`` collection of a :class:`.Select`
+ """Visit the ``_statement_hints`` collection of a
+ :class:`_expression.Select`
object.
"""
@@ -383,7 +387,8 @@ class InternalTraversal(util.with_metaclass(_InternalTraversalType, object)):
"""
dp_dml_ordered_values = symbol("DML_OV")
- """visit the values() ordered tuple list of an :class:`.Update` object."""
+ """visit the values() ordered tuple list of an
+ :class:`_expression.Update` object."""
dp_dml_values = symbol("DML_V")
"""visit the values() dictionary of a :class:`.ValuesBase`
@@ -393,7 +398,7 @@ class InternalTraversal(util.with_metaclass(_InternalTraversalType, object)):
dp_dml_multi_values = symbol("DML_MV")
"""visit the values() multi-valued list of dictionaries of an
- :class:`~.sql.expression.Insert` object.
+ :class:`_expression.Insert` object.
"""
@@ -401,7 +406,7 @@ class InternalTraversal(util.with_metaclass(_InternalTraversalType, object)):
class ExtendedInternalTraversal(InternalTraversal):
"""defines additional symbols that are useful in caching applications.
- Traversals for :class:`.ClauseElement` objects only need to use
+ Traversals for :class:`_expression.ClauseElement` objects only need to use
those symbols present in :class:`.InternalTraversal`. However, for
additional caching use cases within the ORM, symbols dealing with the
:class:`.HasCacheKey` class are added here.
@@ -570,14 +575,18 @@ def iterate(obj, opts):
The central API feature used by the :func:`.visitors.iterate` and
:func:`.visitors.iterate_depthfirst` functions is the
- :meth:`.ClauseElement.get_children` method of :class:`.ClauseElement`
- objects. This method should return all the :class:`.ClauseElement` objects
- which are associated with a particular :class:`.ClauseElement` object.
+ :meth:`_expression.ClauseElement.get_children` method of
+ :class:`_expression.ClauseElement`
+ objects. This method should return all the
+ :class:`_expression.ClauseElement` objects
+ which are associated with a particular :class:`_expression.ClauseElement`
+ object.
For example, a :class:`.Case` structure will refer to a series of
- :class:`.ColumnElement` objects within its "whens" and "else\_" member
+ :class:`_expression.ColumnElement`
+ objects within its "whens" and "else\_" member
variables.
- :param obj: :class:`.ClauseElement` structure to be traversed
+ :param obj: :class:`_expression.ClauseElement` structure to be traversed
:param opts: dictionary of iteration options. This dictionary is usually
empty in modern usage.
@@ -603,7 +612,7 @@ def iterate_depthfirst(obj, opts):
traversal is configured to be depth-first.
- :param obj: :class:`.ClauseElement` structure to be traversed
+ :param obj: :class:`_expression.ClauseElement` structure to be traversed
:param opts: dictionary of iteration options. This dictionary is usually
empty in modern usage.
@@ -637,11 +646,13 @@ def traverse_using(iterator, obj, visitors):
functions.
:param iterator: an iterable or sequence which will yield
- :class:`.ClauseElement` structures; the iterator is assumed to be the
+ :class:`_expression.ClauseElement`
+ structures; the iterator is assumed to be the
product of the :func:`.visitors.iterate` or
:func:`.visitors.iterate_depthfirst` functions.
- :param obj: the :class:`.ClauseElement` that was used as the target of the
+ :param obj: the :class:`_expression.ClauseElement`
+ that was used as the target of the
:func:`.iterate` or :func:`.iterate_depthfirst` function.
:param visitors: dictionary of visit functions. See :func:`.traverse`
@@ -679,7 +690,7 @@ def traverse(obj, opts, visitors):
The iteration of objects uses the :func:`.visitors.iterate` function,
which does a breadth-first traversal using a stack.
- :param obj: :class:`.ClauseElement` structure to be traversed
+ :param obj: :class:`_expression.ClauseElement` structure to be traversed
:param opts: dictionary of iteration options. This dictionary is usually
empty in modern usage.
@@ -718,9 +729,12 @@ def cloned_traverse(obj, opts, visitors):
The central API feature used by the :func:`.visitors.cloned_traverse`
and :func:`.visitors.replacement_traverse` functions, in addition to the
- :meth:`.ClauseElement.get_children` function that is used to achieve
- the iteration, is the :meth:`.ClauseElement._copy_internals` method.
- For a :class:`.ClauseElement` structure to support cloning and replacement
+ :meth:`_expression.ClauseElement.get_children`
+ function that is used to achieve
+ the iteration, is the :meth:`_expression.ClauseElement._copy_internals`
+ method.
+ For a :class:`_expression.ClauseElement`
+ structure to support cloning and replacement
traversals correctly, it needs to be able to pass a cloning function into
its internal members in order to make copies of them.
View Lorry Controller Status