From 0df9759b73cb20818a35bd182697fac36dda3484 Mon Sep 17 00:00:00 2001 From: Eric Hanchrow Date: Wed, 20 Sep 2023 17:02:08 -0400 Subject: [PATCH] Revise / rewrite sentences that use the phrase "referred towards" Comments by Mike : "Referred towards" is not correct English and can be replaced directly with "referred to". However, this then introduces a dangling preposition to sentences which I don't think is appropriate for this style of writing. So instead, use phrases like "known as", "references", "to which X refers". To help me identify dangling prepositions I made use of ChatGPT, here's the log of how that transpired: https://chat.openai.com/share/60d42ff4-c1ac-4232-893a-415c2b6d7320 Co-authored-by: Mike Bayer Closes: #10210 Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/10210 Pull-request-sha: 5d30e79c14fe78996d332fefd4bae36d76626ff4 Change-Id: Ib6a98e5be441f5b25d3929a2efb7d873bcfef98e --- doc/build/changelog/changelog_11.rst | 16 ++++---- doc/build/changelog/changelog_13.rst | 27 ++++++------- doc/build/changelog/changelog_14.rst | 34 ++++++++-------- doc/build/changelog/changelog_20.rst | 2 +- doc/build/changelog/migration_13.rst | 39 +++++++++---------- doc/build/changelog/migration_20.rst | 4 +- doc/build/core/connections.rst | 6 +-- doc/build/core/metadata.rst | 6 +-- doc/build/core/reflection.rst | 2 +- doc/build/errors.rst | 6 +-- doc/build/glossary.rst | 2 +- doc/build/orm/basic_relationships.rst | 10 ++--- doc/build/orm/composites.rst | 2 +- doc/build/orm/declarative_tables.rst | 4 +- doc/build/orm/inheritance.rst | 2 +- doc/build/orm/join_conditions.rst | 2 +- doc/build/orm/mapping_styles.rst | 2 +- doc/build/orm/queryguide/inheritance.rst | 4 +- doc/build/orm/queryguide/select.rst | 4 +- doc/build/orm/quickstart.rst | 4 +- doc/build/tutorial/data_select.rst | 10 ++--- doc/build/tutorial/dbapi_transactions.rst | 4 +- doc/build/tutorial/metadata.rst | 6 +-- doc/build/tutorial/orm_related_objects.rst | 2 +- lib/sqlalchemy/dialects/postgresql/base.py | 6 +-- .../dialects/postgresql/psycopg2.py | 2 +- lib/sqlalchemy/dialects/sqlite/base.py | 2 +- lib/sqlalchemy/engine/base.py | 2 +- lib/sqlalchemy/engine/interfaces.py | 2 +- lib/sqlalchemy/ext/hybrid.py | 2 +- lib/sqlalchemy/orm/mapper.py | 4 +- lib/sqlalchemy/orm/relationships.py | 5 ++- lib/sqlalchemy/orm/util.py | 2 +- lib/sqlalchemy/sql/elements.py | 2 +- lib/sqlalchemy/sql/selectable.py | 2 +- lib/sqlalchemy/sql/visitors.py | 13 ++++--- 36 files changed, 124 insertions(+), 120 deletions(-) diff --git a/doc/build/changelog/changelog_11.rst b/doc/build/changelog/changelog_11.rst index fe2a02477c..00a17896c8 100644 --- a/doc/build/changelog/changelog_11.rst +++ b/doc/build/changelog/changelog_11.rst @@ -207,14 +207,14 @@ :tickets: 4124 :versions: 1.2.0 - Fixed bug where a descriptor that is elsewhere a mapped column - or relationship within a hierarchy based on :class:`.AbstractConcreteBase` - would be referred towards during a refresh operation, causing an error - as the attribute is not mapped as a mapper property. - A similar issue can arise for other attributes like the "type" column - added by :class:`.AbstractConcreteBase` if the class fails to include - "concrete=True" in its mapper, however the check here should also - prevent that scenario from causing a problem. + Fixed a bug where a descriptor, which is a mapped column or a + relationship elsewhere in a hierarchy based on + :class:`.AbstractConcreteBase`, would be referenced during a refresh + operation, leading to an error since the attribute is not mapped as a + mapper property. A similar issue can arise for other attributes + like the "type" column added by :class:`.AbstractConcreteBase` if the + class fails to include "concrete=True" in its mapper, however the check + here should also prevent that scenario from causing a problem. .. change:: 4006 :tags: bug, postgresql diff --git a/doc/build/changelog/changelog_13.rst b/doc/build/changelog/changelog_13.rst index 6039499692..462511f3fd 100644 --- a/doc/build/changelog/changelog_13.rst +++ b/doc/build/changelog/changelog_13.rst @@ -2744,19 +2744,20 @@ :tags: bug, sql :tickets: 4730 - Fixed a series of quoting issues which all stemmed from the concept of the - :func:`_expression.literal_column` construct, which when being "proxied" through a - subquery to be referred towards by a label that matches its text, the label - would not have quoting rules applied to it, even if the string in the - :class:`.Label` were set up as a :class:`.quoted_name` construct. Not - applying quoting to the text of the :class:`.Label` is a bug because this - text is strictly a SQL identifier name and not a SQL expression, and the - string should not have quotes embedded into it already unlike the - :func:`_expression.literal_column` which it may be applied towards. The existing - behavior of a non-labeled :func:`_expression.literal_column` being propagated as is on - the outside of a subquery is maintained in order to help with manual - quoting schemes, although it's not clear if valid SQL can be generated for - such a construct in any case. + Addressed a range of quoting issues originating from the use of the + :func:`_expression.literal_column`` construct. When this construct is + "proxied" through a subquery and referred to by a label matching its + text, the label does not have quoting rules applied to it, even if the + string in the :class:`.Label` was set up using a :class:`.quoted_name`` + construct. Not applying quoting to the text of the :class:`.Label` is a + bug because this text is strictly a SQL identifier name and not a SQL + expression, and the string should not have quotes embedded into it + already unlike the :func:`_expression.literal_column` which it may be + applied towards. The existing behavior of a non-labeled + :func:`_expression.literal_column` being propagated as is on the + outside of a subquery is maintained in order to help with manual + quoting schemes, although it's not clear if valid SQL can be generated + for such a construct in any case. .. changelog:: :version: 1.3.4 diff --git a/doc/build/changelog/changelog_14.rst b/doc/build/changelog/changelog_14.rst index 8b68b04a81..709e0e9780 100644 --- a/doc/build/changelog/changelog_14.rst +++ b/doc/build/changelog/changelog_14.rst @@ -1719,11 +1719,12 @@ This document details individual issue-level changes made throughout Added new parameter :paramref:`.FunctionElement.table_valued.joins_implicitly`, for the - :meth:`.FunctionElement.table_valued` construct. This parameter indicates - that the given table-valued function implicitly joins to the table it - refers towards, essentially disabling the "from linting" feature, i.e. the - "cartesian product" warning, from taking effect due to the presence of this - parameter. May be used for functions such as ``func.json_each()``. + :meth:`.FunctionElement.table_valued` construct. This parameter + indicates that the table-valued function provided will automatically + perform an implicit join with the referenced table. This effectively + disables the 'from linting' feature, such as the 'cartesian product' + warning, from triggering due to the presence of this parameter. May be + used for functions such as ``func.json_each()``. .. change:: :tags: usecase, engine @@ -3990,16 +3991,16 @@ This document details individual issue-level changes made throughout Fixed regression in :mod:`sqlalchemy.ext.automap` extension such that the use case of creating an explicit mapped class to a table that is also the :paramref:`_orm.relationship.secondary` element of a - :func:`_orm.relationship` that automap will be generating would emit the - "overlaps" warnings introduced in 1.4 and discussed at :ref:`error_qzyx`. - While generating this case from automap is still subject to the same - caveats that the "overlaps" warning refers towards, as automap is intended - for more ad-hoc use cases, the condition which produces the warning is - disabled when a many-to-many relationship with this particular pattern is + :func:`_orm.relationship` that automap will be generating would emit + the "overlaps" warnings introduced in 1.4 and discussed at + :ref:`error_qzyx`. While generating this case from automap is still + subject to the same caveats mentioned in the 'overlaps' warning, + since automap is primarily intended for more ad-hoc + use cases, the condition triggering the warning is disabled when a + many-to-many relationship with this specific pattern is generated. - .. change:: :tags: bug, regression, orm :tickets: 6678 @@ -5056,7 +5057,7 @@ This document details individual issue-level changes made throughout Fixed a critical performance issue where the traversal of a :func:`_sql.select` construct would traverse a repetitive product of the - represented FROM clauses as they were each referred towards by columns in + represented FROM clauses as they were each referenced by columns in the columns clause; for a series of nested subqueries with lots of columns this could cause a large delay and significant memory growth. This traversal is used by a wide variety of SQL and ORM functions, including by @@ -6518,8 +6519,9 @@ This document details individual issue-level changes made throughout with an emphasis on its use within the :func:`_orm.with_loader_criteria` feature where it is most prominently used [ticket:5760]: - * fixed issue where boolean True/False values referred towards in the - closure variables of the lambda would cause failures [ticket:5763] + * Fixed the issue where boolean True/False values, which were referred + to in the closure variables of the lambda, would cause failures. + [ticket:5763] * Repaired a non-working detection for Python functions embedded in the lambda that produce bound values; this case is likely not supportable @@ -6962,7 +6964,7 @@ This document details individual issue-level changes made throughout syntaxes supported by PostgreSQL, one of the most commonly requested features. Table valued functions are SQL functions that return lists of values or rows, and are prevalent in PostgreSQL in the area of JSON - functions, where the "table value" is commonly referred towards as the + functions, where the "table value" is commonly referred to as the "record" datatype. Table valued functions are also supported by Oracle and SQL Server. diff --git a/doc/build/changelog/changelog_20.rst b/doc/build/changelog/changelog_20.rst index 45bf8e3511..b1d7d79185 100644 --- a/doc/build/changelog/changelog_20.rst +++ b/doc/build/changelog/changelog_20.rst @@ -2564,7 +2564,7 @@ Fixed regression related to the implementation for the new "insertmanyvalues" feature where an internal ``TypeError`` would occur in - arrangements where a :func:`_sql.insert` would be referred towards inside + arrangements where a :func:`_sql.insert` would be referenced inside of another :func:`_sql.insert` via a CTE; made additional repairs for this use case for positional dialects such as asyncpg when using "insertmanyvalues". diff --git a/doc/build/changelog/migration_13.rst b/doc/build/changelog/migration_13.rst index f7ce653f47..a86e5bc089 100644 --- a/doc/build/changelog/migration_13.rst +++ b/doc/build/changelog/migration_13.rst @@ -150,7 +150,7 @@ so that they did not conflict with the existing columns mapped to ``B``, as well as it was necessary to define a new primary key. With the new approach, all of this verbosity goes away, and the additional -columns are referred towards directly when making the relationship:: +columns are referenced directly when making the relationship:: j = join(B, D, D.b_id == B.id).join(C, C.id == D.c_id) @@ -452,27 +452,26 @@ AssociationProxy stores class-specific state on a per-class basis The :class:`.AssociationProxy` object makes lots of decisions based on the parent mapped class it is associated with. While the -:class:`.AssociationProxy` historically began as a relatively simple "getter", -it became apparent early on that it also needed to make decisions about what -kind of attribute it is referring towards, e.g. scalar or collection, mapped -object or simple value, and similar. To achieve this, it needs to inspect the -mapped attribute or other descriptor or attribute that it refers towards, as -referenced from its parent class. However in Python descriptor mechanics, a -descriptor only learns about its "parent" class when it is accessed in the -context of that class, such as calling ``MyClass.some_descriptor``, which calls -the ``__get__()`` method which passes in the class. The +:class:`.AssociationProxy` historically began as a relatively simple 'getter,' +it became apparent early on that it also needed to make decisions regarding the +kind of attribute to which it refers—such as scalar or collection, mapped +object or simple value, and so on. To achieve this, it needs to inspect the +mapped attribute or other referring descriptor or attribute, as referenced from +its parent class. However in Python descriptor mechanics, a descriptor only +learns about its "parent" class when it is accessed in the context of that +class, such as calling ``MyClass.some_descriptor``, which calls the +``__get__()`` method which passes in the class. The :class:`.AssociationProxy` object would therefore store state that is specific to that class, but only once this method were called; trying to inspect this -state ahead of time without first accessing the :class:`.AssociationProxy` -as a descriptor would raise an error. Additionally, it would assume that -the first class to be seen by ``__get__()`` would be the only parent class it -needed to know about. This is despite the fact that if a particular class -has inheriting subclasses, the association proxy is really working -on behalf of more than one parent class even though it was not explicitly -re-used. While even with this shortcoming, the association proxy would -still get pretty far with its current behavior, it still leaves shortcomings -in some cases as well as the complex problem of determining the best "owner" -class. +state ahead of time without first accessing the :class:`.AssociationProxy` as a +descriptor would raise an error. Additionally, it would assume that the first +class to be seen by ``__get__()`` would be the only parent class it needed to +know about. This is despite the fact that if a particular class has inheriting +subclasses, the association proxy is really working on behalf of more than one +parent class even though it was not explicitly re-used. While even with this +shortcoming, the association proxy would still get pretty far with its current +behavior, it still leaves shortcomings in some cases as well as the complex +problem of determining the best "owner" class. These problems are now solved in that :class:`.AssociationProxy` no longer modifies its own internal state when ``__get__()`` is called; instead, a new diff --git a/doc/build/changelog/migration_20.rst b/doc/build/changelog/migration_20.rst index a830122554..b7d7dbcdcb 100644 --- a/doc/build/changelog/migration_20.rst +++ b/doc/build/changelog/migration_20.rst @@ -1525,7 +1525,7 @@ following the table, and may include additional notes not summarized here. ) # or - + session.scalar( select(func.count(User.id)) ) @@ -2007,7 +2007,7 @@ The new approach makes use of the :func:`_orm.aliased` construct so that the ORM internals don't need to guess which entities and columns should be adapted and in what way; in the example above, the ``ua`` and ``aa`` objects, both of which are :class:`_orm.AliasedClass` instances, provide to the internals -an unambiguous marker as to where the subquery should be referred towards +an unambiguous marker as to where the subquery should be referenced as well as what entity column or relationship is being considered for a given component of the query. diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst index 89d6df321d..994daa8f54 100644 --- a/doc/build/core/connections.rst +++ b/doc/build/core/connections.rst @@ -107,7 +107,7 @@ to the transaction ending, the :class:`_engine.Connection` waits for the :meth:`_engine.Connection.execute` method to be called again, at which point it autobegins again. -This calling style is referred towards as **commit as you go**, and is +This calling style is known as **commit as you go**, and is illustrated in the example below:: with engine.connect() as connection: @@ -159,7 +159,7 @@ Begin Once ~~~~~~~~~~ The :class:`_engine.Connection` object provides a more explicit transaction -management style referred towards as **begin once**. In contrast to "commit as +management style known as **begin once**. In contrast to "commit as you go", "begin once" allows the start point of the transaction to be stated explicitly, and allows that the transaction itself may be framed out as a context manager @@ -2199,7 +2199,7 @@ given exceeds a fixed limit, or when the total number of bound parameters to be rendered in a single INSERT statement exceeds a fixed limit (the two fixed limits are separate), multiple INSERT statements will be invoked within the scope of a single :meth:`_engine.Connection.execute` call, each of which -accommodate for a portion of the parameter dictionaries, referred towards as a +accommodate for a portion of the parameter dictionaries, known as a "batch". The number of parameter dictionaries represented within each "batch" is then known as the "batch size". For example, a batch size of 500 means that each INSERT statement emitted will INSERT at most 500 rows. diff --git a/doc/build/core/metadata.rst b/doc/build/core/metadata.rst index 4966970562..1a93382885 100644 --- a/doc/build/core/metadata.rst +++ b/doc/build/core/metadata.rst @@ -301,11 +301,11 @@ Server) or even names that refer to alternate database files (SQLite ATTACH) or remote servers (Oracle DBLINK with synonyms). What all of the above approaches have (mostly) in common is that there's a way -of referring to this alternate set of tables using a string name. SQLAlchemy +of referencing this alternate set of tables using a string name. SQLAlchemy refers to this name as the **schema name**. Within SQLAlchemy, this is nothing more than a string name which is associated with a :class:`_schema.Table` object, and is then rendered into SQL statements in a manner appropriate to the -target database such that the table is referred towards in its remote "schema", +target database such that the table is referenced in its remote "schema", whatever mechanism that is on the target database. The "schema" name may be associated directly with a :class:`_schema.Table` @@ -328,7 +328,7 @@ schema names on a per-connection or per-statement basis. "database" that typically has a single "owner". Within this database there can be any number of "schemas" which then contain the actual table objects. - A table within a specific schema is referred towards explicitly using the + A table within a specific schema is referenced explicitly using the syntax ".". Contrast this to an architecture such as that of MySQL, where there are only "databases", however SQL statements can refer to multiple databases at once, using the same syntax except it diff --git a/doc/build/core/reflection.rst b/doc/build/core/reflection.rst index 1ff517510e..4f3805b7ed 100644 --- a/doc/build/core/reflection.rst +++ b/doc/build/core/reflection.rst @@ -215,7 +215,7 @@ schemas will not require that the schema name be present (while at the same time it's also perfectly fine if the schema name *is* present). Since most relational databases therefore have the concept of a particular -table object which can be referred towards both in a schema-qualified way, as +table object which can be referenced both in a schema-qualified way, as well as an "implicit" way where no schema is present, this presents a complexity for SQLAlchemy's reflection feature. Reflecting a table in diff --git a/doc/build/errors.rst b/doc/build/errors.rst index bcfb43efb7..48fdedeace 100644 --- a/doc/build/errors.rst +++ b/doc/build/errors.rst @@ -678,7 +678,7 @@ construct:: The above pattern also allows an arbitrary selectable, such as a Core :class:`_sql.Join` or :class:`_sql.Alias` object, however there is no automatic adaptation of this element, meaning the -Core element would need to be referred towards directly:: +Core element would need to be referenced directly:: a1 = Address.__table__.alias() @@ -783,7 +783,7 @@ Above, the SQL selects FROM the ``employee`` table, representing the ``Employee`` entity in the query. It then joins to a right-nested join of ``employee AS employee_1 JOIN manager AS manager_1``, where the ``employee`` table is stated again, except as an anonymous alias ``employee_1``. This is the -"automatic generation of an alias" that the warning message refers towards. +'automatic generation of an alias' to which the warning message refers. When SQLAlchemy loads ORM rows that each contain an ``Employee`` and a ``Manager`` object, the ORM must adapt rows from what above is the @@ -1196,7 +1196,7 @@ relationship X will copy column Q to column P, which conflicts with relationship This warning refers to the case when two or more relationships will write data to the same columns on flush, but the ORM does not have any means of coordinating these relationships together. Depending on specifics, the solution -may be that two relationships need to be referred towards one another using +may be that two relationships need to be referenced by one another using :paramref:`_orm.relationship.back_populates`, or that one or more of the relationships should be configured with :paramref:`_orm.relationship.viewonly` to prevent conflicting writes, or sometimes that the configuration is fully diff --git a/doc/build/glossary.rst b/doc/build/glossary.rst index 21c8a6ebfb..c3e49cacf6 100644 --- a/doc/build/glossary.rst +++ b/doc/build/glossary.rst @@ -304,7 +304,7 @@ Glossary aggregate the single row from each INSERT execution together. To overcome this limitation, SQLAlchemy as of the 2.0 series implements - an alternative form of "executemany" which is referred towards as + an alternative form of "executemany" which is known as :ref:`engine_insertmanyvalues`. This feature makes use of ``cursor.execute()`` to invoke an INSERT statement that will proceed with multiple parameter sets in one round trip, thus producing the same diff --git a/doc/build/orm/basic_relationships.rst b/doc/build/orm/basic_relationships.rst index 91353681ed..bbeac0858c 100644 --- a/doc/build/orm/basic_relationships.rst +++ b/doc/build/orm/basic_relationships.rst @@ -945,10 +945,10 @@ the :func:`_orm.relationship` construct:: ) These string names are resolved into classes in the mapper resolution stage, -which is an internal process that occurs typically after all mappings have -been defined and is normally triggered by the first usage of the mappings -themselves. The :class:`_orm.registry` object is the container in which -these names are stored and resolved to the mapped classes they refer towards. +which is an internal process that occurs typically after all mappings have been +defined and is normally triggered by the first usage of the mappings +themselves. The :class:`_orm.registry` object is the container where these +names are stored and resolved to the mapped classes to which they refer. In addition to the main class argument for :func:`_orm.relationship`, other arguments which depend upon the columns present on an as-yet @@ -1140,7 +1140,7 @@ using either a lambda callable or string name is supported, where string resolution works by evaluation of given Python expression which links identifier names to same-named :class:`_schema.Table` objects that are present in the same -:class:`_schema.MetaData` collection referred towards by the current +:class:`_schema.MetaData` collection referenced by the current :class:`_orm.registry`. For the example given at :ref:`relationships_many_to_many`, if we assumed diff --git a/doc/build/orm/composites.rst b/doc/build/orm/composites.rst index 4eaf7024a9..2e625509e0 100644 --- a/doc/build/orm/composites.rst +++ b/doc/build/orm/composites.rst @@ -84,7 +84,7 @@ Working with Mapped Composite Column Types With a mapping as illustrated in the top section, we can work with the ``Vertex`` class, where the ``.start`` and ``.end`` attributes will -transparently refer to the columns referred towards by the ``Point`` class, as +transparently refer to the columns referenced by the ``Point`` class, as well as with instances of the ``Vertex`` class, where the ``.start`` and ``.end`` attributes will refer to instances of the ``Point`` class. The ``x1``, ``y1``, ``x2``, and ``y2`` columns are handled transparently: diff --git a/doc/build/orm/declarative_tables.rst b/doc/build/orm/declarative_tables.rst index 3d032b9a62..711fa11bbe 100644 --- a/doc/build/orm/declarative_tables.rst +++ b/doc/build/orm/declarative_tables.rst @@ -1218,7 +1218,7 @@ The above configuration is often more readable as an inline definition:: A natural effect of the above style is that the ``__table__`` attribute is itself defined within the class definition block. As such it may be -immediately referred towards within subsequent attributes, such as the example +immediately referenced within subsequent attributes, such as the example below which illustrates referring to the ``type`` column in a polymorphic mapper configuration:: @@ -1699,7 +1699,7 @@ Similarly:: will map the ``Address`` class to the ``address_table`` table, including all columns present except ``street``, ``city``, ``state``, and ``zip``. -As indicated in the two examples, columns may be referred towards either +As indicated in the two examples, columns may be referenced either by string name or by referring to the :class:`_schema.Column` object directly. Referring to the object directly may be useful for explicitness as well as to resolve ambiguities when diff --git a/doc/build/orm/inheritance.rst b/doc/build/orm/inheritance.rst index 6746a0cda5..fe3e06bf0f 100644 --- a/doc/build/orm/inheritance.rst +++ b/doc/build/orm/inheritance.rst @@ -424,7 +424,7 @@ parameter indicates to :func:`_orm.mapped_column` that it should look for the requested :class:`_schema.Column` on the mapped :class:`.Table` for ``Employee`` first, and if present, maintain that existing mapping. If not present, :func:`_orm.mapped_column` will map the column normally, adding it -as one of the columns in the :class:`.Table` referred towards by the +as one of the columns in the :class:`.Table` referenced by the ``Employee`` superclass. diff --git a/doc/build/orm/join_conditions.rst b/doc/build/orm/join_conditions.rst index 09c744e40a..ef6d74e667 100644 --- a/doc/build/orm/join_conditions.rst +++ b/doc/build/orm/join_conditions.rst @@ -428,7 +428,7 @@ composite key to ``Writer``. If we associate an ``Article`` with a particular ``Magazine``, but then associate the ``Article`` with a ``Writer`` that's associated with a *different* ``Magazine``, the ORM will overwrite ``Article.magazine_id`` non-deterministically, silently -changing which magazine we refer towards; it may +changing which magazine to which we refer; it may also attempt to place NULL into this column if we de-associate a ``Writer`` from an ``Article``. The warning lets us know this is the case. diff --git a/doc/build/orm/mapping_styles.rst b/doc/build/orm/mapping_styles.rst index 72d540090f..fbe4267be7 100644 --- a/doc/build/orm/mapping_styles.rst +++ b/doc/build/orm/mapping_styles.rst @@ -89,7 +89,7 @@ the use of a declarative base which is then used in a declarative table mapping: nickname: Mapped[Optional[str]] Above, the :class:`_orm.DeclarativeBase` class is used to generate a new -base class (within SQLAlchemy's documentation it's typically referred towards +base class (within SQLAlchemy's documentation it's typically referred to as ``Base``, however can have any desired name) from which new classes to be mapped may inherit from, as above a new mapped class ``User`` is constructed. diff --git a/doc/build/orm/queryguide/inheritance.rst b/doc/build/orm/queryguide/inheritance.rst index 66ac18e268..136bed55a6 100644 --- a/doc/build/orm/queryguide/inheritance.rst +++ b/doc/build/orm/queryguide/inheritance.rst @@ -408,7 +408,7 @@ In contrast to :func:`_orm.selectin_polymorphic` which affects only the loading of objects, the :func:`_orm.with_polymorphic` construct affects how the SQL query for a polymorphic structure is rendered, most commonly as a series of LEFT OUTER JOINs to each of the included sub-tables. This join structure is -referred towards as the **polymorphic selectable**. By providing for a view of +known as the **polymorphic selectable**. By providing for a view of several sub-tables at once, :func:`_orm.with_polymorphic` offers a means of writing a SELECT statement across several inherited classes at once with the ability to add filtering criteria based on individual sub-tables. @@ -509,7 +509,7 @@ statement. To use this feature with a joined inheritance mapping, we typically want to pass two parameters, :paramref:`_orm.with_polymorphic.aliased` as well as :paramref:`_orm.with_polymorphic.flat`. The :paramref:`_orm.with_polymorphic.aliased` -parameter indicates that the polymorphic selectable should be referred towards +parameter indicates that the polymorphic selectable should be referenced by an alias name that is unique to this construct. The :paramref:`_orm.with_polymorphic.flat` parameter is specific to the default LEFT OUTER JOIN polymorphic selectable and indicates that a more optimized diff --git a/doc/build/orm/queryguide/select.rst b/doc/build/orm/queryguide/select.rst index c14eb134e4..678565932d 100644 --- a/doc/build/orm/queryguide/select.rst +++ b/doc/build/orm/queryguide/select.rst @@ -798,7 +798,7 @@ applied to more than one :func:`_orm.aliased` construct at once, and used in the same :class:`.Select` construct in terms of each entity separately. The rendered SQL will continue to treat all such :func:`_orm.aliased` constructs as the same subquery, however from the ORM / Python perspective -the different return values and object attributes can be referred towards +the different return values and object attributes can be referenced by using the appropriate :func:`_orm.aliased` construct. Given for example a subquery that refers to both ``User`` and ``Address``:: @@ -1049,7 +1049,7 @@ in terms of the target :func:`_orm.relationship`. * **An object has a particular parent from a one-to-many perspective** - the :func:`_orm.with_parent` function produces a comparison that returns rows - which are referred towards by a given parent, this is essentially the + which are referenced by a given parent, this is essentially the same as using the ``==`` operator with the many-to-one side:: >>> from sqlalchemy.orm import with_parent diff --git a/doc/build/orm/quickstart.rst b/doc/build/orm/quickstart.rst index 9c693e027d..48f3673699 100644 --- a/doc/build/orm/quickstart.rst +++ b/doc/build/orm/quickstart.rst @@ -103,10 +103,10 @@ of the key. In the above example, the ``User.id`` and ``Address.id`` columns are marked as primary key. Taken together, the combination of a string table name as well as a list -of column declarations is referred towards in SQLAlchemy as :term:`table metadata`. +of column declarations is known in SQLAlchemy as :term:`table metadata`. Setting up table metadata using both Core and ORM approaches is introduced in the :ref:`unified_tutorial` at :ref:`tutorial_working_with_metadata`. -The above mapping is an example of what's referred towards as +The above mapping is an example of what's known as :ref:`Annotated Declarative Table ` configuration. diff --git a/doc/build/tutorial/data_select.rst b/doc/build/tutorial/data_select.rst index 03bc459a1f..abdbb2ec54 100644 --- a/doc/build/tutorial/data_select.rst +++ b/doc/build/tutorial/data_select.rst @@ -255,7 +255,7 @@ when referring to arbitrary SQL expressions in a result row by name: .. seealso:: :ref:`tutorial_order_by_label` - the label names we create may also be - referred towards in the ORDER BY or GROUP BY clause of the :class:`_sql.Select`. + referenced in the ORDER BY or GROUP BY clause of the :class:`_sql.Select`. .. _tutorial_select_arbitrary_text: @@ -682,7 +682,7 @@ Now that we are selecting from multiple tables and using joins, we quickly run into the case where we need to refer to the same table multiple times in the FROM clause of a statement. We accomplish this using SQL **aliases**, which are a syntax that supplies an alternative name to a table or subquery -from which it can be referred towards in the statement. +from which it can be referenced in the statement. In the SQLAlchemy Expression Language, these "names" are instead represented by :class:`_sql.FromClause` objects known as the :class:`_sql.Alias` construct, @@ -1163,7 +1163,7 @@ that it has fewer methods. The :class:`_sql.CompoundSelect` produced by To use a :class:`_sql.CompoundSelect` as a subquery, just like :class:`_sql.Select` it provides a :meth:`_sql.SelectBase.subquery` method which will produce a :class:`_sql.Subquery` object with a :attr:`_sql.FromClause.c` -collection that may be referred towards in an enclosing :func:`_sql.select`:: +collection that may be referenced in an enclosing :func:`_sql.select`:: >>> u_subq = u.subquery() >>> stmt = ( @@ -1422,7 +1422,7 @@ something like :class:`_types.Integer` or :class:`_types.Numeric`, JSON accessors in order to work need to be using a type such as :class:`_types.JSON`. Certain classes of functions return entire rows instead of column values, where there is a need to refer to specific columns; -such functions are referred towards +such functions are known as :ref:`table valued functions `. The SQL return type of the function may also be significant when executing a @@ -1676,7 +1676,7 @@ Table-Valued Functions Table-valued SQL functions support a scalar representation that contains named sub-elements. Often used for JSON and ARRAY-oriented functions as well as functions like ``generate_series()``, the table-valued function is specified in -the FROM clause, and is then referred towards as a table, or sometimes even as +the FROM clause, and is then referenced as a table, or sometimes even as a column. Functions of this form are prominent within the PostgreSQL database, however some forms of table valued functions are also supported by SQLite, Oracle, and SQL Server. diff --git a/doc/build/tutorial/dbapi_transactions.rst b/doc/build/tutorial/dbapi_transactions.rst index aecc3e6bae..ade14eb4fb 100644 --- a/doc/build/tutorial/dbapi_transactions.rst +++ b/doc/build/tutorial/dbapi_transactions.rst @@ -137,7 +137,7 @@ connection, rather than the :meth:`_engine.Engine.connect` method. This method will both manage the scope of the :class:`_engine.Connection` and also enclose everything inside of a transaction with COMMIT at the end, assuming a successful block, or ROLLBACK in case of exception raise. This style -may be referred towards as **begin once**: +is known as **begin once**: .. sourcecode:: pycon+sql @@ -301,7 +301,7 @@ Sending Parameters SQL statements are usually accompanied by data that is to be passed with the statement itself, as we saw in the INSERT example previously. The :meth:`_engine.Connection.execute` method therefore also accepts parameters, -which are referred towards as :term:`bound parameters`. A rudimentary example +which are known as :term:`bound parameters`. A rudimentary example might be if we wanted to limit our SELECT statement only to rows that meet a certain criteria, such as rows where the "y" value were greater than a certain value that is passed in to a function. diff --git a/doc/build/tutorial/metadata.rst b/doc/build/tutorial/metadata.rst index 8ee87480af..7d6f5b3137 100644 --- a/doc/build/tutorial/metadata.rst +++ b/doc/build/tutorial/metadata.rst @@ -335,7 +335,7 @@ SQLAlchemy :class:`_orm.DeclarativeBase` class:: >>> class Base(DeclarativeBase): ... pass -Above, the ``Base`` class is what we'll refer towards as the Declarative Base. +Above, the ``Base`` class is what we'll call the Declarative Base. When we make new classes that are subclasses of ``Base``, combined with appropriate class-level directives, they will each be established as a new **ORM mapped class** at class creation time, each one typically (but not @@ -415,7 +415,7 @@ types:: ... def __repr__(self) -> str: ... return f"Address(id={self.id!r}, email_address={self.email_address!r})" -The two classes above, ``User`` and ``Address``, are now referred towards +The two classes above, ``User`` and ``Address``, are now called as **ORM Mapped Classes**, and are available for use in ORM persistence and query operations, which will be described later. Details about these classes include: @@ -427,7 +427,7 @@ about these classes include: from the :attr:`_orm.DeclarativeBase.__table__` attribute. * As mentioned previously, this form - is referred towards as :ref:`orm_declarative_table_configuration`. One + is known as :ref:`orm_declarative_table_configuration`. One of several alternative declaration styles would instead have us build the :class:`_schema.Table` object directly, and **assign** it directly to :attr:`_orm.DeclarativeBase.__table__`. This style diff --git a/doc/build/tutorial/orm_related_objects.rst b/doc/build/tutorial/orm_related_objects.rst index e10288a21c..48e049dd9e 100644 --- a/doc/build/tutorial/orm_related_objects.rst +++ b/doc/build/tutorial/orm_related_objects.rst @@ -56,7 +56,7 @@ are mapped to the ``User`` and ``Address`` classes. As the table, the :func:`_orm.relationship` can determine unambiguously that there is a :term:`one to many` relationship from the ``User`` class to the ``Address`` class, along the ``User.addresses`` relationship; one particular row in the -``user_account`` table may be referred towards by many rows in the ``address`` +``user_account`` table may be referenced by many rows in the ``address`` table. All one-to-many relationships naturally correspond to a :term:`many to one` diff --git a/lib/sqlalchemy/dialects/postgresql/base.py b/lib/sqlalchemy/dialects/postgresql/base.py index b5f53a1ff1..b9fd8c8bab 100644 --- a/lib/sqlalchemy/dialects/postgresql/base.py +++ b/lib/sqlalchemy/dialects/postgresql/base.py @@ -303,7 +303,7 @@ Setting Alternate Search Paths on Connect ------------------------------------------ The PostgreSQL ``search_path`` variable refers to the list of schema names -that will be implicitly referred towards when a particular table or other +that will be implicitly referenced when a particular table or other object is referenced in a SQL statement. As detailed in the next section :ref:`postgresql_schema_reflection`, SQLAlchemy is generally organized around the concept of keeping this variable at its default value of ``public``, @@ -1376,8 +1376,8 @@ Built-in support for rendering a ``ROW`` may be approximated using Table Types passed to Functions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -PostgreSQL supports passing a table as an argument to a function, which it -refers towards as a "record" type. SQLAlchemy :class:`_sql.FromClause` objects +PostgreSQL supports passing a table as an argument to a function, which is +known as a "record" type. SQLAlchemy :class:`_sql.FromClause` objects such as :class:`_schema.Table` support this special form using the :meth:`_sql.FromClause.table_valued` method, which is comparable to the :meth:`_functions.FunctionElement.table_valued` method except that the collection diff --git a/lib/sqlalchemy/dialects/postgresql/psycopg2.py b/lib/sqlalchemy/dialects/postgresql/psycopg2.py index 27f63ea6e1..2719f3dc5e 100644 --- a/lib/sqlalchemy/dialects/postgresql/psycopg2.py +++ b/lib/sqlalchemy/dialects/postgresql/psycopg2.py @@ -254,7 +254,7 @@ equivalent to psycopg2's ``execute_values()`` handler; an overview of this feature and its configuration are at :ref:`engine_insertmanyvalues`. .. versionadded:: 2.0 Replaced psycopg2's ``execute_values()`` fast execution - helper with a native SQLAlchemy mechanism referred towards as + helper with a native SQLAlchemy mechanism known as :ref:`insertmanyvalues `. The psycopg2 dialect retains the ability to use the psycopg2-specific diff --git a/lib/sqlalchemy/dialects/sqlite/base.py b/lib/sqlalchemy/dialects/sqlite/base.py index 15c262c3e8..4bce3a3d29 100644 --- a/lib/sqlalchemy/dialects/sqlite/base.py +++ b/lib/sqlalchemy/dialects/sqlite/base.py @@ -843,7 +843,7 @@ Reflecting internal schema tables ---------------------------------- Reflection methods that return lists of tables will omit so-called -"SQLite internal schema object" names, which are referred towards by SQLite +"SQLite internal schema object" names, which are considered by SQLite as any object name that is prefixed with ``sqlite_``. An example of such an object is the ``sqlite_sequence`` table that's generated when the ``AUTOINCREMENT`` column parameter is used. In order to return diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index b0cd721f1c..72012ff9d9 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -814,7 +814,7 @@ class Connection(ConnectionEventsTarget, inspection.Inspectable["Inspector"]): The above code is not fundamentally any different in its behavior than the following code which does not use - :meth:`_engine.Connection.begin`; the below style is referred towards + :meth:`_engine.Connection.begin`; the below style is known as "commit as you go" style:: with engine.connect() as conn: diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py index c7db91000d..ea1f27d062 100644 --- a/lib/sqlalchemy/engine/interfaces.py +++ b/lib/sqlalchemy/engine/interfaces.py @@ -521,7 +521,7 @@ class ReflectedIndex(TypedDict): """index name""" column_names: List[Optional[str]] - """column names which the index refers towards. + """column names which the index references. An element of this list is ``None`` if it's an expression and is returned in the ``expressions`` list. """ diff --git a/lib/sqlalchemy/ext/hybrid.py b/lib/sqlalchemy/ext/hybrid.py index 722c9bd563..615f166b47 100644 --- a/lib/sqlalchemy/ext/hybrid.py +++ b/lib/sqlalchemy/ext/hybrid.py @@ -200,7 +200,7 @@ Using ``inplace`` to create pep-484 compliant hybrid properties In the previous section, a :class:`.hybrid_property` decorator is illustrated which includes two separate method-level functions being decorated, both -to produce a single object attribute referred towards as ``Interval.radius``. +to produce a single object attribute referenced as ``Interval.radius``. There are actually several different modifiers we can use for :class:`.hybrid_property` including :meth:`.hybrid_property.expression`, :meth:`.hybrid_property.setter` and :meth:`.hybrid_property.update_expression`. diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py index a83c70043a..c66d876e08 100644 --- a/lib/sqlalchemy/orm/mapper.py +++ b/lib/sqlalchemy/orm/mapper.py @@ -964,8 +964,8 @@ class Mapper( version_id_generator: Optional[Union[Literal[False], Callable[[Any], Any]]] local_table: FromClause - """The immediate :class:`_expression.FromClause` which this - :class:`_orm.Mapper` refers towards. + """The immediate :class:`_expression.FromClause` to which this + :class:`_orm.Mapper` refers. Typically is an instance of :class:`_schema.Table`, may be any :class:`.FromClause`. diff --git a/lib/sqlalchemy/orm/relationships.py b/lib/sqlalchemy/orm/relationships.py index 191ace48dd..bb5ddb8725 100644 --- a/lib/sqlalchemy/orm/relationships.py +++ b/lib/sqlalchemy/orm/relationships.py @@ -1614,7 +1614,8 @@ class RelationshipProperty( @util.memoized_property def entity(self) -> _InternalEntityType[_T]: """Return the target mapped entity, which is an inspect() of the - class or aliased class that is referred towards. + class or aliased class that is referenced by this + :class:`.RelationshipProperty`. """ self.parent._check_configure() @@ -1990,7 +1991,7 @@ class RelationshipProperty( 'and not on the "many" side of a many-to-one or many-to-many ' "relationship. " "To force this relationship to allow a particular " - '"%(relatedcls)s" object to be referred towards by only ' + '"%(relatedcls)s" object to be referenced by only ' 'a single "%(clsname)s" object at a time via the ' "%(rel)s relationship, which " "would allow " diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py index a838d8d08e..e9a85b9ae6 100644 --- a/lib/sqlalchemy/orm/util.py +++ b/lib/sqlalchemy/orm/util.py @@ -936,7 +936,7 @@ class AliasedInsp( """the AliasedClass that refers to this AliasedInsp""" _target: Union[Type[_O], AliasedClass[_O]] - """the thing referred towards by the AliasedClass/AliasedInsp. + """the thing referenced by the AliasedClass/AliasedInsp. In the vast majority of cases, this is the mapped class. However it may also be another AliasedClass (alias of alias). diff --git a/lib/sqlalchemy/sql/elements.py b/lib/sqlalchemy/sql/elements.py index a3666c5f10..90ee100aae 100644 --- a/lib/sqlalchemy/sql/elements.py +++ b/lib/sqlalchemy/sql/elements.py @@ -4182,7 +4182,7 @@ class Over(ColumnElement[_T]): element: ColumnElement[_T] """The underlying expression object to which this :class:`.Over` - object refers towards.""" + object refers.""" range_: Optional[typing_Tuple[int, int]] diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py index a508e6fb77..debeb8bb87 100644 --- a/lib/sqlalchemy/sql/selectable.py +++ b/lib/sqlalchemy/sql/selectable.py @@ -2434,7 +2434,7 @@ class HasCTE(roles.HasCTERole, SelectsRows): SELECT t.c1, t.c2 FROM t - Above, the "anon_1" CTE is not referred towards in the SELECT + Above, the "anon_1" CTE is not referenced in the SELECT statement, however still accomplishes the task of running an INSERT statement. diff --git a/lib/sqlalchemy/sql/visitors.py b/lib/sqlalchemy/sql/visitors.py index 8020181a29..cccebe65ba 100644 --- a/lib/sqlalchemy/sql/visitors.py +++ b/lib/sqlalchemy/sql/visitors.py @@ -161,16 +161,17 @@ class InternalTraversal(Enum): the ``_traverse_internals`` collection. Such as, the :class:`.Case` object defines ``_traverse_internals`` as :: - _traverse_internals = [ - ("value", InternalTraversal.dp_clauseelement), - ("whens", InternalTraversal.dp_clauseelement_tuples), - ("else_", InternalTraversal.dp_clauseelement), - ] + class Case(ColumnElement[_T]): + _traverse_internals = [ + ("value", InternalTraversal.dp_clauseelement), + ("whens", InternalTraversal.dp_clauseelement_tuples), + ("else_", InternalTraversal.dp_clauseelement), + ] Above, the :class:`.Case` class indicates its internal state as the attributes named ``value``, ``whens``, and ``else_``. They each link to an :class:`.InternalTraversal` method which indicates the type - of datastructure referred towards. + of datastructure to which each attribute refers. Using the ``_traverse_internals`` structure, objects of type :class:`.InternalTraversible` will have the following methods automatically -- 2.47.3