diff options
| author | mike bayer <mike_mp@zzzcomputing.com> | 2020-04-14 19:48:20 +0000 |
|---|---|---|
| committer | Gerrit Code Review <gerrit@bbpush.zzzcomputing.com> | 2020-04-14 19:48:20 +0000 |
| commit | d9b230e78c70c17a6856f4ff3b8380b9ce510702 (patch) | |
| tree | 3e1583daaa76cff27fbdf5de8b3b1f63c00a1225 /lib/sqlalchemy/sql/selectable.py | |
| parent | f39cf13680a0ee5b190d498d29ea31c76f546dfb (diff) | |
| parent | cea03be855514d592b6671fa6dbc074a19a795fb (diff) | |
| download | sqlalchemy-d9b230e78c70c17a6856f4ff3b8380b9ce510702.tar.gz | |
Merge "Run search and replace of symbolic module names"
Diffstat (limited to 'lib/sqlalchemy/sql/selectable.py')
| -rw-r--r-- | lib/sqlalchemy/sql/selectable.py | 1078 |
1 files changed, 636 insertions, 442 deletions
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 |