r"""Return an :class:`.Subquery` object derived
from a :class:`_expression.Select`.
- :param name: the alias name for the subquery
+ :param alias: the alias name for the subquery
:param \*args, \**kwargs: all other arguments are passed through to the
:func:`_expression.select` function.
class Selectable(ReturnsRows):
- """mark a class as being selectable.
+ """Mark a class as being selectable.
"""
raise NotImplementedError()
def lateral(self, name=None):
- """Return a LATERAL alias of this :class:`expression.Selectable`.
+ """Return a LATERAL alias of this :class:`_expression.Selectable`.
The return value is the :class:`_expression.Lateral` construct also
provided by the top-level :func:`_expression.lateral` function.
)
@util.preload_module("sqlalchemy.sql.util")
def replace_selectable(self, old, alias):
- """replace all occurrences of FromClause 'old' with the given Alias
+ """Replace all occurrences of :class:`_expression.FromClause`
+ 'old' with the given :class:`_expression.Alias`
object, returning a copy of this :class:`_expression.FromClause`.
"""
def corresponding_column(self, column, require_embedded=False):
"""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`
+ :attr:`_expression.Selectable.exported_columns`
+ collection of this :class:`_expression.Selectable`
which corresponds to that
original :class:`_expression.ColumnElement` via a common ancestor
column.
the given :class:`_expression.ColumnElement`, if the given
:class:`_expression.ColumnElement`
is actually present within a sub-element
- of this :class:`expression.Selectable`.
+ 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:`expression.Selectable`.
+ columns of this :class:`_expression.Selectable`.
.. seealso::
- :attr:`expression.Selectable.exported_columns` - the
+ :attr:`_expression.Selectable.exported_columns` - the
:class:`_expression.ColumnCollection`
that is used for the operation
]
def with_statement_hint(self, text, dialect_name="*"):
- """add a statement hint to this :class:`_expression.Select` or
+ """Add a statement hint to this :class:`_expression.Select` or
other selectable object.
This method is similar to :meth:`_expression.Select.with_hint`
_use_schema_map = False
def select(self, whereclause=None, **params):
- """return a SELECT of this :class:`_expression.FromClause`.
+ """Return a SELECT of this :class:`_expression.FromClause`.
.. seealso::
return Join(self, right, onclause, True, full)
def alias(self, name=None, flat=False):
- """return an alias of this :class:`_expression.FromClause`.
+ """Return an alias of this :class:`_expression.FromClause`.
E.g.::
return TableSample._construct(self, sampling, name, seed)
def is_derived_from(self, fromclause):
- """Return True if this FromClause is 'derived' from the given
- FromClause.
+ """Return ``True`` if this :class:`_expression.FromClause` is
+ 'derived' from the given ``FromClause``.
An example would be an Alias of a Table is derived from that Table.
return fromclause in self._cloned_set
def _is_lexical_equivalent(self, other):
- """Return True if this FromClause and the other represent
- the same lexical identity.
+ """Return ``True`` if this :class:`_expression.FromClause` and
+ the other represent the same lexical identity.
This tests if either one is a copy of the other, or
if they are the same via annotation identity.
@property
def description(self):
- """a brief description of this FromClause.
+ """A brief description of this :class:`_expression.FromClause`.
Used primarily for error message formatting.
def exported_columns(self):
"""A :class:`_expression.ColumnCollection`
that represents the "exported"
- columns of this :class:`expression.Selectable`.
+ columns of this :class:`_expression.Selectable`.
The "exported" columns for a :class:`_expression.FromClause`
object are synonymous
.. seealso::
- :attr:`expression.Selectable.exported_columns`
+ :attr:`_expression.Selectable.exported_columns`
:attr:`_expression.SelectBase.exported_columns`
stmt.filter_by(address='some address')
- It defaults to the .c collection, however internally it can
+ It defaults to the ``.c`` collection, however internally it can
be overridden using the "entity_namespace" annotation to deliver
alternative results.
return self.foreign_keys
def _reset_column_collection(self):
- """Reset the attributes linked to the FromClause.c attribute.
+ """Reset the attributes linked to the ``FromClause.c`` attribute.
This collection is separate from all the other memoized things
as it has shown to be sensitive to being cleared out in situations
class Join(roles.DMLTableRole, FromClause):
- """represent a ``JOIN`` construct between two
+ """Represent a ``JOIN`` construct between two
:class:`_expression.FromClause`
elements.
The returned object is an instance of :class:`_expression.Join`.
Similar functionality is also available via the
- :meth:`_expression.FromClause.outerjoin()` method on any
+ :meth:`_expression.FromClause.outerjoin` method on any
:class:`_expression.FromClause`.
:param left: The left side of the join.
.. seealso::
:meth:`_expression.FromClause.join` - method form,
- based on a given left side
+ based on a given left side.
- :class:`_expression.Join` - the type of object produced
+ :class:`_expression.Join` - the type of object produced.
"""
def _join_condition(
cls, a, b, a_subset=None, consider_as_foreign_keys=None
):
- """create a join condition between two tables or selectables.
+ """Create a join condition between two tables or selectables.
e.g.::
@util.preload_module("sqlalchemy.sql.util")
def alias(self, name=None, flat=False):
- r"""return an alias of this :class:`_expression.Join`.
+ r"""Return an alias of this :class:`_expression.Join`.
The default behavior here is to first produce a SELECT
construct from this :class:`_expression.Join`, then to produce an
@property
def original(self):
- """legacy for dialects that are referring to Alias.original"""
+ """Legacy for dialects that are referring to Alias.original."""
return self.element
def is_derived_from(self, fromclause):
:class:`_expression.CTE`.
This method is a CTE-specific specialization of the
- :class:`_expression.FromClause.alias` method.
+ :meth:`_expression.FromClause.alias` method.
.. seealso::
In particular - MATERIALIZED and NOT MATERIALIZED.
:param name: name given to the common table expression. Like
- :meth:`._FromClause.alias`, the name can be left as ``None``
- in which case an anonymous symbol will be used at query
+ :meth:`_expression.FromClause.alias`, the name can be left as
+ ``None`` in which case an anonymous symbol will be used at query
compile time.
:param recursive: if ``True``, will render ``WITH RECURSIVE``.
A recursive common table expression is intended to be used in
A :class:`.Subquery` is created by invoking the
:meth:`_expression.SelectBase.subquery` method, or for convenience the
- :class:`_expression.SelectBase.alias` method, on any
+ :meth:`_expression.SelectBase.alias` method, on any
:class:`_expression.SelectBase` subclass
which includes :class:`_expression.Select`,
:class:`_expression.CompoundSelect`, and
class Values(Generative, FromClause):
- """represent a ``VALUES`` construct that can be used as a FROM element
+ """Represent a ``VALUES`` construct that can be used as a FROM element
in a statement.
The :class:`_expression.Values` object is created from the
one with the given name.
This method is a VALUES-specific specialization of the
- :class:`_expression.FromClause.alias` method.
+ :meth:`_expression.FromClause.alias` method.
.. seealso::
def exported_columns(self):
"""A :class:`_expression.ColumnCollection`
that represents the "exported"
- columns of this :class:`expression.Selectable`.
+ columns of this :class:`_expression.Selectable`.
The "exported" columns for a :class:`_expression.SelectBase`
object are synonymous
.. seealso::
- :attr:`expression.Selectable.exported_columns`
+ :attr:`_expression.Selectable.exported_columns`
:attr:`_expression.FromClause.exported_columns`
"creates a subquery that should be explicit. "
"Please call :meth:`_expression.SelectBase.subquery` "
"first in order to create "
- "a subquery, which then can be seleted.",
+ "a subquery, which then can be selected.",
)
def select(self, *arg, **kw):
return self._implicit_subquery.select(*arg, **kw)
return self.scalar_subquery()
def scalar_subquery(self):
- """return a 'scalar' representation of this selectable, which can be
+ """Return a 'scalar' representation of this selectable, which can be
used as a column expression.
Typically, a select statement which has only one column in its columns
return ScalarSelect(self)
def label(self, name):
- """return a 'scalar' representation of this selectable, embedded as a
+ """Return a 'scalar' representation of this selectable, embedded as a
subquery with a label.
.. seealso::
return self.scalar_subquery().label(name)
def lateral(self, name=None):
- """Return a LATERAL alias of this :class:`expression.Selectable`.
+ """Return a LATERAL alias of this :class:`_expression.Selectable`.
The return value is the :class:`_expression.Lateral` construct also
provided by the top-level :func:`_expression.lateral` function.
def subquery(self, name=None):
"""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.
+ A subquery is from a SQL perspective a parenthesized, named
+ construct that can be placed in the FROM clause of another
+ SELECT statement.
Given a SELECT statement such as::
return self._label_style is LABEL_STYLE_TABLENAME_PLUS_COL
def apply_labels(self):
- """return a new selectable with the 'use_labels' flag set to True.
+ """Return a new selectable with the 'use_labels' flag set to True.
This will result in column expressions being generated using labels
against their table name, such as "SELECT somecolumn AS
@_generative
def limit(self, limit):
- """return a new selectable with the given LIMIT criterion
+ """Return a new selectable with the given LIMIT criterion
applied.
This is a numerical value which usually renders as a ``LIMIT``
@_generative
def offset(self, offset):
- """return a new selectable with the given OFFSET criterion
+ """Return a new selectable with the given OFFSET criterion
applied.
@_generative
def order_by(self, *clauses):
- r"""return a new selectable with the given list of ORDER BY
+ r"""Return a new selectable with the given list of ORDER BY
criterion applied.
e.g.::
stmt = select([table]).order_by(table.c.id, table.c.name)
- :param \*order_by: a series of :class:`_expression.ColumnElement`
+ :param \*clauses: a series of :class:`_expression.ColumnElement`
constructs
which will be used to generate an ORDER BY clause.
@_generative
def group_by(self, *clauses):
- r"""return a new selectable with the given list of GROUP BY
+ r"""Return a new selectable with the given list of GROUP BY
criterion applied.
e.g.::
stmt = select([table.c.name, func.max(table.c.stat)]).\
group_by(table.c.name)
- :param \*group_by: a series of :class:`_expression.ColumnElement`
+ :param \*clauses: a series of :class:`_expression.ColumnElement`
constructs
which will be used to generate an GROUP BY clause.
class CompoundSelect(HasCompileState, GenerativeSelect):
"""Forms the basis of ``UNION``, ``UNION ALL``, and other
- SELECT-based set operations.
+ SELECT-based set operations.
.. seealso::
"method :meth:`_expression.Select.correlate`.",
)
def append_correlation(self, fromclause):
- """append the given correlation expression to this select()
+ """Append the given correlation expression to this select()
construct.
This is an **in-place** mutation method; the
"method :meth:`_expression.Select.column`.",
)
def append_column(self, column):
- """append the given column expression to the columns clause of this
+ """Append the given column expression to the columns clause of this
select() construct.
E.g.::
"method :meth:`_expression.Select.prefix_with`.",
)
def append_prefix(self, clause):
- """append the given columns clause prefix expression to this select()
+ """Append the given columns clause prefix expression to this select()
construct.
This is an **in-place** mutation method; the
"method :meth:`_expression.Select.where`.",
)
def append_whereclause(self, whereclause):
- """append the given expression to this select() construct's WHERE
+ """Append the given expression to this select() construct's WHERE
criterion.
The expression will be joined to existing WHERE criterion via AND.
"method :meth:`_expression.Select.having`.",
)
def append_having(self, having):
- """append the given expression to this select() construct's HAVING
+ """Append the given expression to this select() construct's HAVING
criterion.
The expression will be joined to existing HAVING criterion via AND.
"method :meth:`_expression.Select.select_from`.",
)
def append_from(self, fromclause):
- """append the given FromClause expression to this select() construct's
- FROM clause.
+ """Append the given :class:`_expression.FromClause` expression
+ to this select() construct's FROM clause.
This is an **in-place** mutation method; the
:meth:`_expression.Select.select_from` method is preferred,
"from, there are multiple FROMS which can "
"join to this entity. Please use the .select_from() "
"method to establish an explicit left side, as well as "
- "providing an explcit ON clause if not present already to "
+ "providing an explicit ON clause if not present already to "
"help resolve the ambiguity."
)
elif not indexes:
"Don't know how to join to %r. "
"Please use the .select_from() "
"method to establish an explicit left side, as well as "
- "providing an explcit ON clause if not present already to "
+ "providing an explicit ON clause if not present already to "
"help resolve the ambiguity." % (right,)
)
return left, replace_from_obj_index
suffixes=None,
**kwargs
):
- """Construct a new :class:`_expression.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:`_expression.FromClause.select` method on any
All arguments which accept :class:`_expression.ClauseElement`
arguments also
accept string arguments, which will be converted as appropriate into
- either :func:`_expression.text()` or
- :func:`_expression.literal_column()` constructs.
+ either :func:`_expression.text` or
+ :func:`_expression.literal_column` constructs.
.. seealso::
for each column in the columns clause, which qualify each
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"
+ The format of the label is ``<tablename>_<column>``. The "c"
collection of the resulting :class:`_expression.Select`
object will use these
names as well for targeting column members.
@property
def froms(self):
- """Return the displayed list of FromClause elements."""
+ """Return the displayed list of :class:`_expression.FromClause`
+ elements.
+ """
return self._compile_state_factory(self, None)._get_display_froms()
@property
def inner_columns(self):
- """an iterator of all ColumnElement expressions which would
+ """An iterator of all :class:`_expression.ColumnElement`
+ expressions which would
be rendered into the columns clause of the resulting SELECT statement.
This method is legacy as of 1.4 and is superseded by the
@_generative
def add_columns(self, *columns):
- """return a new select() construct with the given column expressions
- added to its columns clause.
+ """Return a new :func:`_expression.select` construct with
+ the given column expressions added to its columns clause.
- E.g.::
+ E.g.::
- my_select = my_select.add_columns(table.c.new_column)
+ my_select = my_select.add_columns(table.c.new_column)
- See the documentation for
- :meth:`_expression.Select.with_only_columns`
- for guidelines on adding /replacing the columns of a
- :class:`_expression.Select` object.
+ See the documentation for
+ :meth:`_expression.Select.with_only_columns`
+ for guidelines on adding /replacing the columns of a
+ :class:`_expression.Select` object.
"""
# memoizations should be cleared here as of
":meth:`_expression.Select.add_columns`",
)
def column(self, column):
- """return a new select() construct with the given column expression
- added to its columns clause.
+ """Return a new :func:`_expression.select` construct with
+ the given column expression added to its columns clause.
- E.g.::
+ E.g.::
- my_select = my_select.column(table.c.new_column)
+ my_select = my_select.column(table.c.new_column)
- See the documentation for
- :meth:`_expression.Select.with_only_columns`
- for guidelines on adding /replacing the columns of a
- :class:`_expression.Select` object.
+ See the documentation for
+ :meth:`_expression.Select.with_only_columns`
+ for guidelines on adding /replacing the columns of a
+ :class:`_expression.Select` object.
"""
return self.add_columns(column)
@util.preload_module("sqlalchemy.sql.util")
def reduce_columns(self, only_synonyms=True):
- """Return a new :func:`.select` construct with redundantly
+ """Return a new :func:`_expression.select` construct with redundantly
named, equivalently-valued columns removed from the columns clause.
"Redundant" here means two columns where one refers to the
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:`_expression.Select.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
@property
def whereclause(self):
- """Return the completed WHERE clause for this :class:`.Select`
- statement.
+ """Return the completed WHERE clause for this
+ :class:`_expression.Select` statement.
This assembles the current collection of WHERE criteria
into a single :class:`_expression.BooleanClauseList` construct.
@_generative
def where(self, whereclause):
- """return a new select() construct with the given expression added to
+ """Return a new :func:`_expression.select` construct with
+ the given expression added to
its WHERE clause, joined to the existing clause via AND, if any.
"""
@_generative
def having(self, having):
- """return a new select() construct with the given expression added to
+ """Return a new :func:`_expression.select` construct with
+ the given expression added to
its HAVING clause, joined to the existing clause via AND, if any.
"""
@_generative
def distinct(self, *expr):
- r"""Return a new select() construct which will apply DISTINCT to its
- columns clause.
+ r"""Return a new :func:`_expression.select` construct which
+ will apply DISTINCT to its columns clause.
:param \*expr: optional column expressions. When present,
the PostgreSQL dialect will render a ``DISTINCT ON (<expressions>>)``
@_generative
def select_from(self, *froms):
- r"""return a new :func:`_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.
@_generative
def correlate(self, *fromclauses):
- r"""return a new :class:`_expression.Select`
+ r"""Return a new :class:`_expression.Select`
which will correlate the given FROM
clauses to that of an enclosing :class:`_expression.Select`.
@_generative
def correlate_except(self, *fromclauses):
- r"""return a new :class:`_expression.Select`
+ r"""Return a new :class:`_expression.Select`
which will omit the given FROM
clauses from the auto-correlation process.
return [name_for_col(c) for c in cols]
def _generate_fromclause_column_proxies(self, subquery):
- """generate column proxies to place in the exported .c collection
- of a subquery."""
+ """Generate column proxies to place in the exported ``.c``
+ collection of a subquery."""
keys_seen = set()
prox = []
)
def self_group(self, against=None):
- """return a 'grouping' construct as per the ClauseElement
- specification.
+ """Return a 'grouping' construct as per the
+ :class:`_expression.ClauseElement` specification.
This produces an element that can be embedded in an expression. Note
that this method is called automatically as needed when constructing
return SelectStatementGrouping(self)
def union(self, other, **kwargs):
- """return a SQL UNION of this select() construct against the given
- selectable."""
+ """Return a SQL ``UNION`` of this select() construct against
+ the given selectable.
+ """
return CompoundSelect._create_union(self, other, **kwargs)
def union_all(self, other, **kwargs):
- """return a SQL UNION ALL of this select() construct against the given
- selectable.
+ """Return a SQL ``UNION ALL`` of this select() construct against
+ the given selectable.
"""
return CompoundSelect._create_union_all(self, other, **kwargs)
return CompoundSelect._create_except_all(self, other, **kwargs)
def intersect(self, other, **kwargs):
- """return a SQL INTERSECT of this select() construct against the given
- selectable.
+ """Return a SQL ``INTERSECT`` of this select() construct against
+ the given selectable.
"""
return CompoundSelect._create_intersect(self, other, **kwargs)
def intersect_all(self, other, **kwargs):
- """return a SQL INTERSECT ALL of this select() construct against the
- given selectable.
+ """Return a SQL ``INTERSECT ALL`` of this select() construct
+ against the given selectable.
"""
return CompoundSelect._create_intersect_all(self, other, **kwargs)
return e
def select_from(self, clause):
- """return a new :class:`_expression.Exists` construct,
+ """Return a new :class:`_expression.Exists` construct,
applying the given
expression to the :meth:`_expression.Select.select_from`
method of the select
return e
def where(self, clause):
- """return a new exists() construct with the given expression added to
+ """Return a new :func:`_expression.exists` construct with the
+ given expression added to
its WHERE clause, joined to the existing clause via AND, if any.
"""
:class:`_expression.SelectBase`
interface.
- This allows the :class:`_expression.TextClause` object to gain a ``.
- c`` collection
+ 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.
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
