From 0c4e648af7276711b8eca7b645190ee80281c382 Mon Sep 17 00:00:00 2001 From: aplatkouski <5857672+aplatkouski@users.noreply.github.com> Date: Tue, 9 Jun 2020 22:53:52 +0300 Subject: [PATCH] Fix typos in 'SQL Expression Language Tutorial' Signed-off-by: aplatkouski <5857672+aplatkouski@users.noreply.github.com> --- doc/build/core/sqlelement.rst | 10 +-- doc/build/glossary.rst | 2 +- lib/sqlalchemy/engine/interfaces.py | 2 +- lib/sqlalchemy/ext/associationproxy.py | 4 +- lib/sqlalchemy/ext/declarative/clsregistry.py | 2 +- lib/sqlalchemy/orm/mapper.py | 5 +- lib/sqlalchemy/orm/query.py | 4 +- lib/sqlalchemy/orm/session.py | 2 +- lib/sqlalchemy/sql/base.py | 8 +-- lib/sqlalchemy/sql/elements.py | 63 ++++++++++--------- lib/sqlalchemy/sql/operators.py | 8 +-- lib/sqlalchemy/sql/schema.py | 2 +- lib/sqlalchemy/sql/selectable.py | 51 +++++++-------- lib/sqlalchemy/sql/sqltypes.py | 4 +- lib/sqlalchemy/sql/traversals.py | 6 +- lib/sqlalchemy/sql/type_api.py | 10 +-- lib/sqlalchemy/testing/profiling.py | 2 +- 17 files changed, 93 insertions(+), 92 deletions(-) diff --git a/doc/build/core/sqlelement.rst b/doc/build/core/sqlelement.rst index b7bb48b95b..46cda7bf0d 100644 --- a/doc/build/core/sqlelement.rst +++ b/doc/build/core/sqlelement.rst @@ -7,12 +7,12 @@ The expression API consists of a series of classes each of which represents a specific lexical element within a SQL string. Composed together into a larger structure, they form a statement construct that may be *compiled* into a string representation that can be passed to a database. -The classes are organized into a -hierarchy that begins at the basemost ClauseElement class. Key subclasses -include ColumnElement, which represents the role of any column-based expression +The classes are organized into a hierarchy that begins at the basemost +:class:`.ClauseElement` class. Key subclasses include :class:`.ColumnElement`, +which represents the role of any column-based expression in a SQL statement, such as in the columns clause, WHERE clause, and ORDER BY -clause, and FromClause, which represents the role of a token that is placed in -the FROM clause of a SELECT statement. +clause, and :class:`.FromClause`, which represents the role of a token that +is placed in the FROM clause of a SELECT statement. .. autofunction:: all_ diff --git a/doc/build/glossary.rst b/doc/build/glossary.rst index b6902262c1..5b656b9c7a 100644 --- a/doc/build/glossary.rst +++ b/doc/build/glossary.rst @@ -206,7 +206,7 @@ Glossary In SQLAlchemy, the "dialect" is a Python object that represents information and methods that allow database operations to proceed on a particular kind of database backend and a particular kind of Python driver (or - :term`DBAPI`) for that database. SQLAlchemy dialects are subclasses + :term:`DBAPI`) for that database. SQLAlchemy dialects are subclasses of the :class:`.Dialect` class. .. seealso:: diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py index 49d9af9661..0be416bccc 100644 --- a/lib/sqlalchemy/engine/interfaces.py +++ b/lib/sqlalchemy/engine/interfaces.py @@ -1013,7 +1013,7 @@ class CreateEnginePlugin(object): what it needs here as well as remove its custom arguments from the :attr:`.URL.query` collection. The URL can be modified in-place in any other way as well. - :param kwargs: The keyword arguments passed to :func`.create_engine`. + :param kwargs: The keyword arguments passed to :func:`.create_engine`. The plugin can read and modify this dictionary in-place, to affect the ultimate arguments used to create the engine. It should remove its custom arguments from the dictionary as well. diff --git a/lib/sqlalchemy/ext/associationproxy.py b/lib/sqlalchemy/ext/associationproxy.py index fc10cb88d9..dd6217664a 100644 --- a/lib/sqlalchemy/ext/associationproxy.py +++ b/lib/sqlalchemy/ext/associationproxy.py @@ -844,8 +844,8 @@ class ObjectAssociationProxyInstance(AssociationProxyInstance): """Produce a proxied 'contains' expression using EXISTS. This expression will be a composed product - using the :meth:`.RelationshipProperty.Comparator.any` - , :meth:`.RelationshipProperty.Comparator.has`, + using the :meth:`.RelationshipProperty.Comparator.any`, + :meth:`.RelationshipProperty.Comparator.has`, and/or :meth:`.RelationshipProperty.Comparator.contains` operators of the underlying proxied attributes. """ diff --git a/lib/sqlalchemy/ext/declarative/clsregistry.py b/lib/sqlalchemy/ext/declarative/clsregistry.py index 20de3c6364..51af6f1b44 100644 --- a/lib/sqlalchemy/ext/declarative/clsregistry.py +++ b/lib/sqlalchemy/ext/declarative/clsregistry.py @@ -132,7 +132,7 @@ class _MultipleClassMarker(object): class _ModuleMarker(object): - """"refers to a module name within + """Refers to a module name within _decl_class_registry. """ diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py index bec6da74d4..c2c49912e1 100644 --- a/lib/sqlalchemy/orm/mapper.py +++ b/lib/sqlalchemy/orm/mapper.py @@ -759,9 +759,8 @@ class Mapper( """The :class:`expression.Selectable` to which this :class:`_orm.Mapper` is mapped. - Typically an instance of :class:`_schema.Table`, :class:`_expression.Join` - , or - :class:`_expression.Alias`. + Typically an instance of :class:`_schema.Table`, + :class:`_expression.Join`, or :class:`_expression.Alias`. The :attr:`_orm.Mapper.persist_selectable` is separate from :attr:`_orm.Mapper.selectable` in that the former represents columns diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py index dc208f7e16..0aa1901e83 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -879,8 +879,8 @@ class Query( the order in which they correspond to the mapped :class:`_schema.Table` object's primary key columns, or if the - :paramref:`_orm.Mapper.primary_key` configuration parameter were used - , in + :paramref:`_orm.Mapper.primary_key` configuration parameter were + used, in the order used for that parameter. For example, if the primary key of a row is represented by the integer digits "5, 10" the call would look like:: diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index eefac2520c..6a40926da8 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -3536,7 +3536,7 @@ class sessionmaker(_SessionClassMethods): sess = Session() - .. seealso: + .. seealso:: :ref:`session_getting` - introductory text on creating sessions using :class:`.sessionmaker`. diff --git a/lib/sqlalchemy/sql/base.py b/lib/sqlalchemy/sql/base.py index 5f2ce8f14f..7a57be3fd3 100644 --- a/lib/sqlalchemy/sql/base.py +++ b/lib/sqlalchemy/sql/base.py @@ -874,7 +874,7 @@ class ColumnCollection(object): Column('x', Integer(), table=None) >>> cc['y'] - :class`.ColumnCollection` also indexes the columns in order and allows + :class:`.ColumnCollection` also indexes the columns in order and allows them to be accessible by their integer position:: >>> cc[0] @@ -892,8 +892,8 @@ class ColumnCollection(object): [Column('x', Integer(), table=None), Column('y', Integer(), table=None)] - The base :class:`_expression.ColumnCollection` object can store duplicates - , which can + The base :class:`_expression.ColumnCollection` object can store + duplicates, which can mean either two columns with the same key, in which case the column returned by key access is **arbitrary**:: @@ -1073,7 +1073,7 @@ class ColumnCollection(object): ancestor column. :param column: the target :class:`_expression.ColumnElement` - to be matched + to be matched. :param require_embedded: only return corresponding columns for the given :class:`_expression.ColumnElement`, if the given diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py index 60c816ee6d..5e071f3ea1 100644 --- a/lib/sqlalchemy/sql/elements.py +++ b/lib/sqlalchemy/sql/elements.py @@ -354,14 +354,14 @@ 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 ``ClauseElement`` to the given ``ClauseElement``. Subclasses should override the default behavior, which is a straight identity comparison. - \**kw are arguments consumed by subclass compare() methods and - may be used to modify the criteria for comparison. - (see :class:`_expression.ColumnElement`) + \**kw are arguments consumed by subclass ``compare()`` methods and + may be used to modify the criteria for comparison + (see :class:`_expression.ColumnElement`). """ return traversals.compare(self, other, **kw) @@ -732,12 +732,12 @@ class ColumnElement( """ key = None - """the 'key' that in some circumstances refers to this object in a + """The 'key' that in some circumstances refers to this object in a Python namespace. This typically refers to the "key" of the column as present in the - ``.c`` collection of a selectable, e.g. sometable.c["somekey"] would - return a Column with a .key of "somekey". + ``.c`` collection of a selectable, e.g. ``sometable.c["somekey"]`` would + return a :class:`_schema.Column` with a ``.key`` of "somekey". """ @@ -970,7 +970,7 @@ class ColumnElement( This is a shortcut to the :func:`_expression.label` function. - if 'name' is None, an anonymous label name will be generated. + If 'name' is ``None``, an anonymous label name will be generated. """ return Label(name, self, self.type) @@ -989,14 +989,14 @@ class ColumnElement( @util.memoized_property def anon_label(self): - """provides a constant 'anonymous label' for this ColumnElement. + """Provides a constant 'anonymous label' for this ColumnElement. This is a label() expression which will be named at compile time. - The same label() is returned each time anon_label is called so - that expressions can reference anon_label multiple times, producing - the same label name at compile time. + The same label() is returned each time ``anon_label`` is called so + that expressions can reference ``anon_label`` multiple times, + producing the same label name at compile time. - the compiler uses this function automatically at compile time + The compiler uses this function automatically at compile time for expressions that are known to be 'unnamed' like binary expressions and function calls. @@ -1689,7 +1689,7 @@ class TextClause( be eligible for autocommit if no transaction is in progress. :param text: - the text of the SQL statement to be created. use ``:`` + the text of the SQL statement to be created. Use ``:`` to specify bind parameters; they will be compiled to their engine-specific format. @@ -1952,7 +1952,7 @@ class TextClause( :param \**types: A mapping of string names to :class:`.TypeEngine` type objects indicating the datatypes to use for names that are - SELECTed from the textual string. Prefer to use the ``\*cols`` + SELECTed from the textual string. Prefer to use the ``*cols`` argument as it also indicates positional ordering. """ @@ -2394,9 +2394,11 @@ class BooleanClauseList(ClauseList, ColumnElement): times against a statement, which will have the effect of each clause being combined using :func:`.and_`:: - stmt = select([users_table]).\ - where(users_table.c.name == 'wendy').\ - where(users_table.c.enrolled == True) + stmt = ( + select([users_table]). + where(users_table.c.name == 'wendy'). + where(users_table.c.enrolled == True) + ) The :func:`.and_` construct must be given at least one positional argument in order to be valid; a :func:`.and_` construct with no @@ -2799,7 +2801,7 @@ def literal_column(text, type_=None): :param type\_: an optional :class:`~sqlalchemy.types.TypeEngine` object which will provide result-set translation and additional expression semantics for - this column. If left as None the type will be NullType. + this column. If left as ``None`` the type will be :class:`.NullType`. .. seealso:: @@ -3166,8 +3168,8 @@ class UnaryExpression(ColumnElement): from sqlalchemy import desc, nullsfirst - stmt = select([users_table]).\ - order_by(nullsfirst(desc(users_table.c.name))) + stmt = select([users_table]).order_by( + nullsfirst(desc(users_table.c.name))) The SQL expression from the above would resemble:: @@ -3179,9 +3181,8 @@ class UnaryExpression(ColumnElement): rather than as its standalone function version, as in:: - stmt = (select([users_table]). - order_by(users_table.c.name.desc().nullsfirst()) - ) + stmt = select([users_table]).order_by( + users_table.c.name.desc().nullsfirst()) .. seealso:: @@ -3211,8 +3212,8 @@ class UnaryExpression(ColumnElement): from sqlalchemy import desc, nullslast - stmt = select([users_table]).\ - order_by(nullslast(desc(users_table.c.name))) + stmt = select([users_table]).order_by( + nullslast(desc(users_table.c.name))) The SQL expression from the above would resemble:: @@ -3224,8 +3225,8 @@ class UnaryExpression(ColumnElement): rather than as its standalone function version, as in:: - stmt = select([users_table]).\ - order_by(users_table.c.name.desc().nullslast()) + stmt = select([users_table]).order_by( + users_table.c.name.desc().nullslast()) .. seealso:: @@ -3778,7 +3779,7 @@ class Over(ColumnElement): ROW_NUMBER() OVER(ORDER BY some_column RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW) - A value of None indicates "unbounded", a + A value of ``None`` indicates "unbounded", a value of zero indicates "current row", and negative / positive integers indicate "preceding" and "following": @@ -3810,8 +3811,8 @@ class Over(ColumnElement): of such, that will be used as the ORDER BY clause of the OVER construct. :param range\_: optional range clause for the window. This is a - tuple value which can contain integer values or None, and will - render a RANGE BETWEEN PRECEDING / FOLLOWING clause + tuple value which can contain integer values or ``None``, + and will render a RANGE BETWEEN PRECEDING / FOLLOWING clause. .. versionadded:: 1.1 diff --git a/lib/sqlalchemy/sql/operators.py b/lib/sqlalchemy/sql/operators.py index 1bd63f285b..85db883453 100644 --- a/lib/sqlalchemy/sql/operators.py +++ b/lib/sqlalchemy/sql/operators.py @@ -124,7 +124,7 @@ class Operators(object): def op( self, opstring, precedence=0, is_comparison=False, return_type=None ): - """produce a generic operator function. + """Produce a generic operator function. e.g.:: @@ -721,7 +721,7 @@ class ColumnOperators(Operators): somecolumn LIKE :param || '%' ESCAPE '/' - With the value of :param as ``"foo/%bar"``. + With the value of ``:param`` as ``"foo/%bar"``. .. versionadded:: 1.2 @@ -809,7 +809,7 @@ class ColumnOperators(Operators): somecolumn LIKE '%' || :param ESCAPE '/' - With the value of :param as ``"foo/%bar"``. + With the value of ``:param`` as ``"foo/%bar"``. .. versionadded:: 1.2 @@ -897,7 +897,7 @@ class ColumnOperators(Operators): somecolumn LIKE '%' || :param || '%' ESCAPE '/' - With the value of :param as ``"foo/%bar"``. + With the value of ``:param`` as ``"foo/%bar"``. .. versionadded:: 1.2 diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py index 29ca81d26d..e35d04faa8 100644 --- a/lib/sqlalchemy/sql/schema.py +++ b/lib/sqlalchemy/sql/schema.py @@ -2203,7 +2203,7 @@ class ColumnDefault(DefaultGenerator): """ def __init__(self, arg, **kwargs): - """"Construct a new :class:`.ColumnDefault`. + """Construct a new :class:`.ColumnDefault`. :param arg: argument representing the default value. diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py index c032b2b7ed..801f2b67c8 100644 --- a/lib/sqlalchemy/sql/selectable.py +++ b/lib/sqlalchemy/sql/selectable.py @@ -143,7 +143,7 @@ class ReturnsRows(roles.ReturnsRowsRole, ClauseElement): .. versionadded:: 1.4 - .. seealso: + .. seealso:: :attr:`_expression.FromClause.exported_columns` @@ -208,7 +208,7 @@ class Selectable(ReturnsRows): column. :param column: the target :class:`_expression.ColumnElement` - to be matched + to be matched. :param require_embedded: only return corresponding columns for the given :class:`_expression.ColumnElement`, if the given @@ -656,7 +656,7 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): .. versionadded:: 1.4 - .. seealso: + .. seealso:: :attr:`expression.Selectable.exported_columns` @@ -2048,8 +2048,8 @@ class TableClause(roles.DMLTableRole, Immutable, FromClause): def __init__(self, name, *columns, **kw): """Produce a new :class:`_expression.TableClause`. - The object returned is an instance of :class:`_expression.TableClause` - , which + The object returned is an instance of + :class:`_expression.TableClause`, which represents the "syntactical" portion of the schema-level :class:`_schema.Table` object. It may be used to construct lightweight table constructs. @@ -2398,7 +2398,7 @@ class SelectBase( .. versionadded:: 1.4 - .. seealso: + .. seealso:: :attr:`expression.Selectable.exported_columns` @@ -3111,12 +3111,12 @@ class CompoundSelect(HasCompileState, GenerativeSelect): A similar :func:`union()` method is available on all :class:`_expression.FromClause` subclasses. - \*selects + :param \*selects: a list of :class:`_expression.Select` instances. - \**kwargs - available keyword arguments are the same as those of - :func:`select`. + :param \**kwargs: + available keyword arguments are the same as those of + :func:`select`. """ return CompoundSelect(CompoundSelect.UNION, *selects, **kwargs) @@ -3131,10 +3131,10 @@ class CompoundSelect(HasCompileState, GenerativeSelect): A similar :func:`union_all()` method is available on all :class:`_expression.FromClause` subclasses. - \*selects + :param \*selects: a list of :class:`_expression.Select` instances. - \**kwargs + :param \**kwargs: available keyword arguments are the same as those of :func:`select`. @@ -3148,10 +3148,10 @@ class CompoundSelect(HasCompileState, GenerativeSelect): The returned object is an instance of :class:`_expression.CompoundSelect`. - \*selects + :param \*selects: a list of :class:`_expression.Select` instances. - \**kwargs + :param \**kwargs: available keyword arguments are the same as those of :func:`select`. @@ -3165,10 +3165,10 @@ class CompoundSelect(HasCompileState, GenerativeSelect): The returned object is an instance of :class:`_expression.CompoundSelect`. - \*selects + :param \*selects: a list of :class:`_expression.Select` instances. - \**kwargs + :param \**kwargs: available keyword arguments are the same as those of :func:`select`. @@ -3182,10 +3182,10 @@ class CompoundSelect(HasCompileState, GenerativeSelect): The returned object is an instance of :class:`_expression.CompoundSelect`. - \*selects + :param \*selects: a list of :class:`_expression.Select` instances. - \**kwargs + :param \**kwargs: available keyword arguments are the same as those of :func:`select`. @@ -3199,10 +3199,10 @@ class CompoundSelect(HasCompileState, GenerativeSelect): The returned object is an instance of :class:`_expression.CompoundSelect`. - \*selects + :param \*selects: a list of :class:`_expression.Select` instances. - \**kwargs + :param \**kwargs: available keyword arguments are the same as those of :func:`select`. @@ -4255,7 +4255,7 @@ class Select( @util.preload_module("sqlalchemy.sql.util") def reduce_columns(self, only_synonyms=True): - """Return a new :func`.select` construct with redundantly + """Return a new :func:`.select` construct with redundantly named, equivalently-valued columns removed from the columns clause. "Redundant" here means two columns where one refers to the @@ -4815,14 +4815,15 @@ class Select( return CompoundSelect._create_union_all(self, other, **kwargs) def except_(self, other, **kwargs): - """return a SQL EXCEPT of this select() construct against the given - selectable.""" + """Return a SQL ``EXCEPT`` of this select() construct against + the given selectable. + """ return CompoundSelect._create_except(self, other, **kwargs) def except_all(self, other, **kwargs): - """return a SQL EXCEPT ALL of this select() construct against the - given selectable. + """Return a SQL ``EXCEPT ALL`` of this select() construct against + the given selectable. """ return CompoundSelect._create_except_all(self, other, **kwargs) diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py index 9cd9d50582..a143a2241c 100644 --- a/lib/sqlalchemy/sql/sqltypes.py +++ b/lib/sqlalchemy/sql/sqltypes.py @@ -2237,8 +2237,8 @@ class JSON(Indexable, TypeEngine): ) While it is possible to use :attr:`_types.JSON.NULL` in this context, the - :attr:`_types.JSON.NULL` value will be returned as the value of the column - , + :attr:`_types.JSON.NULL` value will be returned as the value of the + column, which in the context of the ORM or other repurposing of the default value, may not be desirable. Using a SQL expression means the value will be re-fetched from the database within the context of retrieving diff --git a/lib/sqlalchemy/sql/traversals.py b/lib/sqlalchemy/sql/traversals.py index ed0bfa27a2..8d01b7ff7d 100644 --- a/lib/sqlalchemy/sql/traversals.py +++ b/lib/sqlalchemy/sql/traversals.py @@ -287,7 +287,7 @@ class CacheKey(namedtuple("CacheKey", ["key", "bindparams"])): return None def to_offline_string(self, statement_cache, statement, parameters): - """generate an "offline string" form of this :class:`.CacheKey` + """Generate an "offline string" form of this :class:`.CacheKey` The "offline string" is basically the string SQL for the statement plus a repr of the bound parameter values in series. @@ -295,8 +295,8 @@ class CacheKey(namedtuple("CacheKey", ["key", "bindparams"])): identities in order to work as a cache key, the "offline" version is suitable for a cache that will work for other processes as well. - The given "statement_cache" is a dictionary-like object where the - string form of the statement itself will be cached. this dictionary + The given ``statement_cache`` is a dictionary-like object where the + string form of the statement itself will be cached. This dictionary should be in a longer lived scope in order to reduce the time spent stringifying statements. diff --git a/lib/sqlalchemy/sql/type_api.py b/lib/sqlalchemy/sql/type_api.py index fe3634badd..dbd5fd2001 100644 --- a/lib/sqlalchemy/sql/type_api.py +++ b/lib/sqlalchemy/sql/type_api.py @@ -337,7 +337,7 @@ class TypeEngine(Traversible): ) def bind_expression(self, bindvalue): - """"Given a bind value (i.e. a :class:`.BindParameter` instance), + """Given a bind value (i.e. a :class:`.BindParameter` instance), return a SQL expression in its place. This is typically a SQL function that wraps the existing bound @@ -809,10 +809,10 @@ class TypeDecorator(SchemaEventTarget, TypeEngine): def copy(self, **kw): return MyType(self.impl.length) - The class-level "impl" attribute is required, and can reference any - TypeEngine class. Alternatively, the load_dialect_impl() method - can be used to provide different type classes based on the dialect - given; in this case, the "impl" variable can reference + The class-level ``impl`` attribute is required, and can reference any + :class:`.TypeEngine` class. Alternatively, the :meth:`load_dialect_impl` + method can be used to provide different type classes based on the dialect + given; in this case, the ``impl`` variable can reference ``TypeEngine`` as a placeholder. Types that receive a Python type that isn't similar to the ultimate type diff --git a/lib/sqlalchemy/testing/profiling.py b/lib/sqlalchemy/testing/profiling.py index 16215dcd54..c50ce1e153 100644 --- a/lib/sqlalchemy/testing/profiling.py +++ b/lib/sqlalchemy/testing/profiling.py @@ -57,7 +57,7 @@ def _start_current_test(id_): class ProfileStatsFile(object): - """"Store per-platform/fn profiling results in a file. + """Store per-platform/fn profiling results in a file. There was no json module available when this was written, but now the file format which is very deterministically line oriented is kind of -- 2.47.3