From: aplatkouski <5857672+aplatkouski@users.noreply.github.com> Date: Fri, 12 Jun 2020 18:12:12 +0000 (+0300) Subject: Fix typos in 'Schema Definition Language' X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=da6458d9f7e3524b4d1b47983817b495f67c5036;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git Fix typos in 'Schema Definition Language' Signed-off-by: aplatkouski <5857672+aplatkouski@users.noreply.github.com> --- diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst index 6c100282ee..7869e61223 100644 --- a/doc/build/core/connections.rst +++ b/doc/build/core/connections.rst @@ -23,7 +23,7 @@ the :func:`_sa.create_engine` call:: engine = create_engine('mysql://scott:tiger@localhost/test') -The typical usage of :func:`_sa.create_engine()` is once per particular database +The typical usage of :func:`_sa.create_engine` is once per particular database URL, held globally for the lifetime of a single application process. A single :class:`_engine.Engine` manages many individual :term:`DBAPI` connections on behalf of the process and is intended to be called upon in a concurrent fashion. The diff --git a/doc/build/core/defaults.rst b/doc/build/core/defaults.rst index 6898324b66..3d6124b438 100644 --- a/doc/build/core/defaults.rst +++ b/doc/build/core/defaults.rst @@ -152,8 +152,8 @@ otherwise not provided, and the value will be that of whatever value is present in the execution for the ``counter`` column, plus the number 12. For a single statement that is being executed using "executemany" style, e.g. -with multiple parameter sets passed to :meth:`_engine.Connection.execute`, the user- -defined function is called once for each set of parameters. For the use case of +with multiple parameter sets passed to :meth:`_engine.Connection.execute`, the +user-defined function is called once for each set of parameters. For the use case of a multi-valued :class:`_expression.Insert` construct (e.g. with more than one VALUES clause set up via the :meth:`_expression.Insert.values` method), the user-defined function is also called once for each set of parameters. @@ -242,8 +242,8 @@ all Python and SQL expressions which were pre-executed, are present in the :meth:`_engine.CursorResult.last_updated_params` collections on :class:`~sqlalchemy.engine.CursorResult`. The :attr:`_engine.CursorResult.inserted_primary_key` collection contains a list of primary -key values for the row inserted (a list so that single-column and composite- -column primary keys are represented in the same format). +key values for the row inserted (a list so that single-column and +composite-column primary keys are represented in the same format). .. _server_defaults: @@ -371,7 +371,7 @@ Associating a Sequence on a SERIAL column PostgreSQL's SERIAL datatype is an auto-incrementing type that implies the implicit creation of a PostgreSQL sequence when CREATE TABLE is emitted. If a :class:`_schema.Column` specifies an explicit :class:`.Sequence` object -which also specifies a true value for the :paramref:`.Sequence.optional` +which also specifies a ``True`` value for the :paramref:`.Sequence.optional` boolean flag, the :class:`.Sequence` will not take effect under PostgreSQL, and the SERIAL datatype will proceed normally. Instead, the :class:`.Sequence` will only take effect when used against other sequence-supporting diff --git a/doc/build/core/tutorial.rst b/doc/build/core/tutorial.rst index e84ef965cd..5c30177540 100644 --- a/doc/build/core/tutorial.rst +++ b/doc/build/core/tutorial.rst @@ -956,8 +956,8 @@ Fetching the ``email_address`` column would be:: >>> row._mapping[addresses.c.email_address] 'jack@yahoo.com' -If on the other hand we used a string column key, the usual rules of name- -based matching still apply, and we'd get an ambiguous column error for +If on the other hand we used a string column key, the usual rules of +name-based matching still apply, and we'd get an ambiguous column error for the ``id`` value:: >>> row._mapping["id"] diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py index 0be416bccc..76d6b889e1 100644 --- a/lib/sqlalchemy/engine/interfaces.py +++ b/lib/sqlalchemy/engine/interfaces.py @@ -377,13 +377,13 @@ class Dialect(object): Given a string `table_name` and an optional string `schema`, return check constraint information as a list of dicts with these keys: - name + * ``name`` - the check constraint's name - sqltext + * ``sqltext`` - the check constraint's SQL expression - \**kw + * ``**kw`` - other options passed to the dialect's get_check_constraints() method. @@ -415,7 +415,7 @@ class Dialect(object): """convert the given name to lowercase if it is detected as case insensitive. - this method is only used if the dialect defines + This method is only used if the dialect defines requires_name_normalize=True. """ @@ -425,7 +425,7 @@ class Dialect(object): """convert the given name to a case insensitive identifier for the backend if it is an all-lowercase name. - this method is only used if the dialect defines + This method is only used if the dialect defines requires_name_normalize=True. """ diff --git a/lib/sqlalchemy/engine/reflection.py b/lib/sqlalchemy/engine/reflection.py index 564a82c5a8..7fc7df981c 100644 --- a/lib/sqlalchemy/engine/reflection.py +++ b/lib/sqlalchemy/engine/reflection.py @@ -304,7 +304,7 @@ class Inspector(object): :meth:`_reflection.Inspector.get_table_names` :func:`.sort_tables_and_constraints` - similar method which works - with an already-given :class:`_schema.MetaData`. + with an already-given :class:`_schema.MetaData`. """ @@ -339,7 +339,7 @@ class Inspector(object): ] + [(None, list(remaining_fkcs))] def get_temp_table_names(self): - """return a list of temporary table names for the current bind. + """Return a list of temporary table names for the current bind. This method is unsupported by most dialects; currently only SQLite implements it. @@ -354,7 +354,7 @@ class Inspector(object): ) def get_temp_view_names(self): - """return a list of temporary view names for the current bind. + """Return a list of temporary view names for the current bind. This method is unsupported by most dialects; currently only SQLite implements it. @@ -480,10 +480,10 @@ class Inspector(object): Given a string `table_name`, and an optional string `schema`, return primary key information as a dictionary with these keys: - constrained_columns + * ``constrained_columns`` - a list of column names that make up the primary key - name + * ``name`` - optional name of the primary key constraint. :param table_name: string name of the table. For special quoting, @@ -505,20 +505,20 @@ class Inspector(object): Given a string `table_name`, and an optional string `schema`, return foreign key information as a list of dicts with these keys: - constrained_columns + * ``constrained_columns`` - a list of column names that make up the foreign key - referred_schema + * ``referred_schema`` - the name of the referred schema - referred_table + * ``referred_table`` - the name of the referred table - referred_columns + * ``referred_columns`` - a list of column names in the referred table that correspond to constrained_columns - name + * ``name`` - optional name of the foreign key constraint. :param table_name: string name of the table. For special quoting, @@ -541,22 +541,22 @@ class Inspector(object): Given a string `table_name` and an optional string `schema`, return index information as a list of dicts with these keys: - name + * ``name`` - the index's name - column_names + * ``column_names`` - list of column names in order - unique + * ``unique`` - boolean - column_sorting + * ``column_sorting`` - optional dict mapping column names to tuple of sort keywords, which may include ``asc``, ``desc``, ``nullsfirst``, ``nullslast``. .. versionadded:: 1.3.5 - dialect_options + * ``dialect_options`` - dict of dialect-specific index options. May not be present for all dialects. @@ -582,10 +582,10 @@ class Inspector(object): Given a string `table_name` and an optional string `schema`, return unique constraint information as a list of dicts with these keys: - name + * ``name`` - the unique constraint's name - column_names + * ``column_names`` - list of column names in order :param table_name: string name of the table. For special quoting, @@ -608,7 +608,7 @@ class Inspector(object): Given a string ``table_name`` and an optional string ``schema``, return table comment information as a dictionary with these keys: - text + * ``text`` - text of the comment. Raises ``NotImplementedError`` for a dialect that does not support @@ -629,13 +629,13 @@ class Inspector(object): Given a string `table_name` and an optional string `schema`, return check constraint information as a list of dicts with these keys: - name + * ``name`` - the check constraint's name - sqltext + * ``sqltext`` - the check constraint's SQL expression - dialect_options + * ``dialect_options`` - may or may not be present; a dictionary with additional dialect-specific options for this CHECK constraint @@ -676,8 +676,8 @@ class Inspector(object): resolve_fks=True, _extend_on=None, ): - """Given a Table object, load its internal constructs based on - introspection. + """Given a :class:`_schema.Table` object, load its internal + constructs based on introspection. This is the underlying method used by most dialects to produce table reflection. Direct usage is like:: diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index 2058cf718a..2ffab67320 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -1308,7 +1308,7 @@ class Session(_SessionClassMethods): resolved through any of the optional keyword arguments. This ultimately makes usage of the :meth:`.get_bind` method for resolution. - :param bind_arguments: dictionary of bind arguments. May include + :param bind_arguments: dictionary of bind arguments. May include "mapper", "bind", "clause", other custom arguments that are passed to :meth:`.Session.get_bind`. diff --git a/lib/sqlalchemy/sql/ddl.py b/lib/sqlalchemy/sql/ddl.py index d3730b1245..17e3be2dac 100644 --- a/lib/sqlalchemy/sql/ddl.py +++ b/lib/sqlalchemy/sql/ddl.py @@ -93,10 +93,10 @@ class DDLElement(roles.DDLRole, Executable, _DDLCompiles): ``.bind`` property. :param target: - Optional, defaults to None. The target SchemaItem for the - execute call. Will be passed to the ``on`` callable if any, - and may also provide string expansion data for the - statement. See ``execute_at`` for more information. + Optional, defaults to None. The target :class:`_schema.SchemaItem` + for the execute call. Will be passed to the ``on`` callable if any, + and may also provide string expansion data for the statement. + See ``execute_at`` for more information. """ @@ -167,7 +167,7 @@ class DDLElement(roles.DDLRole, Executable, _DDLCompiles): set during the call to ``create()``, ``create_all()``, ``drop()``, ``drop_all()``. - If the callable returns a true value, the DDL statement will be + If the callable returns a True value, the DDL statement will be executed. :param state: any value which will be passed to the callable\_ @@ -955,8 +955,8 @@ class SchemaDropper(DDLBase): def sort_tables( tables, skip_fn=None, extra_dependencies=None, ): - """sort a collection of :class:`_schema.Table` objects based on dependency - . + """Sort a collection of :class:`_schema.Table` objects based on + dependency. This is a dependency-ordered sort which will emit :class:`_schema.Table` objects such that they will follow their dependent :class:`_schema.Table` @@ -1040,7 +1040,7 @@ def sort_tables( def sort_tables_and_constraints( tables, filter_fn=None, extra_dependencies=None, _warn_for_cycles=False ): - """sort a collection of :class:`_schema.Table` / + """Sort a collection of :class:`_schema.Table` / :class:`_schema.ForeignKeyConstraint` objects. diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py index abd4469a1f..402895dc78 100644 --- a/lib/sqlalchemy/sql/elements.py +++ b/lib/sqlalchemy/sql/elements.py @@ -2370,7 +2370,7 @@ class BooleanClauseList(ClauseList, ColumnElement): @classmethod def and_(cls, *clauses): - """Produce a conjunction of expressions joined by ``AND``. + r"""Produce a conjunction of expressions joined by ``AND``. E.g.:: @@ -2399,11 +2399,9 @@ 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 diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py index e35d04faa8..f51a73ca6b 100644 --- a/lib/sqlalchemy/sql/schema.py +++ b/lib/sqlalchemy/sql/schema.py @@ -327,7 +327,8 @@ class Table(DialectKWArgs, SchemaItem, TableClause): :param implicit_returning: True by default - indicates that RETURNING can be used by default to fetch newly inserted primary key values, for backends which support this. Note that - create_engine() also provides an implicit_returning flag. + :func:`_sa.create_engine` also provides an ``implicit_returning`` + flag. :param include_columns: A list of strings indicating a subset of columns to be loaded via the ``autoload`` operation; table columns who @@ -1250,13 +1251,13 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause): :ref:`server_defaults` - complete discussion of server side defaults - :param server_onupdate: A :class:`.FetchedValue` instance - representing a database-side default generation function, - such as a trigger. This - indicates to SQLAlchemy that a newly generated value will be - available after updates. This construct does not actually - implement any kind of generation function within the database, - which instead must be specified separately. + :param server_onupdate: A :class:`.FetchedValue` instance + representing a database-side default generation function, + such as a trigger. This + indicates to SQLAlchemy that a newly generated value will be + available after updates. This construct does not actually + implement any kind of generation function within the database, + which instead must be specified separately. .. seealso:: @@ -1547,7 +1548,7 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause): def copy(self, **kw): """Create a copy of this ``Column``, uninitialized. - This is used in ``Table.tometadata``. + This is used in :meth:`_schema.Table.tometadata`. """ @@ -2332,7 +2333,7 @@ class IdentityOptions(object): or minvalue has been reached. :param cache: optional integer value; number of future values in the sequence which are calculated in advance. - :param order: optional boolean value; if true, renders the + :param order: optional boolean value; if ``True``, renders the ORDER keyword. :param data_type: The type to be returned by the sequence. @@ -2482,7 +2483,7 @@ class Sequence(IdentityOptions, roles.StatementRole, DefaultGenerator): .. versionadded:: 1.1.12 - :param order: optional boolean value; if true, renders the + :param order: optional boolean value; if ``True``, renders the ORDER keyword, understood by Oracle, indicating the sequence is definitively ordered. May be necessary to provide deterministic ordering using Oracle RAC. @@ -3304,7 +3305,7 @@ class ForeignKeyConstraint(ColumnCollectionConstraint): This list is either the original string arguments sent to the constructor of the :class:`_schema.ForeignKeyConstraint`, or if the constraint has been initialized with :class:`_schema.Column` - objects, is the string .key of each element. + objects, is the string ``.key`` of each element. .. versionadded:: 1.0.0 @@ -3835,12 +3836,14 @@ class MetaData(SchemaItem): :param bind: An Engine or Connection to bind to. May also be a string or URL - instance, these are passed to create_engine() and this MetaData will + instance, these are passed to :func:`_sa.create_engine` and + this :class:`_schema.MetaData` will be bound to the resulting engine. :param reflect: Optional, automatically load all tables from the bound database. - Defaults to False. ``bind`` is required when this option is set. + Defaults to False. :paramref:`_schema.MetaData.bind` is required + when this option is set. :param schema: The default schema to use for the :class:`_schema.Table`, @@ -4506,15 +4509,15 @@ class Computed(FetchedValue, SchemaItem): Optional, controls how this column should be persisted by the database. Possible values are: - * None, the default, it will use the default persistence defined - by the database. - * True, will render ``GENERATED ALWAYS AS ... STORED``, or the - equivalent for the target database if supported - * False, will render ``GENERATED ALWAYS AS ... VIRTUAL``, or the + * ``None``, the default, it will use the default persistence + defined by the database. + * ``True``, will render ``GENERATED ALWAYS AS ... STORED``, or the equivalent for the target database if supported. + * ``False``, will render ``GENERATED ALWAYS AS ... VIRTUAL``, or + the equivalent for the target database if supported. Specifying ``True`` or ``False`` may raise an error when the DDL - is emitted to the target database if the databse does not support + is emitted to the target database if the database does not support that persistence option. Leaving this parameter at its default of ``None`` is guaranteed to succeed for all databases that support ``GENERATED ALWAYS AS``. diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py index 62736f30a1..bf6f20436e 100644 --- a/lib/sqlalchemy/sql/selectable.py +++ b/lib/sqlalchemy/sql/selectable.py @@ -224,7 +224,7 @@ class Selectable(ReturnsRows): :attr:`_expression.Selectable.exported_columns` - the :class:`_expression.ColumnCollection` - that is used for the operation + that is used for the operation. :meth:`_expression.ColumnCollection.corresponding_column` - implementation @@ -704,18 +704,20 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): @util.memoized_property def primary_key(self): - """Return the collection of Column objects which comprise the - primary key of this FromClause.""" + """Return the collection of :class:`_schema.Column` objects + which comprise the primary key of this FromClause. + """ self._init_collections() self._populate_column_collection() return self.primary_key @util.memoized_property def foreign_keys(self): - """Return the collection of ForeignKey objects which this - FromClause references.""" + """Return the collection of :class:`_schema.ForeignKey` objects + which this FromClause references. + """ self._init_collections() self._populate_column_collection() return self.foreign_keys