From 2cafd6150fabf1f0119453d96dd07df6428a9440 Mon Sep 17 00:00:00 2001 From: aplatkouski <5857672+aplatkouski@users.noreply.github.com> Date: Wed, 10 Jun 2020 21:55:56 +0300 Subject: [PATCH] Fix typos in 'Selectables, Tables, FROM objects' Signed-off-by: aplatkouski <5857672+aplatkouski@users.noreply.github.com> --- doc/build/changelog/changelog_08.rst | 2 +- doc/build/changelog/changelog_10.rst | 2 +- doc/build/changelog/migration_13.rst | 2 +- doc/build/changelog/migration_20.rst | 2 +- doc/build/core/tutorial.rst | 2 +- doc/build/faq/sessions.rst | 2 +- doc/build/glossary.rst | 2 +- doc/build/orm/tutorial.rst | 20 +-- lib/sqlalchemy/engine/create.py | 4 +- lib/sqlalchemy/ext/hybrid.py | 2 +- lib/sqlalchemy/future/selectable.py | 2 +- lib/sqlalchemy/orm/mapper.py | 4 +- lib/sqlalchemy/orm/query.py | 4 +- lib/sqlalchemy/sql/base.py | 10 +- lib/sqlalchemy/sql/dml.py | 2 +- lib/sqlalchemy/sql/elements.py | 19 ++- lib/sqlalchemy/sql/selectable.py | 229 ++++++++++++++------------- 17 files changed, 162 insertions(+), 148 deletions(-) diff --git a/doc/build/changelog/changelog_08.rst b/doc/build/changelog/changelog_08.rst index fbd7b837fb..d0b49a0506 100644 --- a/doc/build/changelog/changelog_08.rst +++ b/doc/build/changelog/changelog_08.rst @@ -356,7 +356,7 @@ :tickets: 2957 :versions: 0.9.3 - Fixed bug where :meth:`.ColumnOperators.in_()` would go into an endless + Fixed bug where :meth:`.ColumnOperators.in_` would go into an endless loop if erroneously passed a column expression whose comparator included the ``__getitem__()`` method, such as a column that uses the :class:`_postgresql.ARRAY` type. diff --git a/doc/build/changelog/changelog_10.rst b/doc/build/changelog/changelog_10.rst index f4e012c230..7058a2ae23 100644 --- a/doc/build/changelog/changelog_10.rst +++ b/doc/build/changelog/changelog_10.rst @@ -1473,7 +1473,7 @@ to a modern pool invalidation in that connections aren't actively closed, but are recycled only on next checkout; this is essentially a per-connection version of that feature. A new event - :class:`_events.PoolEvents.soft_invalidate` is added to complement it. + :meth:`_events.PoolEvents.soft_invalidate` is added to complement it. Also added new flag :attr:`.ExceptionContext.invalidate_pool_on_disconnect`. diff --git a/doc/build/changelog/migration_13.rst b/doc/build/changelog/migration_13.rst index 6e29133508..e7c35c02c3 100644 --- a/doc/build/changelog/migration_13.rst +++ b/doc/build/changelog/migration_13.rst @@ -886,7 +886,7 @@ FOR UPDATE clause is rendered within the joined eager load subquery as well as o This change applies specifically to the use of the :func:`_orm.joinedload` loading strategy in conjunction with a row limited query, e.g. using :meth:`_query.Query.first` -or :meth:`_query.Query.limit`, as well as with use of the :class:`_query.Query.with_for_update` method. +or :meth:`_query.Query.limit`, as well as with use of the :meth:`_query.Query.with_for_update` method. Given a query as:: diff --git a/doc/build/changelog/migration_20.rst b/doc/build/changelog/migration_20.rst index 9ba038cf5f..2a6ccfcdcf 100644 --- a/doc/build/changelog/migration_20.rst +++ b/doc/build/changelog/migration_20.rst @@ -873,7 +873,7 @@ of self-referential joins, such as:: Where above, there would be two JOINs between three instances of the "node" table assuming ``Node.children`` is a self-referential (e.g. adjacency list) -relationship to the ``Node`` class itself. the "node" table would be aliased +relationship to the ``Node`` class itself. The "node" table would be aliased at each step and the final ``filter()`` call would adapt itself to the last "node" table in the chain. diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst index 7db84c7d63..e84ef965cd 100644 --- a/doc/build/core/tutorial.rst +++ b/doc/build/core/tutorial.rst @@ -1215,7 +1215,7 @@ SELECT-oriented constructs which extend from :class:`_expression.SelectBase` may into aliased subqueries using the :meth:`_expression.SelectBase.subquery` method, which produces a :class:`.Subquery` construct; for ease of use, there is also a :meth:`_expression.SelectBase.alias` method that is synonymous with -:class:`_expression.SelectBase.subquery`. Like :class:`_expression.Alias`, :class:`.Subquery` is +:meth:`_expression.SelectBase.subquery`. Like :class:`_expression.Alias`, :class:`.Subquery` is also a :class:`_expression.FromClause` object that may be part of any enclosing SELECT using the same techniques one would use for a :class:`_expression.Alias`. diff --git a/doc/build/faq/sessions.rst b/doc/build/faq/sessions.rst index 76cabf7653..835ce301ff 100644 --- a/doc/build/faq/sessions.rst +++ b/doc/build/faq/sessions.rst @@ -198,7 +198,7 @@ This transaction is "logical" in that it does not actually use any database resources until a SQL statement is invoked, at which point a connection-level and DBAPI-level transaction is started. However, whether or not database-level transactions are part of its state, the logical transaction will -stay in place until it is ended using :meth:`.Session.commit()`, +stay in place until it is ended using :meth:`.Session.commit`, :meth:`.Session.rollback`, or :meth:`.Session.close`. When the ``flush()`` above fails, the code is still within the transaction diff --git a/doc/build/glossary.rst b/doc/build/glossary.rst index 5b656b9c7a..b982101153 100644 --- a/doc/build/glossary.rst +++ b/doc/build/glossary.rst @@ -23,7 +23,7 @@ Glossary A term used in SQLAlchemy to describe a SQL construct that represents a collection of rows. It's largely similar to the concept of a "relation" in :term:`relational algebra`. In SQLAlchemy, objects - that subclass the :class:`expression.Selectable` class are considered to be + that subclass the :class:`_expression.Selectable` class are considered to be usable as "selectables" when using SQLAlchemy Core. The two most common constructs are that of the :class:`_schema.Table` and that of the :class:`_expression.Select` statement. diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst index 13763f6bc1..a6ef57bed1 100644 --- a/doc/build/orm/tutorial.rst +++ b/doc/build/orm/tutorial.rst @@ -849,7 +849,7 @@ A number of methods on :class:`_query.Query` immediately issue SQL and return a value containing loaded database results. Here's a brief tour: -* :meth:`_query.Query.all()` returns a list: +* :meth:`_query.Query.all` returns a list: .. sourcecode:: python+sql @@ -880,7 +880,7 @@ database results. Here's a brief tour: :ref:`faq_query_deduplicating` -* :meth:`_query.Query.first()` applies a limit of one and returns +* :meth:`_query.Query.first` applies a limit of one and returns the first result as a scalar: .. sourcecode:: python+sql @@ -896,7 +896,7 @@ database results. Here's a brief tour: [...] ('%ed', 1, 0) {stop} -* :meth:`_query.Query.one()` fully fetches all rows, and if not +* :meth:`_query.Query.one` fully fetches all rows, and if not exactly one object identity or composite row is present in the result, raises an error. With multiple rows found: @@ -949,8 +949,8 @@ Literal strings can be used flexibly with :class:`~sqlalchemy.orm.query.Query`, by specifying their use with the :func:`_expression.text` construct, which is accepted by most applicable methods. For example, -:meth:`~sqlalchemy.orm.query.Query.filter()` and -:meth:`~sqlalchemy.orm.query.Query.order_by()`: +:meth:`_query.Query.filter` and +:meth:`_query.Query.order_by`: .. sourcecode:: python+sql @@ -972,7 +972,7 @@ by most applicable methods. For example, fred Bind parameters can be specified with string-based SQL, using a colon. To -specify the values, use the :meth:`~sqlalchemy.orm.query.Query.params()` +specify the values, use the :meth:`_query.Query.params` method: .. sourcecode:: python+sql @@ -990,7 +990,7 @@ method: To use an entirely string-based statement, a :func:`_expression.text` construct representing a complete statement can be passed to -:meth:`~sqlalchemy.orm.query.Query.from_statement()`. Without further +:meth:`_query.Query.from_statement`. Without further specification, the ORM will match columns in the ORM mapping to the result returned by the SQL statement based on column name: @@ -1040,7 +1040,7 @@ Counting -------- :class:`~sqlalchemy.orm.query.Query` includes a convenience method for -counting called :meth:`~sqlalchemy.orm.query.Query.count()`: +counting called :meth:`_query.Query.count`: .. sourcecode:: python+sql @@ -1065,7 +1065,7 @@ counting called :meth:`~sqlalchemy.orm.query.Query.count()`: and always returns the right answer. Use ``func.count()`` if a particular statement absolutely cannot tolerate the subquery being present. -The :meth:`_query.Query.count()` method is used to determine +The :meth:`_query.Query.count` method is used to determine how many rows the SQL statement would return. Looking at the generated SQL above, SQLAlchemy always places whatever it is we are querying into a subquery, then counts the rows from that. In some cases @@ -1328,7 +1328,7 @@ The `Wikipedia page on SQL JOIN join techniques, several of which we'll illustrate here. To construct a simple implicit join between ``User`` and ``Address``, -we can use :meth:`_query.Query.filter()` to equate their related columns together. +we can use :meth:`_query.Query.filter` to equate their related columns together. Below we load the ``User`` and ``Address`` entities at once using this method: .. sourcecode:: python+sql diff --git a/lib/sqlalchemy/engine/create.py b/lib/sqlalchemy/engine/create.py index 9bf72eb068..cc138412b1 100644 --- a/lib/sqlalchemy/engine/create.py +++ b/lib/sqlalchemy/engine/create.py @@ -123,13 +123,13 @@ def create_engine(url, **kwargs): parameters specified in the URL argument to be bypassed. This hook is not as flexible as the newer - :class:`_events.DialectEvents.do_connect` hook which allows complete + :meth:`_events.DialectEvents.do_connect` hook which allows complete control over how a connection is made to the database, given the full set of URL arguments and state beforehand. .. seealso:: - :class:`_events.DialectEvents.do_connect` - event hook that allows + :meth:`_events.DialectEvents.do_connect` - event hook that allows full control over DBAPI connection mechanics. :ref:`custom_dbapi_args` diff --git a/lib/sqlalchemy/ext/hybrid.py b/lib/sqlalchemy/ext/hybrid.py index 6b4cf989ca..8269eb1c10 100644 --- a/lib/sqlalchemy/ext/hybrid.py +++ b/lib/sqlalchemy/ext/hybrid.py @@ -711,7 +711,7 @@ the comparison ``Node(id=5)``. A function ``transform`` is then returned which will transform a :class:`_query.Query` first to join to ``Node.parent``, then to compare ``parent_alias`` using :attr:`.Operators.eq` against the left and right -sides, passing into :class:`_query.Query.filter`: +sides, passing into :meth:`_query.Query.filter`: .. sourcecode:: pycon+sql diff --git a/lib/sqlalchemy/future/selectable.py b/lib/sqlalchemy/future/selectable.py index 53fc7c1072..ce609e7db7 100644 --- a/lib/sqlalchemy/future/selectable.py +++ b/lib/sqlalchemy/future/selectable.py @@ -91,7 +91,7 @@ class Select(_LegacySelect): return self._raw_columns[0] def filter_by(self, **kwargs): - r"""apply the given filtering criterion as a WHERE clause + r"""Apply the given filtering criterion as a WHERE clause to this select. """ diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py index c2c49912e1..a4501a1e4b 100644 --- a/lib/sqlalchemy/orm/mapper.py +++ b/lib/sqlalchemy/orm/mapper.py @@ -733,7 +733,7 @@ class Mapper( return self.class_ local_table = None - """The :class:`expression.Selectable` which this :class:`_orm.Mapper` + """The :class:`_expression.Selectable` which this :class:`_orm.Mapper` manages. Typically is an instance of :class:`_schema.Table` or @@ -756,7 +756,7 @@ class Mapper( """ persist_selectable = None - """The :class:`expression.Selectable` to which this :class:`_orm.Mapper` + """The :class:`_expression.Selectable` to which this :class:`_orm.Mapper` is mapped. Typically an instance of :class:`_schema.Table`, diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py index 0aa1901e83..2a1a04d28b 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -436,7 +436,7 @@ class Query( reduce_columns=False, _legacy_core_statement=False, ): - """return the full SELECT statement represented by + """Return the full SELECT statement represented by this :class:`_query.Query`, embedded within an :class:`_expression.Alias`. @@ -1812,7 +1812,7 @@ class Query( @_generative @_assertions(_no_statement_condition, _no_limit_offset) def having(self, criterion): - r"""apply a HAVING criterion to the query and return the + r"""Apply a HAVING criterion to the query and return the newly resulting :class:`_query.Query`. :meth:`_query.Query.having` is used in conjunction with diff --git a/lib/sqlalchemy/sql/base.py b/lib/sqlalchemy/sql/base.py index 7a57be3fd3..4339b67829 100644 --- a/lib/sqlalchemy/sql/base.py +++ b/lib/sqlalchemy/sql/base.py @@ -611,7 +611,7 @@ class CacheableOptions(Options, HasCacheKey): class Executable(Generative): - """Mark a ClauseElement as supporting execution. + """Mark a :class:`_expression.ClauseElement` as supporting execution. :class:`.Executable` is a superclass for all "statement" types of objects, including :func:`select`, :func:`delete`, :func:`update`, @@ -1079,17 +1079,17 @@ class ColumnCollection(object): 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:: - :meth:`expression.Selectable.corresponding_column` + :meth:`_expression.Selectable.corresponding_column` - invokes this method against the collection returned by - :attr:`expression.Selectable.exported_columns`. + :attr:`_expression.Selectable.exported_columns`. .. versionchanged:: 1.4 the implementation for ``corresponding_column`` was moved onto the :class:`_expression.ColumnCollection` itself. diff --git a/lib/sqlalchemy/sql/dml.py b/lib/sqlalchemy/sql/dml.py index 22aac9010e..d72450fb5c 100644 --- a/lib/sqlalchemy/sql/dml.py +++ b/lib/sqlalchemy/sql/dml.py @@ -943,7 +943,7 @@ class DMLWhereBase(object): @_generative def where(self, whereclause): - """return a new construct with the given expression added to + """Return a new construct with the given expression added to its WHERE clause, joined to the existing clause via AND, if any. """ diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py index 5e071f3ea1..abd4469a1f 100644 --- a/lib/sqlalchemy/sql/elements.py +++ b/lib/sqlalchemy/sql/elements.py @@ -312,9 +312,11 @@ class ClauseElement( raise exc.ObjectNotExecutableError(self) def unique_params(self, *optionaldict, **kwargs): - """Return a copy with :func:`bindparam()` elements replaced. + """Return a copy with :func:`_expression.bindparam` elements + replaced. - Same functionality as ``params()``, except adds `unique=True` + Same functionality as :meth:`_expression.ClauseElement.params`, + except adds `unique=True` to affected bind parameters so that multiple statements can be used. @@ -322,9 +324,11 @@ class ClauseElement( return self._replace_params(True, optionaldict, kwargs) def params(self, *optionaldict, **kwargs): - """Return a copy with :func:`bindparam()` elements replaced. + """Return a copy with :func:`_expression.bindparam` elements + replaced. - Returns a copy of this ClauseElement with :func:`bindparam()` + Returns a copy of this ClauseElement with + :func:`_expression.bindparam` elements replaced with values taken from the given dictionary:: >>> clause = column('x') + bindparam('foo') @@ -354,7 +358,8 @@ class ClauseElement( return cloned_traverse(self, {}, {"bindparam": visit_bindparam}) def compare(self, other, **kw): - r"""Compare this ``ClauseElement`` to the given ``ClauseElement``. + r"""Compare this :class:`_expression.ClauseElement` to + the given :class:`_expression.ClauseElement`. Subclasses should override the default behavior, which is a straight identity comparison. @@ -396,8 +401,8 @@ class ClauseElement( setattr(self, attrname, result) def get_children(self, omit_attrs=(), **kw): - r"""Return immediate child :class:`.Traversible` elements of this - :class:`.Traversible`. + r"""Return immediate child :class:`.visitors.Traversible` + elements of this :class:`.visitors.Traversible`. This is used for visit traversal. diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py index 801f2b67c8..62736f30a1 100644 --- a/lib/sqlalchemy/sql/selectable.py +++ b/lib/sqlalchemy/sql/selectable.py @@ -77,7 +77,7 @@ def subquery(alias, *args, **kwargs): 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. @@ -154,7 +154,7 @@ class ReturnsRows(roles.ReturnsRowsRole, ClauseElement): class Selectable(ReturnsRows): - """mark a class as being selectable. + """Mark a class as being selectable. """ @@ -170,7 +170,7 @@ class Selectable(ReturnsRows): 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. @@ -192,7 +192,8 @@ 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 + """Replace all occurrences of :class:`_expression.FromClause` + 'old' with the given :class:`_expression.Alias` object, returning a copy of this :class:`_expression.FromClause`. """ @@ -201,8 +202,8 @@ class Selectable(ReturnsRows): 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. @@ -214,14 +215,14 @@ class Selectable(ReturnsRows): 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 @@ -353,7 +354,7 @@ class HasHints(object): ] 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` @@ -468,7 +469,7 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): _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:: @@ -572,7 +573,7 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): 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.:: @@ -609,8 +610,8 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): 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. @@ -621,8 +622,8 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): 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. @@ -632,7 +633,7 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): @property def description(self): - """a brief description of this FromClause. + """A brief description of this :class:`_expression.FromClause`. Used primarily for error message formatting. @@ -648,7 +649,7 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): 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 @@ -658,7 +659,7 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): .. seealso:: - :attr:`expression.Selectable.exported_columns` + :attr:`_expression.Selectable.exported_columns` :attr:`_expression.SelectBase.exported_columns` @@ -694,7 +695,7 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): 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. @@ -720,7 +721,7 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): 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 @@ -792,7 +793,7 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): class Join(roles.DMLTableRole, FromClause): - """represent a ``JOIN`` construct between two + """Represent a ``JOIN`` construct between two :class:`_expression.FromClause` elements. @@ -857,7 +858,7 @@ class Join(roles.DMLTableRole, FromClause): 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. @@ -922,9 +923,9 @@ class Join(roles.DMLTableRole, FromClause): .. 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. """ @@ -984,7 +985,7 @@ class Join(roles.DMLTableRole, FromClause): 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.:: @@ -1169,7 +1170,7 @@ class Join(roles.DMLTableRole, FromClause): @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 @@ -1376,7 +1377,7 @@ class AliasedReturnsRows(NoInit, FromClause): @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): @@ -1675,7 +1676,7 @@ class CTE(Generative, HasPrefixes, HasSuffixes, AliasedReturnsRows): :class:`_expression.CTE`. This method is a CTE-specific specialization of the - :class:`_expression.FromClause.alias` method. + :meth:`_expression.FromClause.alias` method. .. seealso:: @@ -1754,8 +1755,8 @@ class HasCTE(roles.HasCTERole): 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 @@ -1896,7 +1897,7 @@ class Subquery(AliasedReturnsRows): 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 @@ -2212,7 +2213,7 @@ class ForUpdateArg(ClauseElement): 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 @@ -2283,7 +2284,7 @@ class Values(Generative, FromClause): 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:: @@ -2390,7 +2391,7 @@ class SelectBase( 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 @@ -2400,7 +2401,7 @@ class SelectBase( .. seealso:: - :attr:`expression.Selectable.exported_columns` + :attr:`_expression.Selectable.exported_columns` :attr:`_expression.FromClause.exported_columns` @@ -2436,7 +2437,7 @@ class SelectBase( "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) @@ -2480,7 +2481,7 @@ class SelectBase( 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 @@ -2503,7 +2504,7 @@ class SelectBase( 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:: @@ -2514,7 +2515,7 @@ class SelectBase( 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. @@ -2535,8 +2536,9 @@ class SelectBase( 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:: @@ -2836,7 +2838,7 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase): 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 @@ -2940,7 +2942,7 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase): @_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`` @@ -2960,7 +2962,7 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase): @_generative def offset(self, offset): - """return a new selectable with the given OFFSET criterion + """Return a new selectable with the given OFFSET criterion applied. @@ -2982,14 +2984,14 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase): @_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. @@ -3009,7 +3011,7 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase): @_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.:: @@ -3017,7 +3019,7 @@ 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:`_expression.ColumnElement` + :param \*clauses: a series of :class:`_expression.ColumnElement` constructs which will be used to generate an GROUP BY clause. @@ -3049,7 +3051,7 @@ class CompoundSelectState(CompileState): class CompoundSelect(HasCompileState, GenerativeSelect): """Forms the basis of ``UNION``, ``UNION ALL``, and other - SELECT-based set operations. + SELECT-based set operations. .. seealso:: @@ -3318,7 +3320,7 @@ class DeprecatedSelectGenerations(object): "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 @@ -3337,7 +3339,7 @@ class DeprecatedSelectGenerations(object): "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.:: @@ -3363,7 +3365,7 @@ class DeprecatedSelectGenerations(object): "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 @@ -3382,7 +3384,7 @@ class DeprecatedSelectGenerations(object): "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. @@ -3402,7 +3404,7 @@ class DeprecatedSelectGenerations(object): "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. @@ -3423,8 +3425,8 @@ class DeprecatedSelectGenerations(object): "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, @@ -3689,7 +3691,7 @@ class SelectState(util.MemoizedSlots, CompileState): "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: @@ -3697,7 +3699,7 @@ class SelectState(util.MemoizedSlots, CompileState): "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 @@ -3855,8 +3857,8 @@ class Select( 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 @@ -3865,8 +3867,8 @@ class Select( 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:: @@ -4035,7 +4037,7 @@ class Select( 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 _. The "c" + The format of the label is ``_``. The "c" collection of the resulting :class:`_expression.Select` object will use these names as well for targeting column members. @@ -4112,13 +4114,16 @@ class Select( @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 @@ -4198,17 +4203,17 @@ class Select( @_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 @@ -4238,24 +4243,24 @@ class Select( ":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 @@ -4263,8 +4268,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:`_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 @@ -4371,8 +4376,8 @@ class Select( @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. @@ -4390,7 +4395,8 @@ class Select( @_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. """ @@ -4401,7 +4407,8 @@ class Select( @_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. """ @@ -4411,8 +4418,8 @@ class Select( @_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 (>)`` @@ -4432,7 +4439,7 @@ class Select( @_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. @@ -4475,7 +4482,7 @@ class Select( @_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`. @@ -4536,7 +4543,7 @@ class 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. @@ -4736,8 +4743,8 @@ class Select( 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 = [] @@ -4785,8 +4792,8 @@ class Select( ) 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 @@ -4802,14 +4809,15 @@ class Select( 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) @@ -4829,15 +4837,15 @@ class Select( 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) @@ -4969,7 +4977,7 @@ class Exists(UnaryExpression): 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 @@ -4981,7 +4989,8 @@ class Exists(UnaryExpression): 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. """ @@ -4995,8 +5004,8 @@ class TextualSelect(SelectBase): :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. -- 2.47.3