diff options
| author | mike bayer <mike_mp@zzzcomputing.com> | 2020-06-26 15:30:57 +0000 |
|---|---|---|
| committer | Gerrit Code Review <gerrit@bbpush.zzzcomputing.com> | 2020-06-26 15:30:57 +0000 |
| commit | ba047cc8cab22541e88ce91936162d6e8164991a (patch) | |
| tree | 6ab348228f67ebcfd478bf598b347484e8a811cd | |
| parent | 2d9387354f11da322c516412eb5dfe937163c90b (diff) | |
| parent | 2a1a9f5f5a9723f757439657d2bdf224baed8748 (diff) | |
| download | sqlalchemy-ba047cc8cab22541e88ce91936162d6e8164991a.tar.gz | |
Merge "Fix a wide variety of typos and broken links"
95 files changed, 643 insertions, 617 deletions
diff --git a/doc/build/changelog/changelog_08.rst b/doc/build/changelog/changelog_08.rst index fbd7b837f..d0b49a050 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 f4e012c23..7058a2ae2 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/changelog_11.rst b/doc/build/changelog/changelog_11.rst index d8234488a..013efce38 100644 --- a/doc/build/changelog/changelog_11.rst +++ b/doc/build/changelog/changelog_11.rst @@ -163,7 +163,7 @@ :version: 1.1.15 :released: November 3, 2017 - .. change: + .. change:: :tags: bug, sqlite :tickets: 4099 :versions: 1.2.0b3 @@ -284,7 +284,7 @@ for single inheritance discriminator criteria inappropriately re-applying the criteria to the outer query. - .. change: + .. change:: :tags: bug, mysql :tickets: 4096 :versions: 1.2.0b3 @@ -293,7 +293,7 @@ in the MariaDB 10.2 series due to a syntax change, where the function is now represented as ``current_timestamp()``. - .. change: + .. change:: :tags: bug, mysql :tickets: 4098 :versions: 1.2.0b3 diff --git a/doc/build/changelog/changelog_12.rst b/doc/build/changelog/changelog_12.rst index 8c138bde8..38f6fd5fa 100644 --- a/doc/build/changelog/changelog_12.rst +++ b/doc/build/changelog/changelog_12.rst @@ -740,7 +740,7 @@ Fixed bug in cache key generation for baked queries which could cause a too-short cache key to be generated for the case of eager loads across subclasses. This could in turn cause the eagerload query to be cached in - place of a non-eagerload query, or vice versa, for a polymorhic "selectin" + place of a non-eagerload query, or vice versa, for a polymorphic "selectin" load, or possibly for lazy loads or selectin loads as well. .. change:: diff --git a/doc/build/changelog/changelog_13.rst b/doc/build/changelog/changelog_13.rst index bf0190ded..1118e043a 100644 --- a/doc/build/changelog/changelog_13.rst +++ b/doc/build/changelog/changelog_13.rst @@ -302,7 +302,7 @@ Fixed issue where an :class:`.Index` that is deferred in being associated with a table, such as as when it contains a :class:`.Column` that is not associated with any :class:`.Table` yet, would fail to attach correctly if - it also contained a non table-oriented expession. + it also contained a non table-oriented expression. .. change:: @@ -391,7 +391,7 @@ :tags: bug, mysql :tickets: 5239 - Fixed issue in MySQL dialect when connecting to a psuedo-MySQL database + Fixed issue in MySQL dialect when connecting to a pseudo-MySQL database such as that provided by ProxySQL, the up front check for isolation level when it returns no row will not prevent the dialect from continuing to connect. A warning is emitted that the isolation level could not be diff --git a/doc/build/changelog/migration_13.rst b/doc/build/changelog/migration_13.rst index 6e2913350..e7c35c02c 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_14.rst b/doc/build/changelog/migration_14.rst index 1ee52b86a..c1c69abf8 100644 --- a/doc/build/changelog/migration_14.rst +++ b/doc/build/changelog/migration_14.rst @@ -1687,7 +1687,7 @@ The behavior was first introduced in 0.9 and was part of the larger change of allowing for right nested joins as described at :ref:`feature_joins_09`. However the SQLite workaround produced many regressions in the 2013-2014 period due to its complexity. In 2016, the dialect was modified so that the -join rewriting logic would only occur for SQLite verisons prior to 3.7.16 after +join rewriting logic would only occur for SQLite versions prior to 3.7.16 after bisection was used to identify where SQLite fixed its support for this construct, and no further issues were reported against the behavior (even though some bugs were found internally). It is now anticipated that there @@ -1762,7 +1762,7 @@ on the table. The :class:`.Sequence` prior to version 1.3 was used to control parameters for the IDENTITY column in SQL Server; this usage emitted deprecation warnings -throughout 1.3 and is now removed in 1.4. For control of paramters for an +throughout 1.3 and is now removed in 1.4. For control of parameters for an IDENTITY column, the ``mssql_identity_start`` and ``mssql_identity_increment`` parameters should be used; see the MSSQL dialect documentation linked below. diff --git a/doc/build/changelog/migration_20.rst b/doc/build/changelog/migration_20.rst index 9ba038cf5..2a6ccfcdc 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/changelog/unreleased_14/4449.rst b/doc/build/changelog/unreleased_14/4449.rst index f010bf47f..8b9c4a323 100644 --- a/doc/build/changelog/unreleased_14/4449.rst +++ b/doc/build/changelog/unreleased_14/4449.rst @@ -5,7 +5,7 @@ Additional logic has been added such that certain SQL expressions which typically wrap a single database column will use the name of that column as their "anonymous label" name within a SELECT statement, potentially making - key-based lookups in result tuples more intutive. The primary example of + key-based lookups in result tuples more intuitive. The primary example of this is that of a CAST expression, e.g. ``CAST(table.colname AS INTEGER)``, which will export its default name as "colname", rather than the usual "anon_1" label, that is, ``CAST(table.colname AS INTEGER) AS colname``. diff --git a/doc/build/changelog/unreleased_14/4617_implicit_subquery.rst b/doc/build/changelog/unreleased_14/4617_implicit_subquery.rst index a8bfad138..6bce7e213 100644 --- a/doc/build/changelog/unreleased_14/4617_implicit_subquery.rst +++ b/doc/build/changelog/unreleased_14/4617_implicit_subquery.rst @@ -45,7 +45,7 @@ :class:`_expression.SelectBase` (which is what's produced by :func:`_expression.select`) or :class:`_query.Query` object is passed directly to these functions and others, the ORM is typically coercing them to be a subquery by calling the - :meth:`_expression.SelectBase.alias` method automatically (which is now superceded by + :meth:`_expression.SelectBase.alias` method automatically (which is now superseded by the :meth:`_expression.SelectBase.subquery` method). See the migration notes linked below for further details. diff --git a/doc/build/changelog/unreleased_14/4638.rst b/doc/build/changelog/unreleased_14/4638.rst index 1a799cf91..cc1cd5dd6 100644 --- a/doc/build/changelog/unreleased_14/4638.rst +++ b/doc/build/changelog/unreleased_14/4638.rst @@ -4,6 +4,6 @@ All long-deprecated "extension" classes have been removed, including MapperExtension, SessionExtension, PoolListener, ConnectionProxy, - AttributExtension. These classes have been deprecated since version 0.7 + AttributeExtension. These classes have been deprecated since version 0.7 long superseded by the event listener system. diff --git a/doc/build/changelog/unreleased_14/4643.rst b/doc/build/changelog/unreleased_14/4643.rst index 50ad1edcc..8910c2559 100644 --- a/doc/build/changelog/unreleased_14/4643.rst +++ b/doc/build/changelog/unreleased_14/4643.rst @@ -25,7 +25,7 @@ :tags: change, mysql :tickets: 4643 - Remove deprecated dialect ``mysql+gaerdbms`` that has beed deprecated + Remove deprecated dialect ``mysql+gaerdbms`` that has been deprecated since version 1.0. Use the MySQLdb dialect directly. Remove deprecated parameter ``quoting`` from :class:`.mysql.ENUM` diff --git a/doc/build/changelog/unreleased_14/4662.rst b/doc/build/changelog/unreleased_14/4662.rst index b297c9405..99469e888 100644 --- a/doc/build/changelog/unreleased_14/4662.rst +++ b/doc/build/changelog/unreleased_14/4662.rst @@ -7,7 +7,7 @@ rather than throw a :class:`.FlushError`. The rationale is so that the flush will proceed and raise a :class:`.IntegrityError` instead, in the same way as if the existing object were not present in the identity map - already. This helps with schemes that are uinsg the + already. This helps with schemes that are using the :class:`.IntegrityError` as a means of catching whether or not a row already exists in the table. diff --git a/doc/build/changelog/unreleased_14/4976.rst b/doc/build/changelog/unreleased_14/4976.rst index 2bba59896..520e6b7f0 100644 --- a/doc/build/changelog/unreleased_14/4976.rst +++ b/doc/build/changelog/unreleased_14/4976.rst @@ -5,7 +5,7 @@ Added support for use of the :class:`.Sequence` construct with MariaDB 10.3 and greater, as this is now supported by this database. The construct integrates with the :class:`_schema.Table` object in the same way that it does for - other databases like PostrgreSQL and Oracle; if is present on the integer + other databases like PostgreSQL and Oracle; if is present on the integer primary key "autoincrement" column, it is used to generate defaults. For backwards compatibility, to support a :class:`_schema.Table` that has a :class:`.Sequence` on it to support sequence only databases like Oracle, diff --git a/doc/build/changelog/unreleased_14/5221.rst b/doc/build/changelog/unreleased_14/5221.rst index 883f0029d..869c58942 100644 --- a/doc/build/changelog/unreleased_14/5221.rst +++ b/doc/build/changelog/unreleased_14/5221.rst @@ -6,8 +6,8 @@ :func:`_expression.select` construct such that when a select statement is used in a subquery, repeated column names from different tables are now automatically labeled with a unique label name, without the need to use the - full "apply_labels()" feature that conbines tablename plus column name. - The disambigated labels are available as plain string keys in the .c + full "apply_labels()" feature that combines tablename plus column name. + The disambiguated labels are available as plain string keys in the .c collection of the subquery, and most importantly the feature allows an ORM :func:`_orm.aliased` construct against the combination of an entity and an arbitrary subquery to work correctly, targeting the correct columns despite diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst index 6c100282e..976ac27e1 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 @@ -492,7 +492,7 @@ The introduction on using :meth:`_engine.Connection.execute` made use of the :func:`_expression.text` construct in order to illustrate how textual SQL statements may be invoked. When working with SQLAlchemy, textual SQL is actually more of the exception rather than the norm, as the Core expression language -and the ORM both abstract away the textual representation of SQL. Hpwever, the +and the ORM both abstract away the textual representation of SQL. However, the :func:`_expression.text` construct itself also provides some abstraction of textual SQL in that it normalizes how bound parameters are passed, as well as that it supports datatyping behavior for parameters and result set rows. diff --git a/doc/build/core/constraints.rst b/doc/build/core/constraints.rst index 4abe7709d..3e1eaabad 100644 --- a/doc/build/core/constraints.rst +++ b/doc/build/core/constraints.rst @@ -249,7 +249,7 @@ like the following is generated:: .. versionchanged:: 1.0.0 - The DDL system invoked by :meth:`_schema.MetaData.create_all` and :meth:`_schema.MetaData.drop_all` will now automatically resolve mutually - depdendent foreign keys between tables declared by + dependent foreign keys between tables declared by :class:`_schema.ForeignKeyConstraint` and :class:`_schema.ForeignKey` objects, without the need to explicitly set the :paramref:`_schema.ForeignKeyConstraint.use_alter` flag. diff --git a/doc/build/core/custom_types.rst b/doc/build/core/custom_types.rst index 740d1593f..c9970872d 100644 --- a/doc/build/core/custom_types.rst +++ b/doc/build/core/custom_types.rst @@ -473,7 +473,7 @@ Redefining and Creating New Operators ------------------------------------- SQLAlchemy Core defines a fixed set of expression operators available to all column expressions. -Some of these operations have the effect of overloading Python's built in operators; +Some of these operations have the effect of overloading Python's built-in operators; examples of such operators include :meth:`.ColumnOperators.__eq__` (``table.c.somecolumn == 'foo'``), :meth:`.ColumnOperators.__invert__` (``~table.c.flag``), @@ -484,7 +484,7 @@ explicit methods on column expressions, such as The Core expression constructs in all cases consult the type of the expression in order to determine the behavior of existing operators, as well as to locate additional operators that aren't part of -the built in set. The :class:`.TypeEngine` base class defines a root "comparison" implementation +the built-in set. The :class:`.TypeEngine` base class defines a root "comparison" implementation :class:`.TypeEngine.Comparator`, and many specific types provide their own sub-implementations of this class. User-defined :class:`.TypeEngine.Comparator` implementations can be built directly into a simple subclass of a particular type in order to override or define new operations. Below, diff --git a/doc/build/core/ddl.rst b/doc/build/core/ddl.rst index f38dcf849..30619a419 100644 --- a/doc/build/core/ddl.rst +++ b/doc/build/core/ddl.rst @@ -140,7 +140,7 @@ provide DDL expressions. For example, to produce a ``CREATE TABLE`` statement: .. sourcecode:: python+sql from sqlalchemy.schema import CreateTable - with engine.connecT() as conn: + with engine.connect() as conn: {sql} conn.execute(CreateTable(mytable)) CREATE TABLE mytable ( col1 INTEGER, diff --git a/doc/build/core/defaults.rst b/doc/build/core/defaults.rst index 6898324b6..3d6124b43 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/internals.rst b/doc/build/core/internals.rst index e5a710011..965c03fd9 100644 --- a/doc/build/core/internals.rst +++ b/doc/build/core/internals.rst @@ -5,7 +5,7 @@ Core Internals Some key internal constructs are listed here. -.. currentmodule: sqlalchemy +.. currentmodule:: sqlalchemy .. autoclass:: sqlalchemy.engine.interfaces.Compiled :members: diff --git a/doc/build/core/sqlelement.rst b/doc/build/core/sqlelement.rst index b7bb48b95..46cda7bf0 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/core/tutorial.rst b/doc/build/core/tutorial.rst index 90bdc8d9a..6d9ceb496 100644 --- a/doc/build/core/tutorial.rst +++ b/doc/build/core/tutorial.rst @@ -249,7 +249,7 @@ Executing The interesting part of an :class:`~sqlalchemy.sql.expression.Insert` is executing it. This is performed using a database connection, which is represented by the :class:`_engine.Connection` object. To acquire a -connection, we will use the :meth:`.Engine.connect` method:: +connection, we will use the :meth:`_engine.Engine.connect` method:: >>> conn = engine.connect() >>> conn @@ -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"] @@ -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/core/type_api.rst b/doc/build/core/type_api.rst index 115cbd202..0dd1b4920 100644 --- a/doc/build/core/type_api.rst +++ b/doc/build/core/type_api.rst @@ -20,5 +20,4 @@ Base Type API .. autoclass:: Variant - :members: with_variant, __init__ diff --git a/doc/build/faq/sessions.rst b/doc/build/faq/sessions.rst index 76cabf765..835ce301f 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 f0cb23d42..cec9ebf30 100644 --- a/doc/build/glossary.rst +++ b/doc/build/glossary.rst @@ -12,7 +12,7 @@ Glossary relational relational algebra - An algrebraic system developed by Edgar F. Codd that is used for + An algebraic system developed by Edgar F. Codd that is used for modelling and querying the data stored in relational databases. .. seealso:: @@ -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. @@ -50,6 +50,7 @@ Glossary within the join expression. crud + CRUD An acronym meaning "Create, Update, Delete". The term in SQL refers to the set of operations that create, modify and delete data from the database, also known as :term:`DML`, and typically refers to the ``INSERT``, @@ -131,7 +132,7 @@ Glossary An acronym for **Data Manipulation Language**. DML is the subset of SQL that relational databases use to *modify* the data in tables. DML typically refers to the three widely familiar statements of INSERT, - UPDATE and DELETE, otherwise known as :term:`CRUD` (acronoym for "CReate, + UPDATE and DELETE, otherwise known as :term:`CRUD` (acronym for "CReate, Update, Delete"). .. seealso:: @@ -206,7 +207,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:: @@ -239,7 +240,7 @@ Glossary identity map A mapping between Python objects and their database identities. The identity map is a collection that's associated with an - ORM :term:`session` object, and maintains a single instance + ORM :term:`Session` object, and maintains a single instance of every database object keyed to its identity. The advantage to this pattern is that all operations which occur for a particular database identity are transparently coordinated onto a single @@ -412,7 +413,7 @@ Glossary .. seealso:: - :ref:`pooling_toplevel` + :ref:`pooling_toplevel` DBAPI DBAPI is shorthand for the phrase "Python Database API @@ -461,6 +462,7 @@ Glossary expire expires expiring + Expiring In the SQLAlchemy ORM, refers to when the data in a :term:`persistent` or sometimes :term:`detached` object is erased, such that when the object's attributes are next accessed, a :term:`lazy load` SQL @@ -682,6 +684,7 @@ Glossary isolation isolated + Isolation isolation level The isolation property of the :term:`ACID` model ensures that the concurrent execution @@ -1226,7 +1229,7 @@ Glossary transient This describes one of the major object states which - an object can have within a :term:`session`; a transient object + an object can have within a :term:`Session`; a transient object is a new object that doesn't have any database identity and has not been associated with a session yet. When the object is added to the session, it moves to the @@ -1238,7 +1241,7 @@ Glossary pending This describes one of the major object states which - an object can have within a :term:`session`; a pending object + an object can have within a :term:`Session`; a pending object is a new object that doesn't have any database identity, but has been recently associated with a session. When the session emits a flush and the row is inserted, the @@ -1250,7 +1253,7 @@ Glossary deleted This describes one of the major object states which - an object can have within a :term:`session`; a deleted object + an object can have within a :term:`Session`; a deleted object is an object that was formerly persistent and has had a DELETE statement emitted to the database within a flush to delete its row. The object will move to the :term:`detached` @@ -1265,7 +1268,7 @@ Glossary persistent This describes one of the major object states which - an object can have within a :term:`session`; a persistent object + an object can have within a :term:`Session`; a persistent object is an object that has a database identity (i.e. a primary key) and is currently associated with a session. Any object that was previously :term:`pending` and has now been inserted @@ -1280,7 +1283,7 @@ Glossary detached This describes one of the major object states which - an object can have within a :term:`session`; a detached object + an object can have within a :term:`Session`; a detached object is an object that has a database identity (i.e. a primary key) but is not associated with any session. An object that was previously :term:`persistent` and was removed from its diff --git a/doc/build/orm/backref.rst b/doc/build/orm/backref.rst index 80b395930..65d19eb18 100644 --- a/doc/build/orm/backref.rst +++ b/doc/build/orm/backref.rst @@ -216,7 +216,7 @@ However, if we instead created a new ``Address`` object, and associated the In the above example, it is **not** as intuitive that the ``Address`` would automatically be added to the :class:`.Session`. However, the backref behavior of ``Address.user`` indicates that the ``Address`` object is also appended to -the ``User.addresses`` collection. This in turn intiates a **cascade** +the ``User.addresses`` collection. This in turn initiates a **cascade** operation which indicates that this ``Address`` should be placed into the :class:`.Session` as a :term:`pending` object. @@ -228,7 +228,7 @@ to False, as in:: class User(Base): # ... - addresses = relationship("Address", back_populates="user", cascade_backefs=False) + addresses = relationship("Address", back_populates="user", cascade_backrefs=False) See the example in :ref:`backref_cascade` for further information. diff --git a/doc/build/orm/extensions/baked.rst b/doc/build/orm/extensions/baked.rst index 951f35e6a..72479e64d 100644 --- a/doc/build/orm/extensions/baked.rst +++ b/doc/build/orm/extensions/baked.rst @@ -23,7 +23,7 @@ the caching of the SQL calls and result sets themselves is available in .. deprecated:: 1.4 SQLAlchemy 1.4 and 2.0 feature an all-new direct query caching system that removes the need for the :class:`.BakedQuery` system. Caching is now built in to all Core and ORM queries using the - :paramref:`.create_engine.query_cache_size` parameter. + :paramref:`_engine.create_engine.query_cache_size` parameter. .. versionadded:: 1.0.0 diff --git a/doc/build/orm/extensions/declarative/api.rst b/doc/build/orm/extensions/declarative/api.rst index 9998965c4..be97604d3 100644 --- a/doc/build/orm/extensions/declarative/api.rst +++ b/doc/build/orm/extensions/declarative/api.rst @@ -103,7 +103,7 @@ Above, classes which inherit from ``DefaultBase`` will use one created perhaps within distinct databases:: DefaultBase.metadata.create_all(some_engine) - OtherBase.metadata_create_all(some_other_engine) + OtherBase.metadata.create_all(some_other_engine) ``__table_cls__`` diff --git a/doc/build/orm/extensions/declarative/relationships.rst b/doc/build/orm/extensions/declarative/relationships.rst index d33d44245..ac2671c52 100644 --- a/doc/build/orm/extensions/declarative/relationships.rst +++ b/doc/build/orm/extensions/declarative/relationships.rst @@ -152,8 +152,8 @@ with declarative as with traditional mappings. The traditional way. The :class:`_schema.Table` usually shares the :class:`_schema.MetaData` object used by the declarative base:: - keywords = Table( - 'keywords', Base.metadata, + keyword_author = Table( + 'keyword_author', Base.metadata, Column('author_id', Integer, ForeignKey('authors.id')), Column('keyword_id', Integer, ForeignKey('keywords.id')) ) @@ -161,7 +161,7 @@ the :class:`_schema.MetaData` object used by the declarative base:: class Author(Base): __tablename__ = 'authors' id = Column(Integer, primary_key=True) - keywords = relationship("Keyword", secondary=keywords) + keywords = relationship("Keyword", secondary=keyword_author) Like other :func:`~sqlalchemy.orm.relationship` arguments, a string is accepted as well, passing the string name of the table as defined in the @@ -170,7 +170,7 @@ as well, passing the string name of the table as defined in the class Author(Base): __tablename__ = 'authors' id = Column(Integer, primary_key=True) - keywords = relationship("Keyword", secondary="keywords") + keywords = relationship("Keyword", secondary="keyword_author") As with traditional mapping, its generally not a good idea to use a :class:`_schema.Table` as the "secondary" argument which is also mapped to diff --git a/doc/build/orm/inheritance_loading.rst b/doc/build/orm/inheritance_loading.rst index 7e5675c14..3ddff01cf 100644 --- a/doc/build/orm/inheritance_loading.rst +++ b/doc/build/orm/inheritance_loading.rst @@ -541,7 +541,7 @@ similarly to the following: WHERE employee.id IN (?) ORDER BY employee.id (1,) -Combining "selectin" polymorhic loading with query-time +Combining "selectin" polymorphic loading with query-time :func:`_orm.with_polymorphic` usage is also possible (though this is very outer-space stuff!); assuming the above mappings had no ``polymorphic_load`` set up, we could get the same result as follows:: diff --git a/doc/build/orm/internals.rst b/doc/build/orm/internals.rst index c9683e145..08434d3bb 100644 --- a/doc/build/orm/internals.rst +++ b/doc/build/orm/internals.rst @@ -6,7 +6,7 @@ ORM Internals Key ORM constructs, not otherwise covered in other sections, are listed here. -.. currentmodule: sqlalchemy.orm +.. currentmodule:: sqlalchemy.orm .. autoclass:: sqlalchemy.orm.state.AttributeState :members: diff --git a/doc/build/orm/nonstandard_mappings.rst b/doc/build/orm/nonstandard_mappings.rst index 81679dd01..387a3bf90 100644 --- a/doc/build/orm/nonstandard_mappings.rst +++ b/doc/build/orm/nonstandard_mappings.rst @@ -189,7 +189,7 @@ at :ref:`relationship_aliased_class`. As far as the use case of a class that can actually be fully persisted to different tables under different scenarios, very early versions of SQLAlchemy offered a feature for this adapted from Hibernate, known -as the "entity name" feature. However, this use case became infeasable +as the "entity name" feature. However, this use case became infeasible within SQLAlchemy once the mapped class itself became the source of SQL expression construction; that is, the class' attributes themselves link directly to mapped table columns. The feature was removed and replaced diff --git a/doc/build/orm/persistence_techniques.rst b/doc/build/orm/persistence_techniques.rst index 27c8c382f..c33474f57 100644 --- a/doc/build/orm/persistence_techniques.rst +++ b/doc/build/orm/persistence_techniques.rst @@ -98,27 +98,41 @@ The current :class:`~sqlalchemy.engine.Connection` held by the connection = session.connection() -The examples above deal with a :class:`~sqlalchemy.orm.session.Session` that's -bound to a single :class:`~sqlalchemy.engine.Engine` or -:class:`~sqlalchemy.engine.Connection`. To execute statements using a -:class:`~sqlalchemy.orm.session.Session` which is bound either to multiple +The examples above deal with a :class:`_orm.Session` that's +bound to a single :class:`_engine.Engine` or +:class:`_engine.Connection`. To execute statements using a +:class:`_orm.Session` which is bound either to multiple engines, or none at all (i.e. relies upon bound metadata), both -:meth:`~.Session.execute` and -:meth:`~.Session.connection` accept a ``mapper`` keyword -argument, which is passed a mapped class or -:class:`~sqlalchemy.orm.mapper.Mapper` instance, which is used to locate the +:meth:`_orm.Session.execute` and +:meth:`_orm.Session.connection` accept a dictionary of bind arguments +:paramref:`_orm.Session.execute.bind_arguments` which may include "mapper" +which is passed a mapped class or +:class:`_orm.Mapper` instance, which is used to locate the proper context for the desired engine:: Session = sessionmaker() session = Session() # need to specify mapper or class when executing - result = session.execute("select * from table where id=:id", {'id':7}, mapper=MyMappedClass) + result = session.execute( + text("select * from table where id=:id"), + {'id':7}, + bind_arguments={'mapper': MyMappedClass} + ) - result = session.execute(select([mytable], mytable.c.id==7), mapper=MyMappedClass) + result = session.execute( + select([mytable], mytable.c.id==7), + bind_arguments={'mapper': MyMappedClass} + ) connection = session.connection(MyMappedClass) +.. versionchanged:: 1.4 the ``mapper`` and ``clause`` arguments to + :meth:`_orm.Session.execute` are now passed as part of a dictionary + sent as the :paramref:`_orm.Session.execute.bind_arguments` parameter. + The previous arguments are still accepted however this usage is + deprecated. + .. _session_forcing_null: Forcing NULL on a column with a default @@ -249,7 +263,7 @@ at :paramref:`_schema.Column.autoincrement`. For server-generating columns that are not primary key columns or that are not simple autoincrementing integer columns, the ORM requires that these columns -are marked with an appropriate server_default directive that allows the ORM to +are marked with an appropriate ``server_default`` directive that allows the ORM to retrieve this value. Not all methods are supported on all backends, however, so care must be taken to use the appropriate method. The two questions to be answered are, 1. is this column part of the primary key or not, and 2. does the diff --git a/doc/build/orm/session_api.rst b/doc/build/orm/session_api.rst index 849472e9f..bad816967 100644 --- a/doc/build/orm/session_api.rst +++ b/doc/build/orm/session_api.rst @@ -11,37 +11,29 @@ Session and sessionmaker() :inherited-members: .. autoclass:: ORMExecuteState - :members: - - - .. attribute:: session - - The :class:`_orm.Session` in use. + :members: - .. attribute:: statement + .. attribute:: session - The SQL statement being invoked. For an ORM selection as would - be retrieved from :class:`_orm.Query`, this is an instance of - :class:`_future.select` that was generated from the ORM query. + The :class:`_orm.Session` in use. - .. attribute:: parameters + .. attribute:: statement - Dictionary of parameters that was passed to :meth:`_orm.Session.execute`. + The SQL statement being invoked. For an ORM selection as would + be retrieved from :class:`_orm.Query`, this is an instance of + :class:`_future.select` that was generated from the ORM query. - .. attribute:: execution_options + .. attribute:: parameters - Dictionary of execution options passed to :meth:`_orm.Session.execute`. - Note that this dictionary does not include execution options that may - be associated with the statement itself, or with any underlying - :class:`_engine.Connection` that may be used to invoke this statement. + Dictionary of parameters that was passed to :meth:`_orm.Session.execute`. - .. attribute:: bind_arguments + .. attribute:: bind_arguments - The dictionary passed as the - :paramref:`_orm.Session.execute.bind_arguments` dictionary. This - dictionary may be used by extensions to :class:`_orm.Session` to pass - arguments that will assist in determining amongst a set of database - connections which one should be used to invoke this statement. + The dictionary passed as the + :paramref:`_orm.Session.execute.bind_arguments` dictionary. This + dictionary may be used by extensions to :class:`_orm.Session` to pass + arguments that will assist in determining amongst a set of database + connections which one should be used to invoke this statement. .. autoclass:: Session diff --git a/doc/build/orm/session_basics.rst b/doc/build/orm/session_basics.rst index bf57ac686..df157c17c 100644 --- a/doc/build/orm/session_basics.rst +++ b/doc/build/orm/session_basics.rst @@ -522,10 +522,10 @@ Adding New or Existing Items ---------------------------- :meth:`~.Session.add` is used to place instances in the -session. For *transient* (i.e. brand new) instances, this will have the effect +session. For :term:`transient` (i.e. brand new) instances, this will have the effect of an INSERT taking place for those instances upon the next flush. For -instances which are *persistent* (i.e. were loaded by this session), they are -already present and do not need to be added. Instances which are *detached* +instances which are :term:`persistent` (i.e. were loaded by this session), they are +already present and do not need to be added. Instances which are :term:`detached` (i.e. have been removed from a session) may be re-associated with a session using this method:: @@ -632,7 +632,7 @@ illustrated in the example below:: # ... addresses = relationship( - "Address", cascade="all, delete, delete-orphan") + "Address", cascade="all, delete-orphan") # ... @@ -654,7 +654,7 @@ that this related object is not to shared with any other parent simultaneously:: # ... preference = relationship( - "Preference", cascade="all, delete, delete-orphan", + "Preference", cascade="all, delete-orphan", single_parent=True) diff --git a/doc/build/orm/session_transaction.rst b/doc/build/orm/session_transaction.rst index 233768f42..06139e0c5 100644 --- a/doc/build/orm/session_transaction.rst +++ b/doc/build/orm/session_transaction.rst @@ -403,7 +403,7 @@ has multiple binds or some other custom scheme for :meth:`.Session.get_bind`, we can pass additional arguments to :meth:`.Session.connection` in order to affect how the bind is procured:: - sess = my_sesssionmaker() + sess = my_sessionmaker() # set up a transaction for the bind associated with # the User mapper diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst index 8ea8af4a2..a6ef57bed 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}<User(name='ed', fullname='Ed Jones', nickname='eddie')> -* :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,9 +990,9 @@ 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:: +returned by the SQL statement based on column name: .. sourcecode:: python+sql @@ -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/dialects/mssql/provision.py b/lib/sqlalchemy/dialects/mssql/provision.py index 84b9e4194..23c841da6 100644 --- a/lib/sqlalchemy/dialects/mssql/provision.py +++ b/lib/sqlalchemy/dialects/mssql/provision.py @@ -40,7 +40,7 @@ def _mssql_drop_ignore(conn, ident): # for row in conn.exec_driver_sql( # "select session_id from sys.dm_exec_sessions " # "where database_id=db_id('%s')" % ident): - # log.info("killing SQL server sesssion %s", row['session_id']) + # log.info("killing SQL server session %s", row['session_id']) # conn.exec_driver_sql("kill %s" % row['session_id']) conn.exec_driver_sql("drop database %s" % ident) diff --git a/lib/sqlalchemy/dialects/oracle/cx_oracle.py b/lib/sqlalchemy/dialects/oracle/cx_oracle.py index 4aae059dd..651a6e673 100644 --- a/lib/sqlalchemy/dialects/oracle/cx_oracle.py +++ b/lib/sqlalchemy/dialects/oracle/cx_oracle.py @@ -100,7 +100,7 @@ Unicode As is the case for all DBAPIs under Python 3, all strings are inherently Unicode strings. Under Python 2, cx_Oracle also supports Python Unicode -objects directly. In all cases however, the driver requires an explcit +objects directly. In all cases however, the driver requires an explicit encoding configuration. Ensuring the Correct Client Encoding diff --git a/lib/sqlalchemy/dialects/postgresql/json.py b/lib/sqlalchemy/dialects/postgresql/json.py index ea7b04d4f..255f1af21 100644 --- a/lib/sqlalchemy/dialects/postgresql/json.py +++ b/lib/sqlalchemy/dialects/postgresql/json.py @@ -234,8 +234,8 @@ class JSON(sqltypes.JSON): class JSONB(JSON): """Represent the PostgreSQL JSONB type. - The :class:`_postgresql.JSONB` type stores arbitrary JSONB format data, e. - g.:: + The :class:`_postgresql.JSONB` type stores arbitrary JSONB format data, + e.g.:: data_table = Table('data_table', metadata, Column('id', Integer, primary_key=True), @@ -249,8 +249,8 @@ class JSONB(JSON): ) The :class:`_postgresql.JSONB` type includes all operations provided by - :class:`_types.JSON`, including the same behaviors for indexing operations - . + :class:`_types.JSON`, including the same behaviors for indexing + operations. It also adds additional operators specific to JSONB, including :meth:`.JSONB.Comparator.has_key`, :meth:`.JSONB.Comparator.has_all`, :meth:`.JSONB.Comparator.has_any`, :meth:`.JSONB.Comparator.contains`, diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index c73f89a2b..ed4133dbb 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -42,7 +42,7 @@ class Connection(Connectable): possible that the underlying DBAPI connection may not support shared access between threads. Check the DBAPI documentation for details. - The Connection object represents a single dbapi connection checked out + The Connection object represents a single DBAPI connection checked out from the connection pool. In this state, the connection pool has no affect upon the connection, including its expiration or timeout state. For the connection pool to properly manage connections, connections should be @@ -117,7 +117,7 @@ class Connection(Connectable): return self._execution_options.get("schema_translate_map", None) def schema_for_object(self, obj): - """return the schema name for the given schema item taking into + """Return the schema name for the given schema item taking into account current schema translate map. """ @@ -1944,7 +1944,7 @@ class Transaction(object): "deactive", however leave this transaction object in place as far as the connection's state. - for a "real" transaction this should roll back the transction + for a "real" transaction this should roll back the transaction and ensure this transaction is no longer a reset agent. this is used for nesting of marker transactions where the marker @@ -2372,7 +2372,7 @@ class Engine(Connectable, log.Identified): """Clear the compiled cache associated with the dialect. This applies **only** to the built-in cache that is established - via the :paramref:`.create_engine.query_cache_size` parameter. + via the :paramref:`_engine.create_engine.query_cache_size` parameter. It will not impact any dictionary caches that were passed via the :paramref:`.Connection.execution_options.query_cache` parameter. @@ -2510,8 +2510,8 @@ class Engine(Connectable, log.Identified): return "Engine(%r)" % self.url def dispose(self): - """Dispose of the connection pool used by this :class:`_engine.Engine` - . + """Dispose of the connection pool used by this + :class:`_engine.Engine`. This has the effect of fully closing all **currently checked in** database connections. Connections that are still checked out diff --git a/lib/sqlalchemy/engine/create.py b/lib/sqlalchemy/engine/create.py index 9bf72eb06..cc138412b 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/engine/cursor.py b/lib/sqlalchemy/engine/cursor.py index 65cd92e6f..6f4934521 100644 --- a/lib/sqlalchemy/engine/cursor.py +++ b/lib/sqlalchemy/engine/cursor.py @@ -720,7 +720,7 @@ class LegacyCursorResultMetaData(CursorResultMetaData): if result is not None: if result[MD_OBJECTS] is _UNPICKLED: util.warn_deprecated( - "Retreiving row values using Column objects from a " + "Retrieving row values using Column objects from a " "row that was unpickled is deprecated; adequate " "state cannot be pickled for this to be efficient. " "This usage will raise KeyError in a future release.", @@ -728,7 +728,7 @@ class LegacyCursorResultMetaData(CursorResultMetaData): ) else: util.warn_deprecated( - "Retreiving row values using Column objects with only " + "Retrieving row values using Column objects with only " "matching names as keys is deprecated, and will raise " "KeyError in a future release; only Column " "objects that are explicitly part of the statement " @@ -802,7 +802,7 @@ class ResultFetchStrategy(object): class NoCursorFetchStrategy(ResultFetchStrategy): """Cursor strategy for a result that has no open cursor. - There are two varities of this strategy, one for DQL and one for + There are two varieties of this strategy, one for DQL and one for DML (and also DDL), each of which represent a result that had a cursor but no longer has one. @@ -1584,7 +1584,7 @@ class BaseCursorResult(object): @property def lastrowid(self): - """return the 'lastrowid' accessor on the DBAPI cursor. + """Return the 'lastrowid' accessor on the DBAPI cursor. This is a DBAPI specific method and is only functional for those backends which support it, for statements diff --git a/lib/sqlalchemy/engine/default.py b/lib/sqlalchemy/engine/default.py index 790f68de7..0fe3b085b 100644 --- a/lib/sqlalchemy/engine/default.py +++ b/lib/sqlalchemy/engine/default.py @@ -294,8 +294,8 @@ class DefaultDialect(interfaces.Dialect): """True if this dialect supports sane rowcount even if RETURNING is in use. - For dialects that don't support RETURNING, this is synomous - with supports_sane_rowcount. + For dialects that don't support RETURNING, this is synonymous with + ``supports_sane_rowcount``. """ return self.supports_sane_rowcount diff --git a/lib/sqlalchemy/engine/events.py b/lib/sqlalchemy/engine/events.py index ef760bb54..bd664fb8f 100644 --- a/lib/sqlalchemy/engine/events.py +++ b/lib/sqlalchemy/engine/events.py @@ -235,8 +235,8 @@ class ConnectionEvents(event.Events): .. versionadded: 1.4 - :param result: :class:`_engine.CursorResult` generated by the execution - . + :param result: :class:`_engine.CursorResult` generated by the + execution. """ diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py index 59b9cd4ce..f925df6c5 100644 --- a/lib/sqlalchemy/engine/interfaces.py +++ b/lib/sqlalchemy/engine/interfaces.py @@ -386,13 +386,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. @@ -424,7 +424,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. """ @@ -434,7 +434,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. """ @@ -455,7 +455,7 @@ class Dialect(object): """Check the existence of a particular index name in the database. Given a :class:`_engine.Connection` object, a string - `table_name` and stiring index name, return True if an index of the + `table_name` and string index name, return True if an index of the given name on the given table exists, false otherwise. The :class:`.DefaultDialect` implements this in terms of the @@ -1022,7 +1022,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/engine/mock.py b/lib/sqlalchemy/engine/mock.py index d6a542e19..6c91d1434 100644 --- a/lib/sqlalchemy/engine/mock.py +++ b/lib/sqlalchemy/engine/mock.py @@ -92,8 +92,8 @@ def create_mock_engine(url, executor, **kw): string using :meth:`.DDLElement.compile`. .. versionadded:: 1.4 - the :func:`.create_mock_engine` function replaces - the previous "mock" engine strategy used with :func:`_sa.create_engine` - . + the previous "mock" engine strategy used with + :func:`_sa.create_engine`. .. seealso:: diff --git a/lib/sqlalchemy/engine/reflection.py b/lib/sqlalchemy/engine/reflection.py index fded37b2a..198b5e568 100644 --- a/lib/sqlalchemy/engine/reflection.py +++ b/lib/sqlalchemy/engine/reflection.py @@ -316,7 +316,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`. """ @@ -351,7 +351,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. @@ -366,7 +366,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. @@ -458,7 +458,7 @@ class Inspector(object): * ``autoincrement`` - indicates that the column is auto incremented - this is returned as a boolean or 'auto' - * ``comment`` - (optional) the commnet on the column. Only some + * ``comment`` - (optional) the comment on the column. Only some dialects return this key * ``computed`` - (optional) when present it indicates that this column @@ -505,10 +505,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, @@ -530,20 +530,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, @@ -566,22 +566,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. @@ -607,10 +607,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, @@ -633,7 +633,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 @@ -654,13 +654,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 @@ -701,8 +701,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/engine/result.py b/lib/sqlalchemy/engine/result.py index ead52a3f8..f75cba57d 100644 --- a/lib/sqlalchemy/engine/result.py +++ b/lib/sqlalchemy/engine/result.py @@ -891,7 +891,7 @@ class Result(InPlaceGenerative): None and the ending value. Prefer to use iterative / collection methods which support scalar None values. - this method is provided for backwards compatibility with + This method is provided for backwards compatibility with SQLAlchemy 1.x.x. To fetch the first row of a result only, use the @@ -921,7 +921,7 @@ class Result(InPlaceGenerative): When all rows are exhausted, returns an empty list. - this method is provided for backwards compatibility with + This method is provided for backwards compatibility with SQLAlchemy 1.x.x. To fetch rows in groups, use the :meth:`._result.Result.partitions` diff --git a/lib/sqlalchemy/engine/url.py b/lib/sqlalchemy/engine/url.py index 7b7a0047c..f0685d9e3 100644 --- a/lib/sqlalchemy/engine/url.py +++ b/lib/sqlalchemy/engine/url.py @@ -29,7 +29,7 @@ class URL(object): This object is suitable to be passed directly to a :func:`~sqlalchemy.create_engine` call. The fields of the URL are parsed - from a string by the :func:`.make_url` function. the string + from a string by the :func:`.make_url` function. The string format of the URL is an RFC-1738-style string. All initialization parameters are available as public attributes. diff --git a/lib/sqlalchemy/event/api.py b/lib/sqlalchemy/event/api.py index 9cff67033..6bd63ceca 100644 --- a/lib/sqlalchemy/event/api.py +++ b/lib/sqlalchemy/event/api.py @@ -67,7 +67,7 @@ def listen(target, identifier, fn, *args, **kw): .. warning:: The ``once`` argument does not imply automatic de-registration of the listener function after it has been invoked a first time; a listener entry will remain associated with the target object. - Associating an arbitrarily high number of listeners without explictitly + Associating an arbitrarily high number of listeners without explicitly removing them will cause memory to grow unbounded even if ``once=True`` is specified. @@ -134,7 +134,7 @@ def listens_for(target, identifier, *args, **kw): .. warning:: The ``once`` argument does not imply automatic de-registration of the listener function after it has been invoked a first time; a listener entry will remain associated with the target object. - Associating an arbitrarily high number of listeners without explictitly + Associating an arbitrarily high number of listeners without explicitly removing them will cause memory to grow unbounded even if ``once=True`` is specified. diff --git a/lib/sqlalchemy/event/base.py b/lib/sqlalchemy/event/base.py index 2eb8846f6..a87c1fe44 100644 --- a/lib/sqlalchemy/event/base.py +++ b/lib/sqlalchemy/event/base.py @@ -213,7 +213,7 @@ class Events(util.with_metaclass(_EventMeta, object)): # This allows an Events subclass to define additional utility # methods made available to the target via # "self.dispatch._events.<utilitymethod>" - # @staticemethod to allow easy "super" calls while in a metaclass + # @staticmethod to allow easy "super" calls while in a metaclass # constructor. cls.dispatch = dispatch_cls(None) dispatch_cls._events = cls diff --git a/lib/sqlalchemy/ext/associationproxy.py b/lib/sqlalchemy/ext/associationproxy.py index fc10cb88d..dd6217664 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/api.py b/lib/sqlalchemy/ext/declarative/api.py index 65d100bc7..31b5e492c 100644 --- a/lib/sqlalchemy/ext/declarative/api.py +++ b/lib/sqlalchemy/ext/declarative/api.py @@ -230,7 +230,8 @@ class declared_attr(interfaces._MappedAttribute, property): def id(cls): if has_inherited_table(cls): return Column( - ForeignKey('myclass.id'), primary_key=True) + ForeignKey('myclass.id'), primary_key=True + ) else: return Column(Integer, primary_key=True) diff --git a/lib/sqlalchemy/ext/declarative/clsregistry.py b/lib/sqlalchemy/ext/declarative/clsregistry.py index 20de3c636..51af6f1b4 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/ext/horizontal_shard.py b/lib/sqlalchemy/ext/horizontal_shard.py index 9d7266d1a..786d00597 100644 --- a/lib/sqlalchemy/ext/horizontal_shard.py +++ b/lib/sqlalchemy/ext/horizontal_shard.py @@ -34,9 +34,9 @@ class ShardedQuery(Query): self._shard_id = None def set_shard(self, shard_id): - """return a new query, limited to a single shard ID. + """Return a new query, limited to a single shard ID. - all subsequent operations with the returned query will + All subsequent operations with the returned query will be against the single shard regardless of other state. The shard_id can be passed for a 2.0 style execution to the @@ -79,7 +79,7 @@ class ShardedSession(Session): where the query should be issued. Results from all shards returned will be combined together into a single listing. - .. versionchanged:: 1.4 The ``execute_chooser`` paramter + .. versionchanged:: 1.4 The ``execute_chooser`` parameter supersedes the ``query_chooser`` parameter. :param shards: A dictionary of string shard names diff --git a/lib/sqlalchemy/ext/hybrid.py b/lib/sqlalchemy/ext/hybrid.py index efd8d7d6b..b031e82fd 100644 --- a/lib/sqlalchemy/ext/hybrid.py +++ b/lib/sqlalchemy/ext/hybrid.py @@ -668,12 +668,11 @@ simple:: return self.parent.parent For the expression, things are not so clear. We'd need to construct a -:class:`_query.Query` where we :meth:`_query.Query.join` twice along ``Node. -parent`` to -get to the ``grandparent``. We can instead return a transforming callable -that we'll combine with the :class:`.Comparator` class to receive any -:class:`_query.Query` object, and return a new one that's joined to the -``Node.parent`` attribute and filtered based on the given criterion:: +:class:`_query.Query` where we :meth:`_query.Query.join` twice along +``Node.parent`` to get to the ``grandparent``. We can instead return a +transforming callable that we'll combine with the :class:`.Comparator` class to +receive any :class:`_query.Query` object, and return a new one that's joined to +the ``Node.parent`` attribute and filtered based on the given criterion:: from sqlalchemy.ext.hybrid import Comparator @@ -690,7 +689,7 @@ that we'll combine with the :class:`.Comparator` class to receive any class Node(Base): __tablename__ = 'node' - id =Column(Integer, primary_key=True) + id = Column(Integer, primary_key=True) parent_id = Column(Integer, ForeignKey('node.id')) parent = relationship("Node", remote_side=id) @@ -711,7 +710,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 @@ -987,7 +986,7 @@ class hybrid_property(interfaces.InspectionAttrInfo): .. note:: - when referring to a hybrid property from an owning class (e.g. + When referring to a hybrid property from an owning class (e.g. ``SomeClass.some_hybrid``), an instance of :class:`.QueryableAttribute` is returned, representing the expression or comparator object as well as this hybrid object. @@ -1027,7 +1026,7 @@ class hybrid_property(interfaces.InspectionAttrInfo): .. note:: - when referring to a hybrid property from an owning class (e.g. + When referring to a hybrid property from an owning class (e.g. ``SomeClass.some_hybrid``), an instance of :class:`.QueryableAttribute` is returned, representing the expression or comparator object as this hybrid object. However, diff --git a/lib/sqlalchemy/ext/instrumentation.py b/lib/sqlalchemy/ext/instrumentation.py index 378d7445f..300d0d81c 100644 --- a/lib/sqlalchemy/ext/instrumentation.py +++ b/lib/sqlalchemy/ext/instrumentation.py @@ -42,10 +42,10 @@ inheritance hierarchy. The value of this attribute must be a callable and will be passed a class object. The callable must return one of: - - An instance of an InstrumentationManager or subclass + - An instance of an :class:`.InstrumentationManager` or subclass - An object implementing all or some of InstrumentationManager (TODO) - A dictionary of callables, implementing all or some of the above (TODO) - - An instance of a ClassManager or subclass + - An instance of a :class:`.ClassManager` or subclass This attribute is consulted by SQLAlchemy instrumentation resolution, once the :mod:`sqlalchemy.ext.instrumentation` module diff --git a/lib/sqlalchemy/future/engine.py b/lib/sqlalchemy/future/engine.py index d3b13b510..d5922daa3 100644 --- a/lib/sqlalchemy/future/engine.py +++ b/lib/sqlalchemy/future/engine.py @@ -267,7 +267,7 @@ class Connection(_LegacyConnection): * :class:`_schema.DDL` and objects which inherit from :class:`_schema.DDLElement` - :param parameters: parameters which will be bound into the statment. + :param parameters: parameters which will be bound into the statement. This may be either a dictionary of parameter names to values, or a mutable sequence (e.g. a list) of dictionaries. When a list of dictionaries is passed, the underlying statement execution @@ -343,7 +343,7 @@ class Engine(_LegacyEngine): # they aren't calling "engine.begin()" explicitly, however, DDL # may be a special case for which we want to continue doing it this # way. A big win here is that the full DDL sequence is inside of a - # single transaction rather than COMMIT for each statment. + # single transaction rather than COMMIT for each statement. with self.begin() as conn: conn._run_ddl_visitor(visitorcallable, element, **kwargs) diff --git a/lib/sqlalchemy/future/selectable.py b/lib/sqlalchemy/future/selectable.py index 53fc7c107..473242bf8 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. """ @@ -114,7 +114,7 @@ class Select(_LegacySelect): @_generative def join(self, target, onclause=None, isouter=False, full=False): - r"""Create a SQL JOIN against this :class:`_expresson.Select` + r"""Create a SQL JOIN against this :class:`_expression.Select` object's criterion and apply generatively, returning the newly resulting :class:`_expression.Select`. @@ -132,7 +132,7 @@ class Select(_LegacySelect): def join_from( self, from_, target, onclause=None, isouter=False, full=False ): - r"""Create a SQL JOIN against this :class:`_expresson.Select` + r"""Create a SQL JOIN against this :class:`_expression.Select` object's criterion and apply generatively, returning the newly resulting :class:`_expression.Select`. diff --git a/lib/sqlalchemy/orm/base.py b/lib/sqlalchemy/orm/base.py index 54e45cd1a..6fdf1f372 100644 --- a/lib/sqlalchemy/orm/base.py +++ b/lib/sqlalchemy/orm/base.py @@ -463,8 +463,8 @@ class InspectionAttr(object): __slots__ = () is_selectable = False - """Return True if this object is an instance of """ - """:class:`expression.Selectable`.""" + """Return True if this object is an instance of + :class:`_expression.Selectable`.""" is_aliased_class = False """True if this object is an instance of :class:`.AliasedClass`.""" @@ -505,8 +505,8 @@ class InspectionAttr(object): """ is_clause_element = False - """True if this object is an instance of """ - """:class:`_expression.ClauseElement`.""" + """True if this object is an instance of + :class:`_expression.ClauseElement`.""" extension_type = NOT_EXTENSION """The extension type, if any. diff --git a/lib/sqlalchemy/orm/context.py b/lib/sqlalchemy/orm/context.py index 77237f089..3a0cce609 100644 --- a/lib/sqlalchemy/orm/context.py +++ b/lib/sqlalchemy/orm/context.py @@ -792,7 +792,7 @@ class ORMSelectCompileState(ORMCompileState, SelectState): if self.order_by: # the default coercion for ORDER BY is now the OrderByRole, # which adds an additional post coercion to ByOfRole in that - # elements are converted into label refernences. For the + # elements are converted into label references. For the # eager load / subquery wrapping case, we need to un-coerce # the original expressions outside of the label references # in order to have them render. @@ -1421,16 +1421,16 @@ class ORMSelectCompileState(ORMCompileState, SelectState): "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 " - "help resolve the ambiguity." + "providing an explicit ON clause if not present already " + "to help resolve the ambiguity." ) else: raise sa_exc.InvalidRequestError( "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 " - "help resolve the ambiguity." % (right,) + "providing an explicit ON clause if not present already " + "to help resolve the ambiguity." % (right,) ) elif self._entities: @@ -1467,16 +1467,16 @@ class ORMSelectCompileState(ORMCompileState, SelectState): "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 " - "help resolve the ambiguity." + "providing an explicit ON clause if not present already " + "to help resolve the ambiguity." ) else: raise sa_exc.InvalidRequestError( "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 " - "help resolve the ambiguity." % (right,) + "providing an explicit ON clause if not present already " + "to help resolve the ambiguity." % (right,) ) else: raise sa_exc.InvalidRequestError( @@ -2471,7 +2471,7 @@ class _ORMColumnEntity(_ColumnEntity): column = column._deannotate() # use entity_zero as the from if we have it. this is necessary - # for polymorpic scenarios where our FROM is based on ORM entity, + # for polymorphic scenarios where our FROM is based on ORM entity, # not the FROM of the column. but also, don't use it if our column # doesn't actually have any FROMs that line up, such as when its # a scalar subquery. diff --git a/lib/sqlalchemy/orm/dynamic.py b/lib/sqlalchemy/orm/dynamic.py index adc976e32..d15127563 100644 --- a/lib/sqlalchemy/orm/dynamic.py +++ b/lib/sqlalchemy/orm/dynamic.py @@ -274,7 +274,7 @@ class AppenderMixin(object): # this is a hack right now. The Query only knows how to # make subsequent joins() without a given left-hand side # from self._from_obj[0]. We need to ensure prop.secondary - # is in the FROM. So we purposly put the mapper selectable + # is in the FROM. So we purposely put the mapper selectable # in _from_obj[0] to ensure a user-defined join() later on # doesn't fail, and secondary is then in _from_obj[1]. self._from_obj = (prop.mapper.selectable, prop.secondary) diff --git a/lib/sqlalchemy/orm/instrumentation.py b/lib/sqlalchemy/orm/instrumentation.py index 432bff7d4..43e380101 100644 --- a/lib/sqlalchemy/orm/instrumentation.py +++ b/lib/sqlalchemy/orm/instrumentation.py @@ -40,7 +40,7 @@ from ..util import HasMemoized class ClassManager(HasMemoized, dict): - """tracks state information at the class level.""" + """Tracks state information at the class level.""" MANAGER_ATTR = base.DEFAULT_MANAGER_ATTR STATE_ATTR = base.DEFAULT_STATE_ATTR @@ -229,7 +229,7 @@ class ClassManager(HasMemoized, dict): setattr(self.class_, self.MANAGER_ATTR, self) def dispose(self): - """Dissasociate this manager from its class.""" + """Disassociate this manager from its class.""" delattr(self.class_, self.MANAGER_ATTR) @@ -493,7 +493,7 @@ class InstrumentationFactory(object): # this attribute is replaced by sqlalchemy.ext.instrumentation -# when importred. +# when imported. _instrumentation_factory = InstrumentationFactory() # these attributes are replaced by sqlalchemy.ext.instrumentation diff --git a/lib/sqlalchemy/orm/loading.py b/lib/sqlalchemy/orm/loading.py index a33e1b77d..abb8ce32d 100644 --- a/lib/sqlalchemy/orm/loading.py +++ b/lib/sqlalchemy/orm/loading.py @@ -657,7 +657,7 @@ def _instance_processor( cached_populators, ) else: - # loader strategries like subqueryload, selectinload, + # loader strategies like subqueryload, selectinload, # joinedload, basically relationships, these need to interact # with the context each time to work correctly. todo.append(prop) @@ -1249,7 +1249,7 @@ def load_scalar_attributes(mapper, state, attribute_names, passive): # concrete inheritance, the class manager might have some keys # of attributes on the superclass that we didn't actually map. # These could be mapped as "concrete, dont load" or could be completely - # exluded from the mapping and we know nothing about them. Filter them + # excluded from the mapping and we know nothing about them. Filter them # here to prevent them from coming through. if attribute_names: attribute_names = attribute_names.intersection(mapper.attrs.keys()) diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py index ef0e9a49b..2b04f1cc7 100644 --- a/lib/sqlalchemy/orm/mapper.py +++ b/lib/sqlalchemy/orm/mapper.py @@ -324,7 +324,7 @@ class Mapper( that specify ``delete-orphan`` cascade. This behavior is more consistent with that of a persistent object, and allows behavior to be consistent in more scenarios independently of whether or not an - orphanable object has been flushed yet or not. + orphan object has been flushed yet or not. See the change note and example at :ref:`legacy_is_orphan_addition` for more detail on this change. @@ -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,12 +756,11 @@ 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`, :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 458217e22..336b7d9aa 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`. @@ -561,9 +561,9 @@ class Query( Analogous to :meth:`sqlalchemy.sql.expression.SelectBase.scalar_subquery`. - .. versionchanged:: 1.4 the :meth:`_query.Query.scalar_subquery` - method - replaces the :meth:`_query.Query.as_scalar` method. + .. versionchanged:: 1.4 The :meth:`_query.Query.scalar_subquery` + method replaces the :meth:`_query.Query.as_scalar` method. + """ return self.enable_eagerloads(False).statement.scalar_subquery() @@ -645,8 +645,8 @@ class Query( .. note:: The :meth:`_query.Query.with_labels` method *only* applies the output of :attr:`_query.Query.statement`, and *not* to any of - the result-row invoking systems of :class:`_query.Query` itself, e. - g. + the result-row invoking systems of :class:`_query.Query` itself, + e.g. :meth:`_query.Query.first`, :meth:`_query.Query.all`, etc. To execute a query using :meth:`_query.Query.with_labels`, invoke the @@ -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:: @@ -1621,10 +1621,10 @@ class Query( @_generative def params(self, *args, **kwargs): - r"""add values for bind parameters which may have been + r"""Add values for bind parameters which may have been specified in filter(). - parameters may be specified using \**kwargs, or optionally a single + Parameters may be specified using \**kwargs, or optionally a single dictionary as the first positional argument. The reason for both is that \**kwargs is convenient, however some parameter dictionaries contain unicode keys in which case \**kwargs cannot be used. @@ -1643,7 +1643,7 @@ class Query( @_generative @_assertions(_no_statement_condition, _no_limit_offset) def filter(self, *criterion): - r"""apply the given filtering criterion to a copy + r"""Apply the given filtering criterion to a copy of this :class:`_query.Query`, using SQL expressions. e.g.:: @@ -1702,7 +1702,7 @@ class Query( return self._raw_columns[0] def filter_by(self, **kwargs): - r"""apply the given filtering criterion to a copy + r"""Apply the given filtering criterion to a copy of this :class:`_query.Query`, using keyword expressions. e.g.:: @@ -1743,11 +1743,12 @@ class Query( @_generative @_assertions(_no_statement_condition, _no_limit_offset) def order_by(self, *clauses): - """apply one or more ORDER BY criterion to the query and return - the newly resulting ``Query`` + """Apply one or more ORDER BY criterion to the query and return + the newly resulting :class:`_query.Query`. + + All existing ORDER BY settings can be suppressed by passing + ``None``. - All existing ORDER BY settings candef order_by be suppressed by - passing ``None``. """ if len(clauses) == 1 and (clauses[0] is None or clauses[0] is False): @@ -1774,15 +1775,15 @@ class Query( @_generative @_assertions(_no_statement_condition, _no_limit_offset) def group_by(self, *clauses): - """apply one or more GROUP BY criterion to the query and return - the newly resulting :class:`_query.Query` + """Apply one or more GROUP BY criterion to the query and return + the newly resulting :class:`_query.Query`. All existing GROUP BY settings can be suppressed by passing ``None`` - this will suppress any GROUP BY configured on mappers as well. - .. versionadded:: 1.1 GROUP BY can be cancelled by passing None, - in the same way as ORDER BY. + .. versionadded:: 1.1 GROUP BY can be cancelled by passing + ``None``, in the same way as ORDER BY. """ @@ -1810,7 +1811,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 @@ -1948,7 +1949,7 @@ class Query( Where above, the call to :meth:`_query.Query.join` along ``User.addresses`` will result in SQL approximately equivalent to:: - SELECT user.id, User.name + SELECT user.id, user.name FROM user JOIN address ON user.id = address.user_id In the above example we refer to ``User.addresses`` as passed to diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index a398da793..abc990f7b 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -218,7 +218,7 @@ class ORMExecuteState(util.MemoizedSlots): def is_orm_statement(self): """return True if the operation is an ORM statement. - This indictes that the select(), update(), or delete() being + This indicates that the select(), update(), or delete() being invoked contains ORM entities as subjects. For a statement that does not have ORM entities and instead refers only to :class:`.Table` metadata, it is invoked as a Core SQL statement @@ -1319,7 +1319,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`. @@ -1462,8 +1462,8 @@ class Session(_SessionClassMethods): The :meth:`.Session.execute` method does *not* invoke autoflush. - The :class:`_engine.CursorResult` returned by the :meth:`.Session. - execute` + The :class:`_engine.CursorResult` returned by the + :meth:`.Session.execute` method is returned with the "close_with_result" flag set to true; the significance of this flag is that if this :class:`.Session` is autocommitting and does not have a transaction-dedicated @@ -1476,7 +1476,7 @@ class Session(_SessionClassMethods): :class:`.Session` is configured with autocommit=True and no transaction has been started. - :param clause: + :param statement: An executable statement (i.e. an :class:`.Executable` expression such as :func:`_expression.select`) or string SQL statement to be executed. @@ -1489,7 +1489,7 @@ class Session(_SessionClassMethods): must correspond to parameter names present in the statement. :param bind_arguments: dictionary of additional arguments to determine - the bind. may include "mapper", "bind", or other custom arguments. + the bind. May include "mapper", "bind", or other custom arguments. Contents of this dictionary are passed to the :meth:`.Session.get_bind` method. @@ -1701,8 +1701,8 @@ class Session(_SessionClassMethods): def bind_mapper(self, mapper, bind): """Associate a :class:`_orm.Mapper` or arbitrary Python class with a - "bind", e.g. an :class:`_engine.Engine` or :class:`_engine.Connection` - . + "bind", e.g. an :class:`_engine.Engine` or + :class:`_engine.Connection`. The given entity is added to a lookup used by the :meth:`.Session.get_bind` method. @@ -1781,15 +1781,15 @@ class Session(_SessionClassMethods): The order of resolution is: - 1. if mapper given and session.binds is present, + 1. if mapper given and :paramref:`.Session.binds` is present, locate a bind based first on the mapper in use, then on the mapped class in use, then on any base classes that are present in the ``__mro__`` of the mapped class, from more specific superclasses to more general. - 2. if clause given and session.binds is present, + 2. if clause given and ``Session.binds`` is present, locate a bind based on :class:`_schema.Table` objects - found in the given clause present in session.binds. - 3. if session.bind is present, return that. + found in the given clause present in ``Session.binds``. + 3. if ``Session.binds`` is present, return that. 4. if clause given, attempt to return a bind linked to the :class:`_schema.MetaData` ultimately associated with the clause. @@ -2783,7 +2783,7 @@ class Session(_SessionClassMethods): .. seealso:: - ``load_on_pending`` at :func:`_orm.relationship` - this flag + :paramref:`_orm.relationship.load_on_pending` - this flag allows per-relationship loading of many-to-ones on items that are pending. @@ -3568,7 +3568,7 @@ class sessionmaker(_SessionClassMethods): sess = Session() - .. seealso: + .. seealso:: :ref:`session_getting` - introductory text on creating sessions using :class:`.sessionmaker`. diff --git a/lib/sqlalchemy/orm/state.py b/lib/sqlalchemy/orm/state.py index 48546f24e..233283497 100644 --- a/lib/sqlalchemy/orm/state.py +++ b/lib/sqlalchemy/orm/state.py @@ -119,7 +119,7 @@ class InstanceState(interfaces.InspectionAttrInfo): @property def transient(self): - """Return true if the object is :term:`transient`. + """Return ``True`` if the object is :term:`transient`. .. seealso:: @@ -130,7 +130,7 @@ class InstanceState(interfaces.InspectionAttrInfo): @property def pending(self): - """Return true if the object is :term:`pending`. + """Return ``True`` if the object is :term:`pending`. .. seealso:: @@ -142,7 +142,7 @@ class InstanceState(interfaces.InspectionAttrInfo): @property def deleted(self): - """Return true if the object is :term:`deleted`. + """Return ``True`` if the object is :term:`deleted`. An object that is in the deleted state is guaranteed to not be within the :attr:`.Session.identity_map` of its parent @@ -196,7 +196,7 @@ class InstanceState(interfaces.InspectionAttrInfo): @property def persistent(self): - """Return true if the object is :term:`persistent`. + """Return ``True`` if the object is :term:`persistent`. An object that is in the persistent state is guaranteed to be within the :attr:`.Session.identity_map` of its parent @@ -217,7 +217,7 @@ class InstanceState(interfaces.InspectionAttrInfo): @property def detached(self): - """Return true if the object is :term:`detached`. + """Return ``True`` if the object is :term:`detached`. .. seealso:: @@ -324,7 +324,7 @@ class InstanceState(interfaces.InspectionAttrInfo): """Return ``True`` if this object has an identity key. This should always have the same value as the - expression ``state.persistent or state.detached``. + expression ``state.persistent`` or ``state.detached``. """ return bool(self.key) diff --git a/lib/sqlalchemy/orm/unitofwork.py b/lib/sqlalchemy/orm/unitofwork.py index 5a3f99e70..97eea4864 100644 --- a/lib/sqlalchemy/orm/unitofwork.py +++ b/lib/sqlalchemy/orm/unitofwork.py @@ -177,7 +177,7 @@ class UOWTransaction(object): return bool(self.states) def was_already_deleted(self, state): - """return true if the given state is expired and was deleted + """Return ``True`` if the given state is expired and was deleted previously. """ if state.expired: @@ -189,7 +189,7 @@ class UOWTransaction(object): return False def is_deleted(self, state): - """return true if the given state is marked as deleted + """Return ``True`` if the given state is marked as deleted within this uowtransaction.""" return state in self.states and self.states[state][0] @@ -202,7 +202,7 @@ class UOWTransaction(object): return ret def remove_state_actions(self, state): - """remove pending actions for a state from the uowtransaction.""" + """Remove pending actions for a state from the uowtransaction.""" isdelete = self.states[state][0] @@ -211,7 +211,7 @@ class UOWTransaction(object): def get_attribute_history( self, state, key, passive=attributes.PASSIVE_NO_INITIALIZE ): - """facade to attributes.get_state_history(), including + """Facade to attributes.get_state_history(), including caching of results.""" hashkey = ("history", state, key) @@ -421,10 +421,10 @@ class UOWTransaction(object): rec.execute(self) def finalize_flush_changes(self): - """mark processed objects as clean / deleted after a successful + """Mark processed objects as clean / deleted after a successful flush(). - this method is called within the flush() method after the + This method is called within the flush() method after the execute() method has succeeded and the transaction has been committed. """ diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py index f7a97bfe5..e04c54497 100644 --- a/lib/sqlalchemy/orm/util.py +++ b/lib/sqlalchemy/orm/util.py @@ -60,7 +60,8 @@ all_cascades = frozenset( class CascadeOptions(frozenset): - """Keeps track of the options sent to relationship().cascade""" + """Keeps track of the options sent to + :paramref:`.relationship.cascade`""" _add_w_all_cascades = all_cascades.difference( ["all", "none", "delete-orphan"] @@ -263,7 +264,7 @@ def polymorphic_union( def identity_key(*args, **kwargs): - """Generate "identity key" tuples, as are used as keys in the + r"""Generate "identity key" tuples, as are used as keys in the :attr:`.Session.identity_map` dictionary. This function has several call styles: @@ -890,8 +891,8 @@ def aliased(element, alias=None, name=None, flat=False, adapt_on_names=False): ORM-mapped in this case. :param element: element to be aliased. Is normally a mapped class, - but for convenience can also be a :class:`_expression.FromClause` element - . + but for convenience can also be a :class:`_expression.FromClause` + element. :param alias: Optional selectable unit to map the element to. This is usually used to link the object to a subquery, and should be an aliased diff --git a/lib/sqlalchemy/sql/base.py b/lib/sqlalchemy/sql/base.py index 4c603b6dd..9dcd7dca9 100644 --- a/lib/sqlalchemy/sql/base.py +++ b/lib/sqlalchemy/sql/base.py @@ -617,7 +617,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`, @@ -880,7 +880,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] @@ -898,8 +898,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**:: @@ -1079,23 +1079,23 @@ 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 :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/compiler.py b/lib/sqlalchemy/sql/compiler.py index e8c11e34a..6152a28e7 100644 --- a/lib/sqlalchemy/sql/compiler.py +++ b/lib/sqlalchemy/sql/compiler.py @@ -2643,8 +2643,8 @@ class SQLCompiler(Compiled): return froms translate_select_structure = None - """if none None, should be a callable which accepts (select_stmt, **kw) - and returns a select object. this is used for structural changes + """if not ``None``, should be a callable which accepts ``(select_stmt, + **kw)`` and returns a select object. this is used for structural changes mostly to accommodate for LIMIT/OFFSET schemes """ diff --git a/lib/sqlalchemy/sql/ddl.py b/lib/sqlalchemy/sql/ddl.py index d3730b124..17e3be2da 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/dml.py b/lib/sqlalchemy/sql/dml.py index 4e8430450..81baa9f52 100644 --- a/lib/sqlalchemy/sql/dml.py +++ b/lib/sqlalchemy/sql/dml.py @@ -457,7 +457,7 @@ class ValuesBase(UpdateBase): @_generative def values(self, *args, **kwargs): - r"""specify a fixed VALUES clause for an INSERT statement, or the SET + r"""Specify a fixed VALUES clause for an INSERT statement, or the SET clause for an UPDATE. Note that the :class:`_expression.Insert` and @@ -685,8 +685,8 @@ class ValuesBase(UpdateBase): added to any existing RETURNING clause, provided that :meth:`.UpdateBase.returning` is not used simultaneously. The column values will then be available on the result using the - :attr:`_engine.CursorResult.returned_defaults` accessor as a dictionary - , + :attr:`_engine.CursorResult.returned_defaults` accessor as + a dictionary, referring to values keyed to the :class:`_schema.Column` object as well as its ``.key``. @@ -959,7 +959,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. """ @@ -1138,7 +1138,7 @@ class Update(DMLWhereBase, ValuesBase): a scalar-returning :func:`_expression.select` construct, etc. - when combining :func:`_expression.select` constructs within the + When combining :func:`_expression.select` constructs within the values clause of an :func:`_expression.update` construct, the subquery represented by the :func:`_expression.select` should be *correlated* to the diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py index 5cb411b85..af5eab257 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,14 +358,15 @@ 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. - \**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) @@ -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. @@ -724,12 +729,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". """ @@ -962,7 +967,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) @@ -981,14 +986,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. @@ -1681,7 +1686,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 ``:<param>`` + the text of the SQL statement to be created. Use ``:<param>`` to specify bind parameters; they will be compiled to their engine-specific format. @@ -1944,7 +1949,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. """ @@ -2357,7 +2362,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.:: @@ -2387,8 +2392,8 @@ class BooleanClauseList(ClauseList, ColumnElement): clause being combined using :func:`.and_`:: stmt = select([users_table]).\ - where(users_table.c.name == 'wendy').\ - where(users_table.c.enrolled == True) + 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 @@ -2791,7 +2796,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:: @@ -3158,8 +3163,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:: @@ -3171,9 +3176,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:: @@ -3203,8 +3207,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:: @@ -3216,8 +3220,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:: @@ -3770,7 +3774,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": @@ -3802,8 +3806,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/functions.py b/lib/sqlalchemy/sql/functions.py index 7b723f371..6fff26842 100644 --- a/lib/sqlalchemy/sql/functions.py +++ b/lib/sqlalchemy/sql/functions.py @@ -58,7 +58,7 @@ def register_function(identifier, fn, package="_default"): if identifier in reg: util.warn( "The GenericFunction '{}' is already registered and " - "is going to be overriden.".format(identifier) + "is going to be overridden.".format(identifier) ) reg[identifier] = fn @@ -125,7 +125,7 @@ class FunctionElement(Executable, ColumnElement, FromClause): @property def columns(self): - """The set of columns exported by this :class:`.FunctionElement`. + r"""The set of columns exported by this :class:`.FunctionElement`. Function objects currently have no result column names built in; this method returns a single-element column collection with @@ -951,7 +951,7 @@ class user(AnsiFunction): class array_agg(GenericFunction): - """support for the ARRAY_AGG function. + """Support for the ARRAY_AGG function. The ``func.array_agg(expr)`` construct returns an expression of type :class:`_types.ARRAY`. @@ -1011,7 +1011,7 @@ class OrderedSetAgg(GenericFunction): class mode(OrderedSetAgg): - """implement the ``mode`` ordered-set aggregate function. + """Implement the ``mode`` ordered-set aggregate function. This function must be used with the :meth:`.FunctionElement.within_group` modifier to supply a sort expression to operate upon. @@ -1026,7 +1026,7 @@ class mode(OrderedSetAgg): class percentile_cont(OrderedSetAgg): - """implement the ``percentile_cont`` ordered-set aggregate function. + """Implement the ``percentile_cont`` ordered-set aggregate function. This function must be used with the :meth:`.FunctionElement.within_group` modifier to supply a sort expression to operate upon. @@ -1044,7 +1044,7 @@ class percentile_cont(OrderedSetAgg): class percentile_disc(OrderedSetAgg): - """implement the ``percentile_disc`` ordered-set aggregate function. + """Implement the ``percentile_disc`` ordered-set aggregate function. This function must be used with the :meth:`.FunctionElement.within_group` modifier to supply a sort expression to operate upon. diff --git a/lib/sqlalchemy/sql/operators.py b/lib/sqlalchemy/sql/operators.py index 1bd63f285..85db88345 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 f6d8cfb1c..3df1c9f91 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`. """ @@ -2216,7 +2217,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. @@ -2345,7 +2346,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. @@ -2495,7 +2496,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. @@ -3330,7 +3331,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 @@ -3861,12 +3862,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`, @@ -4532,15 +4535,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 54f293967..bf6f20436 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. @@ -143,7 +143,7 @@ class ReturnsRows(roles.ReturnsRowsRole, ClauseElement): .. versionadded:: 1.4 - .. seealso: + .. seealso:: :attr:`_expression.FromClause.exported_columns` @@ -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,29 +202,29 @@ 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. :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 :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 + that is used for the operation. :meth:`_expression.ColumnCollection.corresponding_column` - implementation @@ -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` @@ -371,9 +372,9 @@ class HasHints(object): :meth:`_expression.Select.with_hint` - :meth:.`.Select.prefix_with` - generic SELECT prefixing which also - can suit some database-specific HINT syntaxes such as MySQL - optimizer hints + :meth:`_expression.Select.prefix_with` - generic SELECT prefixing + which also can suit some database-specific HINT syntaxes such as + MySQL optimizer hints """ return self.with_hint(None, text, dialect_name) @@ -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 @@ -656,9 +657,9 @@ class FromClause(roles.AnonymizedFromClauseRole, Selectable): .. versionadded:: 1.4 - .. seealso: + .. 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. @@ -703,24 +704,26 @@ 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 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 +795,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 +860,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 +925,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 +987,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 +1172,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 +1379,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 +1678,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 +1757,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 +1899,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 @@ -2048,8 +2051,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. @@ -2212,7 +2215,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 +2286,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 +2393,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 @@ -2398,9 +2401,9 @@ class SelectBase( .. versionadded:: 1.4 - .. seealso: + .. seealso:: - :attr:`expression.Selectable.exported_columns` + :attr:`_expression.Selectable.exported_columns` :attr:`_expression.FromClause.exported_columns` @@ -2436,7 +2439,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 +2483,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 +2506,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 +2517,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 +2538,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 +2840,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 +2944,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 +2964,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 +2986,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 +3013,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 +3021,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 +3053,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:: @@ -3111,12 +3115,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 +3135,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 +3152,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 +3169,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 +3186,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 +3203,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`. @@ -3318,7 +3322,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 +3341,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 +3367,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 +3386,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 +3406,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 +3427,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 +3693,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 +3701,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 +3859,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 +3869,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 +4039,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 <tablename>_<column>. The "c" + The format of the label is ``<tablename>_<column>``. The "c" collection of the resulting :class:`_expression.Select` object will use these names as well for targeting column members. @@ -4112,13 +4116,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 +4205,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 +4245,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 +4270,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 +4378,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 +4397,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 +4409,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 +4420,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 (<expressions>>)`` @@ -4432,7 +4441,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 +4484,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 +4545,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 +4745,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 +4794,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,41 +4811,43 @@ 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) 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) 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) @@ -4968,7 +4979,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 @@ -4980,7 +4991,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. """ @@ -4994,8 +5006,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. diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py index 9cd9d5058..5d7f80b1b 100644 --- a/lib/sqlalchemy/sql/sqltypes.py +++ b/lib/sqlalchemy/sql/sqltypes.py @@ -594,7 +594,7 @@ class Numeric(_LookupExpressionAdapter, TypeEngine): type that is explicitly known to be a decimal type (e.g. ``DECIMAL``, ``NUMERIC``, others) and not a floating point type (e.g. ``FLOAT``, ``REAL``, others). - If the database column on the server is in fact a floating-point type + If the database column on the server is in fact a floating-point type, such as ``FLOAT`` or ``REAL``, use the :class:`.Float` type or a subclass, otherwise numeric coercion between ``float``/``Decimal`` may or may not function as expected. @@ -1161,7 +1161,7 @@ class SchemaType(SchemaEventTarget): return self.metadata and self.metadata.bind or None def create(self, bind=None, checkfirst=False): - """Issue CREATE ddl for this type, if applicable.""" + """Issue CREATE DDL for this type, if applicable.""" if bind is None: bind = _bind_or_error(self) @@ -1170,7 +1170,7 @@ class SchemaType(SchemaEventTarget): t.create(bind=bind, checkfirst=checkfirst) def drop(self, bind=None, checkfirst=False): - """Issue DROP ddl for this type, if applicable.""" + """Issue DROP DDL for this type, if applicable.""" if bind is None: bind = _bind_or_error(self) @@ -1417,7 +1417,7 @@ class Enum(Emulated, String, SchemaType): default, the database value of the enumeration is used as the sorting function. - .. versionadded:: 1.3.8 + .. versionadded:: 1.3.8 @@ -1808,11 +1808,9 @@ class Boolean(Emulated, TypeEngine, SchemaType): appropriate naming convention; see :ref:`constraint_naming_conventions` for background. - .. versionchanged:: 1.4 - this flag now defaults to False, meaning - no CHECK constraint is generated for a non-native enumerated - type. - - + .. versionchanged:: 1.4 - this flag now defaults to False, meaning + no CHECK constraint is generated for a non-native enumerated + type. :param name: if a CHECK constraint is generated, specify the name of the constraint. @@ -2237,8 +2235,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 @@ -2273,7 +2271,7 @@ class JSON(Indexable, TypeEngine): self.none_as_null = none_as_null class JSONElementType(TypeEngine): - """common function for index / path elements in a JSON expression.""" + """Common function for index / path elements in a JSON expression.""" _integer = Integer() _string = String() @@ -2599,7 +2597,7 @@ class ARRAY(SchemaEventTarget, Indexable, Concatenable, TypeEngine): __visit_name__ = "ARRAY" zero_indexes = False - """if True, Python zero-based indexes should be interpreted as one-based + """If True, Python zero-based indexes should be interpreted as one-based on the SQL expression side.""" class Comparator(Indexable.Comparator, Concatenable.Comparator): diff --git a/lib/sqlalchemy/sql/traversals.py b/lib/sqlalchemy/sql/traversals.py index ed0bfa27a..8d01b7ff7 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 fe3634bad..83c7960ac 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 @@ -389,7 +389,7 @@ class TypeEngine(Traversible): """Return the corresponding type object from the underlying DB-API, if any. - This can be useful for calling ``setinputsizes()``, for example. + This can be useful for calling ``setinputsizes()``, for example. """ return None @@ -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 @@ -914,7 +914,7 @@ class TypeDecorator(SchemaEventTarget, TypeEngine): coerce_to_is_types = (util.NoneType,) """Specify those Python types which should be coerced at the expression level to "IS <constant>" when compared using ``==`` (and same for - ``IS NOT`` in conjunction with ``!=``. + ``IS NOT`` in conjunction with ``!=``). For most SQLAlchemy types, this includes ``NoneType``, as well as ``bool``. diff --git a/lib/sqlalchemy/sql/visitors.py b/lib/sqlalchemy/sql/visitors.py index 904702003..56d3c93b3 100644 --- a/lib/sqlalchemy/sql/visitors.py +++ b/lib/sqlalchemy/sql/visitors.py @@ -181,7 +181,7 @@ class InternalTraversal(util.with_metaclass(_InternalTraversalType, object)): ] Above, the :class:`.Case` class indicates its internal state as the - attributes named ``value``, ``whens``, and ``else\_``. They each + attributes named ``value``, ``whens``, and ``else_``. They each link to an :class:`.InternalTraversal` method which indicates the type of datastructure referred towards. @@ -330,7 +330,7 @@ class InternalTraversal(util.with_metaclass(_InternalTraversalType, object)): """ dp_dialect_options = symbol("DO") - """visit a dialect options structure.""" + """Visit a dialect options structure.""" dp_string_clauseelement_dict = symbol("CD") """Visit a dictionary of string keys to :class:`_expression.ClauseElement` @@ -380,8 +380,8 @@ class InternalTraversal(util.with_metaclass(_InternalTraversalType, object)): """ dp_table_hint_list = symbol("TH") - """Visit the ``_hints`` collection of a :class:`_expression.Select` object - . + """Visit the ``_hints`` collection of a :class:`_expression.Select` + object. """ @@ -400,17 +400,17 @@ class InternalTraversal(util.with_metaclass(_InternalTraversalType, object)): """ dp_dml_ordered_values = symbol("DML_OV") - """visit the values() ordered tuple list of an + """Visit the values() ordered tuple list of an :class:`_expression.Update` object.""" dp_dml_values = symbol("DML_V") - """visit the values() dictionary of a :class:`.ValuesBase` + """Visit the values() dictionary of a :class:`.ValuesBase` (e.g. Insert or Update) object. """ dp_dml_multi_values = symbol("DML_MV") - """visit the values() multi-valued list of dictionaries of an + """Visit the values() multi-valued list of dictionaries of an :class:`_expression.Insert` object. """ @@ -479,14 +479,14 @@ class ExternalTraversal(object): return meth(obj, **kw) def iterate(self, obj): - """traverse the given expression structure, returning an iterator + """Traverse the given expression structure, returning an iterator of all elements. """ return iterate(obj, self.__traverse_options__) def traverse(self, obj): - """traverse and visit the given expression structure.""" + """Traverse and visit the given expression structure.""" return traverse(obj, self.__traverse_options__, self._visitor_dict) @@ -501,7 +501,7 @@ class ExternalTraversal(object): @property def visitor_iterator(self): - """iterate through this visitor and each 'chained' visitor.""" + """Iterate through this visitor and each 'chained' visitor.""" v = self while v: @@ -509,9 +509,9 @@ class ExternalTraversal(object): v = getattr(v, "_next", None) def chain(self, visitor): - """'chain' an additional ClauseVisitor onto this ClauseVisitor. + """'Chain' an additional ClauseVisitor onto this ClauseVisitor. - the chained visitor will receive all visit events after this one. + The chained visitor will receive all visit events after this one. """ tail = list(self.visitor_iterator)[-1] @@ -537,7 +537,7 @@ class CloningExternalTraversal(ExternalTraversal): return [self.traverse(x) for x in list_] def traverse(self, obj): - """traverse and visit the given expression structure.""" + """Traverse and visit the given expression structure.""" return cloned_traverse( obj, self.__traverse_options__, self._visitor_dict @@ -554,7 +554,7 @@ class ReplacingExternalTraversal(CloningExternalTraversal): """ def replace(self, elem): - """receive pre-copied elements during a cloning traversal. + """Receive pre-copied elements during a cloning traversal. If the method returns a new element, the element is used instead of creating a simple copy of the element. Traversal @@ -563,7 +563,7 @@ class ReplacingExternalTraversal(CloningExternalTraversal): return None def traverse(self, obj): - """traverse and visit the given expression structure.""" + """Traverse and visit the given expression structure.""" def replace(elem): for v in self.visitor_iterator: @@ -583,9 +583,9 @@ ReplacingCloningVisitor = ReplacingExternalTraversal def iterate(obj, opts=util.immutabledict()): - r"""traverse the given expression structure, returning an iterator. + r"""Traverse the given expression structure, returning an iterator. - traversal is configured to be breadth-first. + Traversal is configured to be breadth-first. The central API feature used by the :func:`.visitors.iterate` function is the @@ -618,7 +618,7 @@ def iterate(obj, opts=util.immutabledict()): def traverse_using(iterator, obj, visitors): - """visit the given expression structure using the given iterator of + """Visit the given expression structure using the given iterator of objects. :func:`.visitors.traverse_using` is usually called internally as the result @@ -650,7 +650,7 @@ def traverse_using(iterator, obj, visitors): def traverse(obj, opts, visitors): - """traverse and visit the given expression structure using the default + """Traverse and visit the given expression structure using the default iterator. e.g.:: @@ -683,7 +683,7 @@ def traverse(obj, opts, visitors): def cloned_traverse(obj, opts, visitors): - """clone the given expression structure, allowing modifications by + """Clone the given expression structure, allowing modifications by visitors. Traversal usage is the same as that of :func:`.visitors.traverse`. @@ -738,14 +738,14 @@ def cloned_traverse(obj, opts, visitors): def replacement_traverse(obj, opts, replace): - """clone the given expression structure, allowing element + """Clone the given expression structure, allowing element replacement by a given replacement function. This function is very similar to the :func:`.visitors.cloned_traverse` function, except instead of being passed a dictionary of visitors, all elements are unconditionally passed into the given replace function. The replace function then has the option to return an entirely new object - which will replace the one given. if it returns ``None``, then the object + which will replace the one given. If it returns ``None``, then the object is kept in place. The difference in usage between :func:`.visitors.cloned_traverse` and diff --git a/lib/sqlalchemy/testing/plugin/pytestplugin.py b/lib/sqlalchemy/testing/plugin/pytestplugin.py index 9dc40c9fe..015598952 100644 --- a/lib/sqlalchemy/testing/plugin/pytestplugin.py +++ b/lib/sqlalchemy/testing/plugin/pytestplugin.py @@ -371,7 +371,7 @@ class PytestFixtureFunctions(plugin_base.FixtureFunctions): } def combinations(self, *arg_sets, **kw): - """facade for pytest.mark.paramtrize. + """Facade for pytest.mark.parametrize. Automatically derives argument names from the callable which in our case is always a method on a class with positional arguments. diff --git a/lib/sqlalchemy/testing/profiling.py b/lib/sqlalchemy/testing/profiling.py index 16215dcd5..c50ce1e15 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 diff --git a/test/base/test_result.py b/test/base/test_result.py index ce0e7b945..bacf09d39 100644 --- a/test/base/test_result.py +++ b/test/base/test_result.py @@ -427,7 +427,7 @@ class ResultTest(fixtures.TestBase): eq_(result.all(), []) def test_one_unique(self): - # assert that one() counts rows after uniquness has been applied. + # assert that one() counts rows after uniqueness has been applied. # this would raise if we didnt have unique result = self._fixture(data=[(1, 1, 1), (1, 1, 1)]) @@ -444,7 +444,7 @@ class ResultTest(fixtures.TestBase): assert_raises(exc.MultipleResultsFound, result.unique().one) def test_one_unique_mapping(self): - # assert that one() counts rows after uniquness has been applied. + # assert that one() counts rows after uniqueness has been applied. # this would raise if we didnt have unique result = self._fixture(data=[(1, 1, 1), (1, 1, 1)]) diff --git a/test/ext/test_automap.py b/test/ext/test_automap.py index 25c43f173..b022f0357 100644 --- a/test/ext/test_automap.py +++ b/test/ext/test_automap.py @@ -107,8 +107,8 @@ class AutomapTest(fixtures.MappedTest): """ The underlying reflect call accepts an optional schema argument. This is for determining which database schema to load. - This test verifies that prepare can accept an optiona schema argument - and pass it to reflect. + This test verifies that prepare can accept an optional schema + argument and pass it to reflect. """ Base = automap_base(metadata=self.metadata) engine_mock = Mock() diff --git a/test/orm/test_assorted_eager.py b/test/orm/test_assorted_eager.py index df3917712..dea7b60ec 100644 --- a/test/orm/test_assorted_eager.py +++ b/test/orm/test_assorted_eager.py @@ -1,6 +1,6 @@ """Exercises for eager loading. -Derived from mailing list-reported problems and trac tickets. +Derived from mailing list-reported problems and issue tracker issues. These are generally very old 0.1-era tests and at some point should be cleaned up and modernized. diff --git a/test/orm/test_bind.py b/test/orm/test_bind.py index 8e6d73ca4..bef06c390 100644 --- a/test/orm/test_bind.py +++ b/test/orm/test_bind.py @@ -301,7 +301,7 @@ class BindIntegrationTest(_fixtures.FixtureTest): ), ( lambda User: future_select(1).where(User.name == "ed"), - # no mapper for this one becuase the plugin is not "orm" + # no mapper for this one because the plugin is not "orm" lambda User: {"clause": mock.ANY}, "e1", ), diff --git a/test/orm/test_deprecations.py b/test/orm/test_deprecations.py index 2e19b9435..4e9f50661 100644 --- a/test/orm/test_deprecations.py +++ b/test/orm/test_deprecations.py @@ -1329,7 +1329,7 @@ class InstancesTest(QueryTest, AssertsCompiledSQL): def go(): with testing.expect_deprecated( r"Using the Query.instances\(\) method without a context", - "Retreiving row values using Column objects with only " + "Retrieving row values using Column objects with only " "matching names", ): result = list( @@ -1442,7 +1442,7 @@ class InstancesTest(QueryTest, AssertsCompiledSQL): r"Using the Query.instances\(\) method without a context", r"Passing a string name for the 'alias' argument to " r"'contains_eager\(\)` is deprecated", - "Retreiving row values using Column objects with only " + "Retrieving row values using Column objects with only " "matching names", ): result = list( @@ -1512,7 +1512,7 @@ class InstancesTest(QueryTest, AssertsCompiledSQL): r"Using the Query.instances\(\) method without a context", r"Passing a string name for the 'alias' argument to " r"'contains_eager\(\)` is deprecated", - "Retreiving row values using Column objects with only " + "Retrieving row values using Column objects with only " "matching names", ): result = list( diff --git a/test/sql/test_compare.py b/test/sql/test_compare.py index 6aaafc716..694410134 100644 --- a/test/sql/test_compare.py +++ b/test/sql/test_compare.py @@ -609,7 +609,7 @@ class CoreFixtures(object): dont_compare_values_fixtures = [ lambda: ( - # note the in_(...) all have different column names becuase + # note the in_(...) all have different column names because # otherwise all IN expressions would compare as equivalent column("x").in_(random_choices(range(10), k=3)), column("y").in_( diff --git a/test/sql/test_deprecations.py b/test/sql/test_deprecations.py index 635f009f6..3cc9a06ed 100644 --- a/test/sql/test_deprecations.py +++ b/test/sql/test_deprecations.py @@ -802,7 +802,7 @@ class KeyTargetingTest(fixtures.TablesTest): not_in_(bar.c.content_type, row) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): in_(sql.column("content_type"), row) @@ -813,7 +813,7 @@ class KeyTargetingTest(fixtures.TablesTest): not_in_(content.c.type, row) not_in_(bar.c.content_type, row) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): in_(sql.column("content_type"), row) @@ -830,12 +830,12 @@ class KeyTargetingTest(fixtures.TablesTest): row = connection.execute(stmt).first() with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): in_(keyed2.c.a, row) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): in_(keyed2.c.b, row) @@ -848,12 +848,12 @@ class KeyTargetingTest(fixtures.TablesTest): row = connection.execute(stmt).first() with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): in_(a, row) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): in_(b, row) @@ -869,33 +869,33 @@ class KeyTargetingTest(fixtures.TablesTest): row = connection.execute(stmt).first() with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): in_(keyed2.c.a, row) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): in_(keyed2.c.b, row) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): in_(a, row) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): in_(b, row) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names", "The SelectBase.c and SelectBase.columns", ): in_(stmt.c.a, row) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names", "The SelectBase.c and SelectBase.columns", ): @@ -913,23 +913,23 @@ class KeyTargetingTest(fixtures.TablesTest): row = connection.execute(stmt).first() with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): in_(keyed2.c.a, row) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): in_(keyed2.c.b, row) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names", "The SelectBase.c and SelectBase.columns", ): in_(stmt.c.keyed2_a, row) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names", "The SelectBase.c and SelectBase.columns", ): @@ -946,23 +946,23 @@ class KeyTargetingTest(fixtures.TablesTest): row = connection.execute(stmt).first() with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): in_(keyed2.c.a, row) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): in_(keyed2.c.b, row) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names", "The SelectBase.c and SelectBase.columns", ): in_(stmt.c.keyed2_a, row) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names", "The SelectBase.c and SelectBase.columns", ): @@ -1019,10 +1019,10 @@ class CursorResultTest(fixtures.TablesTest): users = self.tables.users with testing.expect_deprecated( - # "Retreiving row values using Column objects " - # "with only matching names", - # "Using non-integer/slice indices on Row is " - # "deprecated and will be removed in version 2.0", + "Retrieving row values using Column objects " + "with only matching names", + "Using non-integer/slice indices on Row is " + "deprecated and will be removed in version 2.0", ): # this will create column() objects inside # the select(), these need to match on name anyway @@ -1036,14 +1036,14 @@ class CursorResultTest(fixtures.TablesTest): r._keymap.pop(users.c.user_id) # reset lookup with testing.expect_deprecated( - # "Retreiving row values using Column objects " - # "with only matching names" + "Retrieving row values using Column objects " + "with only matching names" ): eq_(r._mapping[users.c.user_id], 2) with testing.expect_deprecated( - # "Retreiving row values using Column objects " - # "with only matching names" + "Retrieving row values using Column objects " + "with only matching names" ): eq_(r._mapping[users.c.user_name], "jack") @@ -1053,7 +1053,7 @@ class CursorResultTest(fixtures.TablesTest): with testing.expect_deprecated( "Using non-integer/slice indices on Row is deprecated " "and will be removed in version 2.0", - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names", ): r = connection.execute( @@ -1064,7 +1064,7 @@ class CursorResultTest(fixtures.TablesTest): r._keymap.pop(users.c.user_id) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): eq_(r._mapping[users.c.user_id], 2) @@ -1072,14 +1072,14 @@ class CursorResultTest(fixtures.TablesTest): with testing.expect_deprecated( "Using non-integer/slice indices on Row is deprecated " "and will be removed in version 2.0", - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names", ): eq_(r[users.c.user_name], "jack") r._keymap.pop(users.c.user_name) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): eq_(r._mapping[users.c.user_name], "jack") @@ -1095,7 +1095,7 @@ class CursorResultTest(fixtures.TablesTest): in_(content.c.type, row._mapping) not_in_(bar.c.content_type, row) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): in_(sql.column("content_type"), row) @@ -1104,7 +1104,7 @@ class CursorResultTest(fixtures.TablesTest): select([content.c.type.label("content_type")]) ).first() with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): in_(content.c.type, row) @@ -1112,7 +1112,7 @@ class CursorResultTest(fixtures.TablesTest): not_in_(bar.c.content_type, row) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): in_(sql.column("content_type"), row) @@ -1126,7 +1126,7 @@ class CursorResultTest(fixtures.TablesTest): not_in_(bar.c.content_type, row) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): in_(sql.column("content_type"), row) @@ -1156,27 +1156,27 @@ class CursorResultTest(fixtures.TablesTest): if pickle: with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "from a row that was unpickled" ): eq_(result[0]._mapping[users.c.user_id], 7) result[0]._keymap.pop(users.c.user_id) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "from a row that was unpickled" ): eq_(result[0]._mapping[users.c.user_id], 7) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "from a row that was unpickled" ): eq_(result[0]._mapping[users.c.user_name], "jack") result[0]._keymap.pop(users.c.user_name) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "from a row that was unpickled" ): eq_(result[0]._mapping[users.c.user_name], "jack") @@ -1196,14 +1196,14 @@ class CursorResultTest(fixtures.TablesTest): # causing 'user_id' to match when use_labels wasn't # used. with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "from a row that was unpickled" ): eq_(result[0]._mapping[addresses.c.user_id], 7) result[0]._keymap.pop(addresses.c.user_id) with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "from a row that was unpickled" ): eq_(result[0]._mapping[addresses.c.user_id], 7) @@ -1395,7 +1395,7 @@ class PositionalTextTest(fixtures.TablesTest): row = result.first() with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): eq_(row._mapping[text1.c.a], "a1") @@ -1420,7 +1420,7 @@ class PositionalTextTest(fixtures.TablesTest): # key fallback rules still match this to a column # unambiguously based on its name with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): eq_(row._mapping[text1.c.a], "a1") @@ -1428,7 +1428,7 @@ class PositionalTextTest(fixtures.TablesTest): # key fallback rules still match this to a column # unambiguously based on its name with testing.expect_deprecated( - "Retreiving row values using Column objects " + "Retrieving row values using Column objects " "with only matching names" ): eq_(row._mapping[text1.c.d], "d1") diff --git a/test/sql/test_functions.py b/test/sql/test_functions.py index b37cb15b7..e0a0dd8a5 100644 --- a/test/sql/test_functions.py +++ b/test/sql/test_functions.py @@ -260,7 +260,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL): with expect_warnings( "The GenericFunction 'replaceable_func' is already registered and " - "is going to be overriden.", + "is going to be overridden.", regex=False, ): @@ -283,7 +283,7 @@ class CompileTest(fixtures.TestBase, AssertsCompiledSQL): with expect_warnings( "The GenericFunction 'replaceable_func' is already registered and " - "is going to be overriden.", + "is going to be overridden.", regex=False, ): |