`python3 -m tox` passes.
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
+ would be referred to 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
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
+ subquery to be referred to 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
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 referred to 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
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
+ * fixed issue where boolean True/False values 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
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.
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 referred to 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".
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 referred to directly when making the relationship::
j = join(B, D, D.b_id == B.id).join(C, C.id == D.c_id)
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 referred to
as well as what entity column or relationship is being considered for a given
component of the query.
: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 referred to as **commit as you go**, and is
illustrated in the example below::
with engine.connect() as connection:
~~~~~~~~~~
The :class:`_engine.Connection` object provides a more explicit transaction
-management style referred towards as **begin once**. In contrast to "commit as
+management style referred to 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
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, referred to 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.
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 referred to in its remote "schema",
whatever mechanism that is on the target database.
The "schema" name may be associated directly with a :class:`_schema.Table`
"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 referred to explicitly using the
syntax "<schemaname>.<tablename>". 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
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 referred to 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
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 referred to directly::
a1 = Address.__table__.alias()
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 referred to 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
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 referred to 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
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 referred to by the current
:class:`_orm.registry`.
For the example given at :ref:`relationships_many_to_many`, if we assumed
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 referred to 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:
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 referred to within subsequent attributes, such as the example
below which illustrates referring to the ``type`` column in a polymorphic
mapper configuration::
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 referred to 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
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` referred to by the
``Employee`` superclass.
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.
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
+referred to 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.
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 referred to
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
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 referred to
by using the appropriate :func:`_orm.aliased` construct.
Given for example a subquery that refers to both ``User`` and ``Address``::
* **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 referred to 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
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 referred to 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 referred to as
:ref:`Annotated Declarative Table <orm_declarative_mapped_column>`
configuration.
.. 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`.
+ referred to in the ORDER BY or GROUP BY clause of the :class:`_sql.Select`.
.. _tutorial_select_arbitrary_text:
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 referred to 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,
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 referred to in an enclosing :func:`_sql.select`::
>>> u_subq = u.subquery()
>>> stmt = (
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 referred to
as :ref:`table valued functions <tutorial_functions_table_valued>`.
The SQL return type of the function may also be significant when executing a
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 referred to 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.
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**:
+may be referred to as **begin once**:
.. sourcecode:: pycon+sql
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 referred to 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.
... 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 referred to
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:
from the :attr:`_orm.DeclarativeBase.__table__` attribute.
* As mentioned previously, this form
- is referred towards as :ref:`orm_declarative_table_configuration`. One
+ is referred to 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
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 referred to by many rows in the ``address``
table.
All one-to-many relationships naturally correspond to a :term:`many to one`
------------------------------------------
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 referred to 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``,
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 referred to as
:ref:`insertmanyvalues <engine_insertmanyvalues>`.
The psycopg2 dialect retains the ability to use the psycopg2-specific
----------------------------------
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 referred to 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
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 referred to
as "commit as you go" style::
with engine.connect() as conn:
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 referred to 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`.
@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 referred to.
"""
self.parent._check_configure()
'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 referred to by only '
'a single "%(clsname)s" object at a time via the '
"%(rel)s relationship, which "
"would allow "
"""the AliasedClass that refers to this AliasedInsp"""
_target: Union[Type[_O], AliasedClass[_O]]
- """the thing referred towards by the AliasedClass/AliasedInsp.
+ """the thing referred to 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).
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 referred to in the SELECT
statement, however still accomplishes the task of running an INSERT
statement.
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 referred to.
Using the ``_traverse_internals`` structure, objects of type
:class:`.InternalTraversible` will have the following methods automatically
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
