diff options
| author | Mike Bayer <mike_mp@zzzcomputing.com> | 2023-04-23 12:54:45 -0400 |
|---|---|---|
| committer | Mike Bayer <mike_mp@zzzcomputing.com> | 2023-04-23 13:01:56 -0400 |
| commit | 5347efa35e3e80c8092501b4adfe1278260d67f5 (patch) | |
| tree | cd3abe5b9c02c59bdecc7a95206b974abdea497e | |
| parent | 08515f23b3ea36bce2f150b8cd82c787c4cf9e5e (diff) | |
| download | sqlalchemy-5347efa35e3e80c8092501b4adfe1278260d67f5.tar.gz | |
remove all labels and links that are no longer locatable
Change-Id: Ic975b8c20bc297d3a04dde0bed143783ae951cd4
100 files changed, 431 insertions, 448 deletions
diff --git a/doc/build/changelog/changelog_14.rst b/doc/build/changelog/changelog_14.rst index 1e80c684c..6d78899fb 100644 --- a/doc/build/changelog/changelog_14.rst +++ b/doc/build/changelog/changelog_14.rst @@ -7,11 +7,6 @@ This document details individual issue-level changes made throughout :ref:`migration_14_toplevel`. -.. changelog_imports:: - - .. include:: changelog_13.rst - :start-line: 5 - .. changelog:: :version: 1.4.48 @@ -995,7 +990,7 @@ This document details individual issue-level changes made throughout .. seealso:: - :ref:`azure_synapse_ignore_no_transaction_on_rollback` + ref_azure_synapse_ignore_no_transaction_on_rollback .. change:: :tags: bug, mypy @@ -1832,7 +1827,7 @@ This document details individual issue-level changes made throughout .. seealso:: - :ref:`postgresql_constraint_options` + ref_postgresql_constraint_options .. change:: :tags: bug, orm, regression @@ -1982,7 +1977,7 @@ This document details individual issue-level changes made throughout .. seealso:: - :ref:`asyncio_events_run_async` + ref_asyncio_events_run_async .. change:: @@ -3229,7 +3224,7 @@ This document details individual issue-level changes made throughout .. seealso:: - :ref:`asyncmy` + ref_asyncmy .. change:: :tags: bug, asyncio @@ -4014,7 +4009,7 @@ This document details individual issue-level changes made throughout .. seealso:: - :ref:`asyncio_scoped_session` + ref_asyncio_scoped_session .. change:: :tags: usecase, mysql @@ -5293,7 +5288,7 @@ This document details individual issue-level changes made throughout .. seealso:: - :ref:`mypy_declarative_mixins` + ref_mypy_declarative_mixins .. change:: @@ -5582,7 +5577,7 @@ This document details individual issue-level changes made throughout .. seealso:: - :ref:`aiosqlite` + ref_aiosqlite .. change:: :tags: bug, regression, orm, declarative @@ -5632,7 +5627,7 @@ This document details individual issue-level changes made throughout .. seealso:: - :ref:`pysqlcipher` + ref_pysqlcipher .. change:: @@ -5746,7 +5741,7 @@ This document details individual issue-level changes made throughout .. seealso:: - :ref:`orm_declarative_dataclasses_mixin` + ref_orm_declarative_dataclasses_mixin .. change:: :tags: bug, sql, regression @@ -5845,7 +5840,7 @@ This document details individual issue-level changes made throughout .. seealso:: - :ref:`mssql_pyodbc_setinputsizes` + ref_mssql_pyodbc_setinputsizes .. change:: :tags: bug, orm, regression @@ -5947,7 +5942,7 @@ This document details individual issue-level changes made throughout .. seealso:: - :ref:`mypy_toplevel` + ref_mypy_toplevel .. change:: :tags: bug, sql @@ -6402,7 +6397,7 @@ This document details individual issue-level changes made throughout .. seealso:: - :ref:`orm_declarative_dataclasses_declarative_table` + ref_orm_declarative_dataclasses_declarative_table .. change:: :tags: bug, sql @@ -6510,7 +6505,7 @@ This document details individual issue-level changes made throughout .. seealso:: - :ref:`asyncpg_prepared_statement_cache` + ref_asyncpg_prepared_statement_cache .. change:: :tags: feature, mysql @@ -6521,7 +6516,7 @@ This document details individual issue-level changes made throughout .. seealso:: - :ref:`aiomysql` + ref_aiomysql .. change:: :tags: bug, reflection @@ -6605,7 +6600,7 @@ This document details individual issue-level changes made throughout .. seealso:: - :ref:`sqlite_on_conflict_insert` + ref_sqlite_on_conflict_insert .. change:: :tags: bug, asyncio @@ -6701,7 +6696,7 @@ This document details individual issue-level changes made throughout :ref:`mapper_automated_reflection_schemes` - in the ORM mapping documentation - :ref:`automap_intercepting_columns` - in the :ref:`automap_toplevel` documentation + ref_automap_intercepting_columns - in the ref_automap_toplevel documentation @@ -6792,7 +6787,7 @@ This document details individual issue-level changes made throughout .. seealso:: - :ref:`metadata_reflection_dbagnostic_types` - example usage + ref_metadata_reflection_dbagnostic_types - example usage .. change:: :tags: bug, sql @@ -7523,13 +7518,13 @@ This document details individual issue-level changes made throughout :tickets: 3414 SQLAlchemy now includes support for Python asyncio within both Core and - ORM, using the included :ref:`asyncio extension <asyncio_toplevel>`. The + ORM, using the included ref_asyncio_toplevel. The extension makes use of the `greenlet <https://greenlet.readthedocs.io/en/latest/>`_ library in order to adapt SQLAlchemy's sync-oriented internals such that an asyncio interface that ultimately interacts with an asyncio database adapter is now feasible. The single driver supported at the moment is the - :ref:`dialect-postgresql-asyncpg` driver for PostgreSQL. + ref_dialect-postgresql-asyncpg driver for PostgreSQL. .. seealso:: @@ -7663,7 +7658,7 @@ This document details individual issue-level changes made throughout Microsoft SQL Server. This removes the deprecated feature of using :class:`.Sequence` objects to manipulate IDENTITY characteristics which should now be performed using ``mssql_identity_start`` and - ``mssql_identity_increment`` as documented at :ref:`mssql_identity`. The + ``mssql_identity_increment`` as documented at ref_mssql_identity. The change includes a new parameter :paramref:`.Sequence.data_type` to accommodate SQL Server's choice of datatype, which for that backend includes INTEGER, BIGINT, and DECIMAL(n, 0). The default starting value @@ -7814,7 +7809,7 @@ This document details individual issue-level changes made throughout .. seealso:: - :ref:`oracle_max_identifier_lengths` - in the Oracle dialect documentation + ref_oracle_max_identifier_lengths - in the Oracle dialect documentation .. change:: @@ -8284,7 +8279,7 @@ This document details individual issue-level changes made throughout .. seealso:: - :ref:`postgresql_readonly_deferrable` + ref_postgresql_readonly_deferrable .. change:: :tags: mysql, feature @@ -8549,7 +8544,7 @@ This document details individual issue-level changes made throughout Remove deprecated method ``Session.prune`` and parameter ``Session.weak_identity_map``. See the recipe at - :ref:`session_referencing_behavior` for an event-based approach to + ref_session_referencing_behavior for an event-based approach to maintaining strong identity references. This change also removes the class ``StrongInstanceDict``. diff --git a/doc/build/changelog/changelog_20.rst b/doc/build/changelog/changelog_20.rst index f6ec81c15..f254d4542 100644 --- a/doc/build/changelog/changelog_20.rst +++ b/doc/build/changelog/changelog_20.rst @@ -109,7 +109,7 @@ .. seealso:: - :ref:`asyncpg_prepared_statement_name` + ref_asyncpg_prepared_statement_name .. change:: :tags: typing, bug @@ -347,7 +347,7 @@ :ref:`error_dcmx` - background on rationale - :ref:`orm_declarative_dc_mixins` + ref_orm_declarative_dc_mixins .. change:: :tags: bug, postgresql @@ -625,7 +625,7 @@ SQLAlchemy now computes rowcount for a RETURNING statement in this specific case by counting the rows returned, rather than relying upon ``cursor.rowcount``. In particular, the ORM versioned rows use case - (documented at :ref:`mapper_version_counter`) should now be fully + (documented at ref_mapper_version_counter) should now be fully supported with the SQL Server pyodbc dialect. @@ -829,7 +829,7 @@ :tags: usecase, typing :tickets: 9321 - Improved the typing support for the :ref:`hybrids_toplevel` + Improved the typing support for the ref_hybrids_toplevel extension, updated all documentation to use ORM Annotated Declarative mappings, and added a new modifier called :attr:`.hybrid_property.inplace`. This modifier provides a way to alter the state of a :class:`.hybrid_property` @@ -845,7 +845,7 @@ .. seealso:: - :ref:`hybrid_pep484_naming` + ref_hybrid_pep484_naming .. change:: :tags: bug, orm @@ -885,7 +885,7 @@ :tickets: 9295 Adjusted the behavior of the ``thick_mode`` parameter for the - :ref:`oracledb` dialect to correctly accept ``False`` as a value. + ref_oracledb dialect to correctly accept ``False`` as a value. Previously, only ``None`` would indicate that thick mode should be disabled. @@ -936,7 +936,7 @@ .. seealso:: - :ref:`dataclasses_pydantic` + ref_dataclasses_pydantic .. changelog:: @@ -1144,7 +1144,7 @@ :class:`_orm.Mapper` object is created within the class creation process, there was no documented means of running code at this point. The change is to immediately benefit custom mapping schemes such as that - of the :ref:`examples_versioned_history` example, which generate additional + of the ref_examples_versioned_history example, which generate additional mappers and tables in response to the creation of mapped classes. @@ -1174,7 +1174,7 @@ :tags: bug, examples :tickets: 9220 - Reworked the :ref:`examples_versioned_history` to work with + Reworked the ref_examples_versioned_history to work with version 2.0, while at the same time improving the overall working of this example to use newer APIs, including a newly added hook :meth:`_orm.MapperEvents.after_mapper_constructed`. @@ -1406,7 +1406,7 @@ .. seealso:: - :ref:`automap_by_module` - illustrates use of both techniques at once. + ref_automap_by_module - illustrates use of both techniques at once. .. change:: :tags: orm, bug @@ -1520,7 +1520,7 @@ .. seealso:: - :ref:`mssql_comment_support` + ref_mssql_comment_support .. changelog:: @@ -1937,7 +1937,7 @@ .. seealso:: - :ref:`orm_declarative_native_dataclasses_non_mapped_fields` + ref_orm_declarative_native_dataclasses_non_mapped_fields .. change:: @@ -2172,7 +2172,7 @@ :tags: bug, orm :tickets: 8880 - Fixed bug in :ref:`orm_declarative_native_dataclasses` feature where using + Fixed bug in ref_orm_declarative_native_dataclasses feature where using plain dataclass fields with the ``__allow_unmapped__`` directive in a mapping would not create a dataclass with the correct class-level state for those fields, copying the raw ``Field`` object to the class inappropriately @@ -2186,7 +2186,7 @@ Added support for the :func:`.association_proxy` extension function to take part within Python ``dataclasses`` configuration, when using the native dataclasses feature described at - :ref:`orm_declarative_native_dataclasses`. Included are attribute-level + ref_orm_declarative_native_dataclasses. Included are attribute-level arguments including :paramref:`.association_proxy.init` and :paramref:`.association_proxy.default_factory`. @@ -2237,7 +2237,7 @@ attribute constructs including :func:`_orm.mapped_column`, :func:`_orm.relationship` etc. to provide for the Python dataclasses ``compare`` parameter on ``field()``, when using the - :ref:`orm_declarative_native_dataclasses` feature. Pull request courtesy + ref_orm_declarative_native_dataclasses feature. Pull request courtesy Simon Schiele. .. change:: @@ -3005,7 +3005,7 @@ .. seealso:: - :ref:`sqlite_include_internal` + ref_sqlite_include_internal .. change:: :tags: feature, postgresql @@ -3039,7 +3039,7 @@ :ref:`ticket_8054` - :ref:`oracledb` + ref_oracledb .. change:: :tags: bug, engine @@ -3197,7 +3197,7 @@ :ref:`ticket_6842` - :ref:`postgresql_psycopg` + ref_postgresql_psycopg @@ -3231,7 +3231,7 @@ Additionally, classes mapped by :class:`_orm.composite` now support ordering comparison operations, e.g. ``<``, ``>=``, etc. - See the new documentation at :ref:`mapper_composite` for examples. + See the new documentation at ref_mapper_composite for examples. .. change:: :tags: engine, bug @@ -4005,7 +4005,7 @@ ``'value'``. For normal bound value handling, the :class:`_types.Unicode` datatype also may have implications for passing values to the DBAPI, again in the case of SQL Server, the pyodbc driver supports the use of - :ref:`setinputsizes mode <mssql_pyodbc_setinputsizes>` which will handle + ref_mssql_pyodbc_setinputsizes which will handle :class:`_types.String` versus :class:`_types.Unicode` differently. diff --git a/doc/build/changelog/migration_13.rst b/doc/build/changelog/migration_13.rst index f7ce653f4..7249b3c21 100644 --- a/doc/build/changelog/migration_13.rst +++ b/doc/build/changelog/migration_13.rst @@ -1228,7 +1228,7 @@ the ON clause of the SQL join is expressed in terms of a SQL function. Expanding IN feature now supports empty lists --------------------------------------------- -The "expanding IN" feature introduced in version 1.2 at :ref:`change_3953` now +The "expanding IN" feature introduced in version 1.2 at ref_change_3953 now supports empty lists passed to the :meth:`.ColumnOperators.in_` operator. The implementation for an empty list will produce an "empty set" expression that is specific to a target backend, such as "SELECT CAST(NULL AS INTEGER) WHERE 1!=1" for PostgreSQL, @@ -1352,7 +1352,7 @@ Coercion of string SQL fragments to text() fully removed --------------------------------------------------------- The warnings that were first added in version 1.0, described at -:ref:`migration_2992`, have now been converted into exceptions. Continued +ref_migration_2992, have now been converted into exceptions. Continued concerns have been raised regarding the automatic coercion of string fragments passed to methods like :meth:`_query.Query.filter` and :meth:`_expression.Select.order_by` being converted to :func:`_expression.text` constructs, even though this has emitted a warning. @@ -1554,7 +1554,7 @@ can now be explicitly ordered by passing a list of 2-tuples:: .. seealso:: - :ref:`mysql_insert_on_duplicate_key_update` + ref_mysql_insert_on_duplicate_key_update Dialect Improvements and Changes - SQLite ============================================= @@ -1611,7 +1611,7 @@ The above table would render in a CREATE TABLE statement as: .. seealso:: - :ref:`sqlite_on_conflict_ddl` + ref_sqlite_on_conflict_ddl :ticket:`4360` @@ -1708,7 +1708,7 @@ Pass it via :func:`_sa.create_engine`:: .. seealso:: - :ref:`mssql_pyodbc_fastexecutemany` + ref_mssql_pyodbc_fastexecutemany :ticket:`4158` @@ -1758,7 +1758,7 @@ primary key column:: .. seealso:: - :ref:`mssql_identity` + ref_mssql_identity :ticket:`4362` diff --git a/doc/build/changelog/migration_14.rst b/doc/build/changelog/migration_14.rst index ac6cb6a53..4e94c2919 100644 --- a/doc/build/changelog/migration_14.rst +++ b/doc/build/changelog/migration_14.rst @@ -174,7 +174,7 @@ construction routines that must be built up each time an ORM query seeks to run and construct ORM objects from result sets. To introduce the general idea of the feature, given code from the -:ref:`examples_performance` suite as follows, which will invoke +ref_examples_performance suite as follows, which will invoke a very simple query "n" times, for a default value of n=10000. The query returns only a single row, as the overhead we are looking to decrease is that of **many small queries**. The optimization is not as significant @@ -287,7 +287,7 @@ In addition, The :func:`_declarative.instrument_declarative` function is deprecated, superseded by :meth:`_orm.registry.map_declaratively`. The :class:`_declarative.ConcreteBase`, :class:`_declarative.AbstractConcreteBase`, and :class:`_declarative.DeferredReflection` classes remain as extensions in the -:ref:`declarative_toplevel` package. +ref_declarative_toplevel package. Mapping styles have now been organized such that they all extend from the :class:`_orm.registry` object, and fall into these categories: @@ -299,10 +299,10 @@ the :class:`_orm.registry` object, and fall into these categories: * Using :meth:`_orm.registry.mapped` Declarative Decorator * Declarative Table * Imperative Table (Hybrid) - * :ref:`orm_declarative_dataclasses` + * ref_orm_declarative_dataclasses * :ref:`Imperative (a.k.a. "classical" mapping) <orm_imperative_mapping>` * Using :meth:`_orm.registry.map_imperatively` - * :ref:`orm_imperative_dataclasses` + * ref_orm_imperative_dataclasses The existing classical mapping function ``sqlalchemy.orm.mapper()`` remains, however it is deprecated to call upon ``sqlalchemy.orm.mapper()`` directly; the @@ -351,9 +351,9 @@ attribute systems can now interoperate with Declarative mappings as well. .. seealso:: - :ref:`orm_declarative_dataclasses` + ref_orm_declarative_dataclasses - :ref:`orm_imperative_dataclasses` + ref_orm_imperative_dataclasses :ticket:`5027` @@ -373,7 +373,7 @@ usage as well as :class:`_orm.Session` for ORM use, using the the initial releases of SQLAlchemy 1.4. This is super new stuff that uses some previously unfamiliar programming techniques. -The initial database API supported is the :ref:`dialect-postgresql-asyncpg` +The initial database API supported is the ref_dialect-postgresql-asyncpg asyncio driver for PostgreSQL. The internal features of SQLAlchemy are fully integrated by making use of @@ -423,7 +423,7 @@ tradition, the new API provides a **strictly optional feature** such that applications that wish to make use of such ORM features can opt to organize database-related code into functions which can then be run within greenlets using the :meth:`_asyncio.AsyncSession.run_sync` -method. See the ``greenlet_orm.py`` example at :ref:`examples_asyncio` +method. See the ``greenlet_orm.py`` example at ref_examples_asyncio for a demonstration. Support for asynchronous cursors is also provided using new methods @@ -438,9 +438,9 @@ in traditional SQLAlchemy. .. seealso:: - :ref:`asyncio_toplevel` + ref_asyncio_toplevel - :ref:`examples_asyncio` + ref_examples_asyncio @@ -553,7 +553,7 @@ is established as the implementation. :meth:`_sql.ColumnOperators.regexp_replace` - :ref:`pysqlite_regexp` - SQLite implementation notes + ref_pysqlite_regexp - SQLite implementation notes :ticket:`1390` @@ -1026,7 +1026,7 @@ structural specification, lists are used for data specification**. All IN expressions render parameters for each value in the list on the fly (e.g. expanding parameters) ------------------------------------------------------------------------------------------------------ -The "expanding IN" feature, first introduced in :ref:`change_3953`, has matured +The "expanding IN" feature, first introduced in ref_change_3953, has matured enough such that it is clearly superior to the previous method of rendering IN expressions. As the approach was improved to handle empty lists of values, it is now the only means that Core / ORM will use to render lists of IN @@ -1043,7 +1043,7 @@ their parameters, nor could the parameter dictionary be fully used for statements that included IN expressions generally. In order to service the "baked query" feature described at -:ref:`baked_toplevel`, a cacheable version of IN was needed, which is what +ref_baked_toplevel, a cacheable version of IN was needed, which is what brought about the "expanding IN" feature. In contrast to the existing behavior whereby the parameter list is expanded at statement construction time into individual :class:`.BindParameter` objects, the feature instead uses a single @@ -1114,7 +1114,7 @@ introduced in version 1.3 and is described at :ref:`change_4271`. The :paramref:`_sa.create_engine.empty_in_strategy` parameter, introduced in version 1.2 as a means for migrating for how this case was treated for the previous IN system, is now deprecated and this flag no longer has an effect; as described -in :ref:`change_3907`, this flag allowed a dialect to switch between the +in ref_change_3907, this flag allowed a dialect to switch between the original system of comparing a column against itself, which turned out to be a huge performance issue, and a newer system of comparing "1 != 1" in order to produce a "false" expression. The 1.3 introduced behavior which @@ -1941,7 +1941,7 @@ rather than invoking the same statement repeatedly, as psycopg2 lacks the abilit to PREPARE the statement ahead of time as would normally be expected for this approach to be performant. -SQLAlchemy includes a :ref:`performance suite <examples_performance>` within +SQLAlchemy includes a ref_examples_performance within its examples, where we can compare the times generated for the "batch_inserts" runner against 1.3 and 1.4, revealing a 3x-5x speedup for most flavors of batch insert: @@ -1993,7 +1993,7 @@ The ultimate INSERT statement can be seen by enabling statement logging on the P The feature batches rows into groups of 1000 by default which can be affected using the ``executemany_values_page_size`` argument documented at -:ref:`psycopg2_executemany_mode`. +ref_psycopg2_executemany_mode. :ticket:`5263` @@ -2572,7 +2572,7 @@ in the value of the ``name`` attribute. Since this is a SQL NULL, the ORM would skip including these values within an INSERT so that SQL-level defaults take place, if any, else the value defaults to NULL on the database side. -In version 1.0 as part of :ref:`migration_3061`, this behavior was refined so +In version 1.0 as part of ref_migration_3061, this behavior was refined so that the ``None`` value was no longer populated into ``__dict__``, only returned. Besides removing the mutating side effect of a getter operation, this change also made it possible to set columns that did have server defaults @@ -2969,7 +2969,7 @@ It also occurs beyond the cache boundary so that the INSERT statement may be cached before the VALUES are rendered. A quick test of the ``execute_values()`` approach using the -``bulk_inserts.py`` script in the :ref:`examples_performance` example +``bulk_inserts.py`` script in the ref_examples_performance example suite reveals an approximate **fivefold performance increase**: .. sourcecode:: text @@ -2983,7 +2983,7 @@ suite reveals an approximate **fivefold performance increase**: test_core_insert : A single Core INSERT construct inserting mappings in bulk. (100000 iterations); total time 0.944007 sec Support for the "batch" extension was added in version 1.2 in -:ref:`change_4109`, and enhanced to include support for the ``execute_values`` +ref_change_4109, and enhanced to include support for the ``execute_values`` extension in 1.3 in :ticket:`4623`. In 1.4 the ``execute_values`` extension is now being turned on by default for INSERT statements; the "batch" extension for UPDATE and DELETE remains off by default. @@ -3035,7 +3035,7 @@ with the following changes: .. seealso:: - :ref:`psycopg2_executemany_mode` + ref_psycopg2_executemany_mode :ticket:`5401` @@ -3051,7 +3051,7 @@ versions prior to 3.7.16, released in 2013. It is not expected that any modern Python versions rely upon this limitation. 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`. +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 versions prior to 3.7.16 after @@ -3114,7 +3114,7 @@ was not created. .. seealso:: - :ref:`defaults_sequences` + ref_defaults_sequences :ticket:`4976` @@ -3139,7 +3139,7 @@ parameters should be used; see the MSSQL dialect documentation linked below. .. seealso:: - :ref:`mssql_identity` + ref_mssql_identity :ticket:`4235` diff --git a/doc/build/changelog/migration_20.rst b/doc/build/changelog/migration_20.rst index 1fe47b7ac..522fb87b1 100644 --- a/doc/build/changelog/migration_20.rst +++ b/doc/build/changelog/migration_20.rst @@ -458,7 +458,7 @@ of the :class:`_orm.Mapped` generic container. Annotations which don't use :class:`_orm.Mapped` which link to constructs such as :func:`_orm.relationship` will raise errors in Python, as they suggest mis-configurations. -SQLAlchemy applications that use the :ref:`Mypy plugin <mypy_toplevel>` with +SQLAlchemy applications that use the ref_mypy_toplevel with explicit annotations that don't use :class:`_orm.Mapped` in their annotations are subject to these errors, as would occur in the example below:: @@ -1298,8 +1298,8 @@ has always allowed this style using so-called remove the base class requirement, a first class :ref:`decorator <declarative_config_toplevel>` form has been added. -As yet another separate but related enhancement, support for :ref:`Python -dataclasses <orm_declarative_dataclasses>` is added as well to both +As yet another separate but related enhancement, support for Python +dataclasses is added as well to both declarative decorator and classical mapping forms. .. seealso:: @@ -1524,7 +1524,7 @@ following the table, and may include additional notes not summarized here. ) # or - + session.scalar( select(func.count(User.id)) ) @@ -2163,7 +2163,7 @@ and should be preferred. **Synopsis** The ``lazy="dynamic"`` relationship loader strategy, discussed at -:ref:`dynamic_relationship`, makes use of the :class:`_query.Query` object +ref_dynamic_relationship, makes use of the :class:`_query.Query` object which is legacy in 2.0. The "dynamic" relationship is not directly compatible with asyncio without workarounds, and additionally it does not fulfill its original purpose of preventing iteration of large collections as it has several @@ -2249,7 +2249,7 @@ new feature is as :ref:`change_7123`. :ref:`change_7123` - :ref:`write_only_relationship` + ref_write_only_relationship .. _migration_20_session_autocommit: diff --git a/doc/build/changelog/whatsnew_20.rst b/doc/build/changelog/whatsnew_20.rst index 366c9c0ff..524b40a87 100644 --- a/doc/build/changelog/whatsnew_20.rst +++ b/doc/build/changelog/whatsnew_20.rst @@ -371,7 +371,7 @@ ORM Declarative Models ~~~~~~~~~~~~~~~~~~~~~~ SQLAlchemy 1.4 introduced the first SQLAlchemy-native ORM typing support -using a combination of sqlalchemy2-stubs_ and the :ref:`Mypy Plugin <mypy_toplevel>`. +using a combination of sqlalchemy2-stubs_ and the ref_mypy_toplevel. In SQLAlchemy 2.0, the Mypy plugin **remains available, and has been updated to work with SQLAlchemy 2.0's typing system**. However, it should now be considered **deprecated**, as applications now have a straightforward path to adopting the @@ -731,7 +731,7 @@ and :class:`_engine.Row` objects:: Using Legacy Mypy-Typed Models ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -SQLAlchemy applications that use the :ref:`Mypy plugin <mypy_toplevel>` with +SQLAlchemy applications that use the ref_mypy_toplevel with explicit annotations that don't use :class:`_orm.Mapped` in their annotations are subject to errors under the new system, as such annotations are flagged as errors when using constructs such as :func:`_orm.relationship`. @@ -848,7 +848,7 @@ positional arguments as configured:: .. seealso:: - :ref:`orm_declarative_native_dataclasses` + ref_orm_declarative_native_dataclasses .. _change_6047: @@ -910,7 +910,7 @@ and are still improved by the "insertmanyvalues" approach. Benchmarks ~~~~~~~~~~ -SQLAlchemy includes a :ref:`Performance Suite <examples_performance>` within +SQLAlchemy includes a ref_examples_performance within the ``examples/`` directory, where we can make use of the ``bulk_insert`` suite to benchmark INSERTs of many rows using both Core and ORM in different ways. @@ -1271,11 +1271,11 @@ using :term:`2.0 style` to load the desired objects in an explicit way:: The :class:`_orm.WriteOnlyCollection` also integrates with the new :ref:`ORM bulk dml <change_8360>` features, including support for bulk INSERT and UPDATE/DELETE with WHERE criteria, all including RETURNING support as -well. See the complete documentation at :ref:`write_only_relationship`. +well. See the complete documentation at ref_write_only_relationship. .. seealso:: - :ref:`write_only_relationship` + ref_write_only_relationship New pep-484 / type annotated mapping support for Dynamic Relationships ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1323,7 +1323,7 @@ as ``AccountTransaction``. .. seealso:: - :ref:`dynamic_relationship` + ref_dynamic_relationship :ticket:`7123` @@ -1392,7 +1392,7 @@ Major Architectural, Performance and API Enhancements for Database Reflection ----------------------------------------------------------------------------- The internal system by which :class:`.Table` objects and their components are -:ref:`reflected <metadata_reflection>` has been completely rearchitected to +ref_metadata_reflection has been completely rearchitected to allow high performance bulk reflection of thousands of tables at once for participating dialects. Currently, the **PostgreSQL** and **Oracle** dialects participate in the new architecture, where the PostgreSQL dialect can now @@ -1504,7 +1504,7 @@ automatically. .. seealso:: - :ref:`postgresql_psycopg` + ref_postgresql_psycopg .. _ticket_8054: @@ -1517,7 +1517,7 @@ DBAPI, which is the renamed, new major release of the popular cx_Oracle driver. .. seealso:: - :ref:`oracledb` + ref_oracledb .. _ticket_7631: @@ -2195,7 +2195,7 @@ customizable via the :paramref:`_sa.create_engine.poolclass` parameter. .. seealso:: - :ref:`pysqlite_threading_pooling` + ref_pysqlite_threading_pooling :ticket:`7490` @@ -2286,12 +2286,12 @@ All PostgreSQL search functions and operators are available through use of :data:`.func` to generate PostgreSQL-specific functions and :meth:`.Operators.bool_op` (a boolean-typed version of :meth:`.Operators.op`) to generate arbitrary operators, in the same manner as they are available -in previous versions. See the examples at :ref:`postgresql_match`. +in previous versions. See the examples at ref_postgresql_match. Existing SQLAlchemy projects that make use of PG-specific directives within :meth:`.Operators.match` should make use of ``func.to_tsquery()`` directly. To render SQL in exactly the same form as would be present -in 1.4, see the version note at :ref:`postgresql_simple_match`. +in 1.4, see the version note at ref_postgresql_simple_match. diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst index 488c2dfad..abb6d6c4c 100644 --- a/doc/build/core/connections.rst +++ b/doc/build/core/connections.rst @@ -411,15 +411,15 @@ reverted when a connection is returned to the connection pool. .. seealso:: - :ref:`SQLite Transaction Isolation <sqlite_isolation_level>` + ref_sqlite_isolation_level - :ref:`PostgreSQL Transaction Isolation <postgresql_isolation_level>` + ref_postgresql_isolation_level - :ref:`MySQL Transaction Isolation <mysql_isolation_level>` + ref_mysql_isolation_level - :ref:`SQL Server Transaction Isolation <mssql_isolation_level>` + ref_mssql_isolation_level - :ref:`Oracle Transaction Isolation <oracle_isolation_level>` + ref_oracle_isolation_level :ref:`session_transaction_isolation` - for the ORM @@ -852,8 +852,8 @@ as the schema name is passed to these methods explicitly. values into account for individual objects. To use a single :class:`_orm.Session` with multiple ``schema_translate_map`` - configurations, the :ref:`horizontal_sharding_toplevel` extension may - be used. See the example at :ref:`examples_sharding`. + configurations, the ref_horizontal_sharding_toplevel extension may + be used. See the example at ref_examples_sharding. .. _sql_caching: @@ -1765,7 +1765,7 @@ be used when the statement is invoked:: For a series of examples of "lambda" caching with performance comparisons, -see the "short_selects" test suite within the :ref:`examples_performance` +see the "short_selects" test suite within the ref_examples_performance performance example. .. _engine_insertmanyvalues: @@ -1820,7 +1820,7 @@ place when making use of the :meth:`_dml.Insert.returning` method of an execution, which occurs when passing a list of dictionaries to the :paramref:`_engine.Connection.execute.parameters` parameter of the :meth:`_engine.Connection.execute` or :meth:`_orm.Session.execute` methods (as -well as equivalent methods under :ref:`asyncio <asyncio_toplevel>` and +well as equivalent methods under ref_asyncio_toplevel and shorthand methods like :meth:`_orm.Session.scalars`). It also takes place within the ORM :term:`unit of work` process when using methods such as :meth:`_orm.Session.add` and :meth:`_orm.Session.add_all` to add rows. diff --git a/doc/build/core/constraints.rst b/doc/build/core/constraints.rst index 1efccdce5..de94e574b 100644 --- a/doc/build/core/constraints.rst +++ b/doc/build/core/constraints.rst @@ -412,13 +412,13 @@ Setting up Constraints when using the Declarative ORM Extension The :class:`_schema.Table` is the SQLAlchemy Core construct that allows one to define table metadata, which among other things can be used by the SQLAlchemy ORM -as a target to map a class. The :ref:`Declarative <declarative_toplevel>` +as a target to map a class. The ref_declarative_toplevel extension allows the :class:`_schema.Table` object to be created automatically, given the contents of the table primarily as a mapping of :class:`_schema.Column` objects. To apply table-level constraint objects such as :class:`_schema.ForeignKeyConstraint` to a table defined using Declarative, use the ``__table_args__`` attribute, -described at :ref:`declarative_table_args`. +described at ref_declarative_table_args. .. _constraint_naming_conventions: diff --git a/doc/build/core/custom_types.rst b/doc/build/core/custom_types.rst index 44187ee4c..da9178f86 100644 --- a/doc/build/core/custom_types.rst +++ b/doc/build/core/custom_types.rst @@ -311,7 +311,7 @@ dictionary-oriented JSON structure, we can apply this as:: .. seealso:: - :ref:`mutable_toplevel` + ref_mutable_toplevel Dealing with Comparison Operations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -695,7 +695,7 @@ It is important to note that database types which are modified to have additional in-Python behaviors, including types based on :class:`.TypeDecorator` as well as other user-defined subclasses of datatypes, do not have any representation within a database schema. When using database -the introspection features described at :ref:`metadata_reflection`, SQLAlchemy +the introspection features described at ref_metadata_reflection, SQLAlchemy makes use of a fixed mapping which links the datatype information reported by a database server to a SQLAlchemy datatype object. For example, if we look inside of a PostgreSQL schema at the definition for a particular database @@ -774,7 +774,7 @@ additional Python behaviors of the custom datatypes, additional steps must be taken to allow this. The most straightforward is to override specific columns as described at -:ref:`reflection_overriding_columns`. In this technique, we simply +ref_reflection_overriding_columns. In this technique, we simply use reflection in combination with explicit :class:`_schema.Column` objects for those columns for which we want to use a custom or decorated datatype:: diff --git a/doc/build/core/engines.rst b/doc/build/core/engines.rst index 696f058e6..5521978d4 100644 --- a/doc/build/core/engines.rst +++ b/doc/build/core/engines.rst @@ -192,7 +192,7 @@ MySQL DBAPIs available, including PyMySQL:: # PyMySQL engine = create_engine("mysql+pymysql://scott:tiger@localhost/foo") -More notes on connecting to MySQL at :ref:`mysql_toplevel`. +More notes on connecting to MySQL at ref_mysql_toplevel. Oracle ^^^^^^^^^^ @@ -203,7 +203,7 @@ The Oracle dialect uses cx_oracle as the default DBAPI:: engine = create_engine("oracle+cx_oracle://scott:tiger@tnsname") -More notes on connecting to Oracle at :ref:`oracle_toplevel`. +More notes on connecting to Oracle at ref_oracle_toplevel. Microsoft SQL Server ^^^^^^^^^^^^^^^^^^^^ @@ -217,7 +217,7 @@ also available:: # pymssql engine = create_engine("mssql+pymssql://scott:tiger@hostname:port/dbname") -More notes on connecting to SQL Server at :ref:`mssql_toplevel`. +More notes on connecting to SQL Server at ref_mssql_toplevel. SQLite ^^^^^^^ @@ -248,7 +248,7 @@ To use a SQLite ``:memory:`` database, specify an empty URL:: engine = create_engine("sqlite://") -More notes on connecting to SQLite at :ref:`sqlite_toplevel`. +More notes on connecting to SQLite at ref_sqlite_toplevel. Others ^^^^^^ @@ -291,7 +291,7 @@ application, rather than creating a new one for each connection. .. note:: :class:`.QueuePool` is not used by default for SQLite engines. See - :ref:`sqlite_toplevel` for details on SQLite connection pool usage. + ref_sqlite_toplevel for details on SQLite connection pool usage. For more information on connection pooling, see :ref:`pooling_toplevel`. @@ -424,7 +424,7 @@ parameter, this could be implemented as:: .. seealso:: - :ref:`mssql_pyodbc_access_tokens` - a more concrete example involving + ref_mssql_pyodbc_access_tokens - a more concrete example involving SQL Server Modifying the DBAPI connection after connect, or running commands after connect diff --git a/doc/build/core/metadata.rst b/doc/build/core/metadata.rst index 496697056..ac7a740bf 100644 --- a/doc/build/core/metadata.rst +++ b/doc/build/core/metadata.rst @@ -401,10 +401,10 @@ at once, such as:: .. seealso:: - :ref:`multipart_schema_names` - describes use of dotted schema names + ref_multipart_schema_names - describes use of dotted schema names with the SQL Server dialect. - :ref:`metadata_reflection_schemas` + ref_metadata_reflection_schemas .. _schema_metadata_schema_name: @@ -543,7 +543,7 @@ for specific information regarding how default schemas are configured. .. seealso:: - :ref:`postgresql_alternate_search_path` - in the :ref:`postgresql_toplevel` dialect documentation. + ref_postgresql_alternate_search_path - in the :ref:`postgresql_toplevel` dialect documentation. @@ -552,8 +552,8 @@ Schemas and Reflection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The schema feature of SQLAlchemy interacts with the table reflection -feature introduced at :ref:`metadata_reflection_toplevel`. See the section -:ref:`metadata_reflection_schemas` for additional details on how this works. +feature introduced at ref_metadata_reflection_toplevel. See the section +ref_metadata_reflection_schemas for additional details on how this works. Backend-Specific Options diff --git a/doc/build/core/pooling.rst b/doc/build/core/pooling.rst index 8e7f1592d..49993a792 100644 --- a/doc/build/core/pooling.rst +++ b/doc/build/core/pooling.rst @@ -214,8 +214,8 @@ consistent with the state of the transaction:: .. seealso:: - * :ref:`mssql_reset_on_return` - in the :ref:`mssql_toplevel` documentation - * :ref:`postgresql_reset_on_return` in the :ref:`postgresql_toplevel` documentation + * ref_mssql_reset_on_return - in the ref_mssql_toplevel documentation + * ref_postgresql_reset_on_return in the :ref:`postgresql_toplevel` documentation diff --git a/doc/build/dialects/postgresql.rst b/doc/build/dialects/postgresql.rst index faaff5b5a..c12cc8373 100644 --- a/doc/build/dialects/postgresql.rst +++ b/doc/build/dialects/postgresql.rst @@ -285,7 +285,7 @@ Illustrating insertion and selecting of a record:: as handled by the ORM will not automatically detect in-place changes to a particular list value; to update list values with the ORM, either re-assign a new list to the attribute, or use the :class:`.MutableList` - type modifier. See the section :ref:`mutable_toplevel` for background. + type modifier. See the section ref_mutable_toplevel for background. The available multirange datatypes are as follows: diff --git a/doc/build/errors.rst b/doc/build/errors.rst index ea76a9914..cee35f326 100644 --- a/doc/build/errors.rst +++ b/doc/build/errors.rst @@ -907,7 +907,7 @@ Mitigation of this error is via these techniques: :ref:`session_committing` - background on session commit - :ref:`session_expire` - background on attribute expiry + ref_session_expire - background on attribute expiry .. _error_7s2a: @@ -1327,7 +1327,7 @@ annotations within class definitions at runtime. A requirement of this form is that all ORM annotations must make use of a generic container called :class:`_orm.Mapped` to be properly annotated. Legacy SQLAlchemy mappings which include explicit :pep:`484` typing annotations, such as those which use the -:ref:`legacy Mypy extension <mypy_toplevel>` for typing support, may include +ref_mypy_toplevel for typing support, may include directives such as those for :func:`_orm.relationship` that don't include this generic. @@ -1346,7 +1346,7 @@ When transforming <cls> to a dataclass, attribute(s) originate from superclass < ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This warning occurs when using the SQLAlchemy ORM Mapped Dataclasses feature -described at :ref:`orm_declarative_native_dataclasses` in conjunction with +described at ref_orm_declarative_native_dataclasses in conjunction with any mixin class or abstract base that is not itself declared as a dataclass, such as in the example below:: @@ -1463,7 +1463,7 @@ attention to the rules applied to `inheritance <dc_superclass_>`_. .. seealso:: - :ref:`orm_declarative_native_dataclasses` - SQLAlchemy dataclasses documentation + ref_orm_declarative_native_dataclasses - SQLAlchemy dataclasses documentation `Python dataclasses <dataclasses_>`_ - on the python.org website @@ -1491,7 +1491,7 @@ with a non compatible :term:`DBAPI`. .. seealso:: - :ref:`asyncio_toplevel` + ref_asyncio_toplevel .. _error_xd2s: @@ -1506,7 +1506,7 @@ attempt, which is unsupported when using SQLAlchemy with AsyncIO dialects. .. seealso:: - :ref:`asyncio_orm_avoid_lazyloads` - covers most ORM scenarios where + ref_asyncio_orm_avoid_lazyloads - covers most ORM scenarios where this problem can occur and how to mitigate. .. _error_xd3s: @@ -1534,7 +1534,7 @@ that performs the desired operations:: .. seealso:: - :ref:`asyncio_inspector` - additional examples of using :func:`_sa.inspect` + ref_asyncio_inspector - additional examples of using :func:`_sa.inspect` with the asyncio extension. diff --git a/doc/build/faq/connections.rst b/doc/build/faq/connections.rst index b0c354c00..1af2b583c 100644 --- a/doc/build/faq/connections.rst +++ b/doc/build/faq/connections.rst @@ -402,7 +402,7 @@ current SQLAlchemy versions. .. seealso:: - :ref:`pysqlite_threading_pooling` - info on PySQLite's behavior. + ref_pysqlite_threading_pooling - info on PySQLite's behavior. .. _faq_dbapi_connection: diff --git a/doc/build/faq/installation.rst b/doc/build/faq/installation.rst index 72b4fc159..7e77a3eb0 100644 --- a/doc/build/faq/installation.rst +++ b/doc/build/faq/installation.rst @@ -21,11 +21,11 @@ to the ``pip install`` command: pip install sqlalchemy[asyncio] -For more background, see :ref:`asyncio_install`. +For more background, see ref_asyncio_install. .. seealso:: - :ref:`asyncio_install` + ref_asyncio_install diff --git a/doc/build/faq/performance.rst b/doc/build/faq/performance.rst index aa8d4e314..ad0195cd3 100644 --- a/doc/build/faq/performance.rst +++ b/doc/build/faq/performance.rst @@ -439,7 +439,7 @@ Common strategies to mitigate this include: for user, address in session.execute(select(u_b, a_b).join(User.addresses)): ... -* Use result caching - see :ref:`examples_caching` for an in-depth example +* Use result caching - see ref_examples_caching for an in-depth example of this. * Consider a faster interpreter like that of PyPy. @@ -449,7 +449,7 @@ practice they are very easy to read. .. seealso:: - :ref:`examples_performance` - a suite of performance demonstrations + ref_examples_performance - a suite of performance demonstrations with bundled profiling capabilities. I'm inserting 400,000 rows with the ORM and it's really slow! diff --git a/doc/build/faq/sessions.rst b/doc/build/faq/sessions.rst index a2c61c0a4..80d587aee 100644 --- a/doc/build/faq/sessions.rst +++ b/doc/build/faq/sessions.rst @@ -64,7 +64,7 @@ Three ways, from most common to least: 2. We tell our :class:`.Session` to re-read rows that it has already read, either when we next query for them using :meth:`.Session.expire_all` or :meth:`.Session.expire`, or immediately on an object using - :class:`.Session.refresh`. See :ref:`session_expire` for detail on this. + :class:`.Session.refresh`. See ref_session_expire for detail on this. 3. We can run whole queries while setting them to definitely overwrite already-loaded objects as they read rows by using "populate existing". diff --git a/doc/build/glossary.rst b/doc/build/glossary.rst index 21c8a6ebf..c7db2439d 100644 --- a/doc/build/glossary.rst +++ b/doc/build/glossary.rst @@ -88,7 +88,7 @@ Glossary .. seealso:: - :ref:`metadata_reflection_toplevel` - complete background on + ref_metadata_reflection_toplevel - complete background on database reflection. :ref:`orm_declarative_reflected` - background on integrating @@ -461,9 +461,9 @@ Glossary .. seealso:: - :ref:`mapper_version_counter` - SQLAlchemy's built-in version id feature. + ref_mapper_version_counter - SQLAlchemy's built-in version id feature. - :ref:`examples_versioning` - other examples of mappings that version rows + ref_examples_versioning - other examples of mappings that version rows temporally. registry @@ -613,8 +613,8 @@ Glossary :doc:`orm/queryguide/relationships` - includes information on lazy loading of ORM related objects - :ref:`asyncio_orm_avoid_lazyloads` - tips on avoiding lazy loading - when using the :ref:`asyncio_toplevel` extension + ref_asyncio_orm_avoid_lazyloads - tips on avoiding lazy loading + when using the ref_asyncio_toplevel extension eager load eager loads @@ -824,7 +824,7 @@ Glossary .. seealso:: - :ref:`session_expire` + ref_session_expire Session The container or scope for ORM database operations. Sessions @@ -1623,7 +1623,7 @@ Glossary .. seealso:: - :ref:`session_object_states` + ref_session_object_states pending This describes one of the major object states which @@ -1635,7 +1635,7 @@ Glossary .. seealso:: - :ref:`session_object_states` + ref_session_object_states deleted This describes one of the major object states which @@ -1650,7 +1650,7 @@ Glossary .. seealso:: - :ref:`session_object_states` + ref_session_object_states persistent This describes one of the major object states which @@ -1665,7 +1665,7 @@ Glossary .. seealso:: - :ref:`session_object_states` + ref_session_object_states detached This describes one of the major object states which @@ -1681,7 +1681,7 @@ Glossary .. seealso:: - :ref:`session_object_states` + ref_session_object_states attached Indicates an ORM object that is presently associated with a specific @@ -1689,5 +1689,5 @@ Glossary .. seealso:: - :ref:`session_object_states` + ref_session_object_states diff --git a/doc/build/index.rst b/doc/build/index.rst index 37b807723..fa7a609b4 100644 --- a/doc/build/index.rst +++ b/doc/build/index.rst @@ -80,20 +80,15 @@ SQLAlchemy Documentation * **Using the ORM:** :doc:`Using the ORM Session <orm/session>` | :doc:`ORM Querying Guide <orm/queryguide/index>` | - :doc:`Using AsyncIO <orm/extensions/asyncio>` * **Configuration Extensions:** - :doc:`Association Proxy <orm/extensions/associationproxy>` | - :doc:`Hybrid Attributes <orm/extensions/hybrid>` | - :doc:`Mutable Scalars <orm/extensions/mutable>` | - :doc:`Automap <orm/extensions/automap>` | - :doc:`All extensions <orm/extensions/index>` + none... * **Extending the ORM:** :doc:`ORM Events and Internals <orm/extending>` * **Other:** - :doc:`Introduction to Examples <orm/examples>` + none .. container:: core @@ -102,14 +97,13 @@ SQLAlchemy Documentation * **Engines, Connections, Pools:** :doc:`Engine Configuration <core/engines>` | :doc:`Connections, Transactions, Results <core/connections>` | - :doc:`AsyncIO Support <orm/extensions/asyncio>` | :doc:`Connection Pooling <core/pooling>` * **Schema Definition:** :doc:`Overview <core/schema>` | :ref:`Tables and Columns <metadata_describing_toplevel>` | - :ref:`Database Introspection (Reflection) <metadata_reflection_toplevel>` | - :ref:`Insert/Update Defaults <metadata_defaults_toplevel>` | + ref_metadata_reflection_toplevel | + ref_metadata_defaults_toplevel | :ref:`Constraints and Indexes <metadata_constraints_toplevel>` | :ref:`Using Data Definition Language (DDL) <metadata_ddl_toplevel>` @@ -118,7 +112,6 @@ SQLAlchemy Documentation :doc:`Operator Reference <core/operators>` | :doc:`SELECT and related constructs <core/selectable>` | :doc:`INSERT, UPDATE, DELETE <core/dml>` | - :doc:`SQL Functions <core/functions>` | :doc:`Table of Contents <core/expression_api>` @@ -130,7 +123,6 @@ SQLAlchemy Documentation * **Core Basics:** :doc:`Overview <core/api_basics>` | - :doc:`Runtime Inspection API <core/inspection>` | :doc:`Event System <core/event>` | :doc:`Core Event Interfaces <core/events>` | :doc:`Creating Custom SQL Constructs <core/compiler>` @@ -149,10 +141,6 @@ SQLAlchemy Documentation This section describes notes, options, and usage patterns regarding individual dialects. :doc:`PostgreSQL <dialects/postgresql>` | - :doc:`MySQL <dialects/mysql>` | - :doc:`SQLite <dialects/sqlite>` | - :doc:`Oracle <dialects/oracle>` | - :doc:`Microsoft SQL Server <dialects/mssql>` :doc:`More Dialects ... <dialects/index>` diff --git a/doc/build/intro.rst b/doc/build/intro.rst index cac103ed8..ef469ca68 100644 --- a/doc/build/intro.rst +++ b/doc/build/intro.rst @@ -80,7 +80,7 @@ Code Examples Working code examples, mostly regarding the ORM, are included in the SQLAlchemy distribution. A description of all the included example -applications is at :ref:`examples_toplevel`. +applications is at ref_examples_toplevel. There is also a wide variety of examples involving both core SQLAlchemy constructs as well as the ORM on the wiki. See @@ -109,7 +109,7 @@ SQLAlchemy's ``asyncio`` support depends upon the `greenlet <https://pypi.org/project/greenlet/>`_ project. This dependency will be installed by default on common machine platforms, however is not supported on every architecture and also may not install by default on -less common architectures. See the section :ref:`asyncio_install` for +less common architectures. See the section ref_asyncio_install for additional details on ensuring asyncio support is present. Supported Installation Methods diff --git a/doc/build/orm/basic_relationships.rst b/doc/build/orm/basic_relationships.rst index 91353681e..6be7f8bfe 100644 --- a/doc/build/orm/basic_relationships.rst +++ b/doc/build/orm/basic_relationships.rst @@ -716,14 +716,14 @@ association object:: To enhance the association object pattern such that direct access to the ``Association`` object is optional, SQLAlchemy -provides the :ref:`associationproxy_toplevel` extension. This +provides the ref_associationproxy_toplevel extension. This extension allows the configuration of attributes which will access two "hops" with a single access, one "hop" to the associated object, and a second to a target attribute. .. seealso:: - :ref:`associationproxy_toplevel` - allows direct "many to many" style + ref_associationproxy_toplevel - allows direct "many to many" style access between parent and child for a three-class association object mapping. .. warning:: @@ -731,7 +731,7 @@ associated object, and a second to a target attribute. Avoid mixing the association object pattern with the :ref:`many-to-many <relationships_many_to_many>` pattern directly, as this produces conditions where data may be read and written in an inconsistent fashion without special steps; - the :ref:`association proxy <associationproxy_toplevel>` is typically + the ref_associationproxy_toplevel is typically used to provide more succinct access. For more detailed background on the caveats introduced by this combination, see the next section :ref:`association_pattern_w_m2m`. @@ -899,11 +899,11 @@ A popular alternative to the above pattern is one where the direct many-to-many ``Parent.children`` and ``Child.parents`` relationships are replaced with an extension that will transparently proxy through the ``Association`` class, while keeping everything consistent from the ORM's point of -view. This extension is known as the :ref:`Association Proxy <associationproxy_toplevel>`. +view. This extension is known as the ref_associationproxy_toplevel. .. seealso:: - :ref:`associationproxy_toplevel` - allows direct "many to many" style + ref_associationproxy_toplevel - allows direct "many to many" style access between parent and child for a three-class association object mapping. .. _orm_declarative_relationship_eval: diff --git a/doc/build/orm/cascades.rst b/doc/build/orm/cascades.rst index 02d68669e..458dd5f7b 100644 --- a/doc/build/orm/cascades.rst +++ b/doc/build/orm/cascades.rst @@ -60,9 +60,9 @@ it is no longer associated with that parent. .. warning:: The ``all`` cascade option implies the :ref:`cascade_refresh_expire` cascade setting which may not be desirable when using the - :ref:`asyncio_toplevel` extension, as it will expire related objects + ref_asyncio_toplevel extension, as it will expire related objects more aggressively than is typically appropriate in an explicit IO context. - See the notes at :ref:`asyncio_orm_avoid_lazyloads` for further background. + See the notes at ref_asyncio_orm_avoid_lazyloads for further background. The list of available values which can be specified for the :paramref:`_orm.relationship.cascade` parameter are described in the following subsections. @@ -457,10 +457,10 @@ is as follows: support ``FOREIGN KEY`` constraints and they must be enforcing: * When using MySQL, an appropriate storage engine must be - selected. See :ref:`mysql_storage_engines` for details. + selected. See ref_mysql_storage_engines for details. * When using SQLite, foreign key support must be enabled explicitly. - See :ref:`sqlite_foreign_keys` for details. + See ref_sqlite_foreign_keys for details. .. topic:: Notes on Passive Deletes diff --git a/doc/build/orm/collection_api.rst b/doc/build/orm/collection_api.rst index 2d56bb9b2..3674dc81b 100644 --- a/doc/build/orm/collection_api.rst +++ b/doc/build/orm/collection_api.rst @@ -293,7 +293,7 @@ with a ``@property`` as mentioned earlier:: ) Dictionary mappings are often combined with the "Association Proxy" extension to produce -streamlined dictionary views. See :ref:`proxying_dictionaries` and :ref:`composite_association_proxy` +streamlined dictionary views. See ref_proxying_dictionaries and ref_composite_association_proxy for examples. .. _key_collections_mutations: @@ -400,7 +400,7 @@ about how the collection operates. of validation and simple marshaling. See :ref:`simple_validators` for an example of this. - For the second use case, the :ref:`associationproxy_toplevel` extension is a + For the second use case, the ref_associationproxy_toplevel extension is a well-tested, widely used system that provides a read/write "view" of a collection in terms of some attribute present on the target object. As the target attribute can be a ``@property`` that returns virtually anything, a diff --git a/doc/build/orm/declarative_config.rst b/doc/build/orm/declarative_config.rst index 873f16aff..99c7451ee 100644 --- a/doc/build/orm/declarative_config.rst +++ b/doc/build/orm/declarative_config.rst @@ -84,7 +84,7 @@ SQL expression mapped by :func:`_orm.column_property`, and an additional "deferred" basis as defined by the :paramref:`_orm.mapped_column.deferred` keyword. More documentation on these particular concepts may be found at :ref:`relationship_patterns`, -:ref:`mapper_column_property_sql_expressions`, and :ref:`orm_queryguide_column_deferral`. +ref_mapper_column_property_sql_expressions, and :ref:`orm_queryguide_column_deferral`. Properties may be specified with a declarative mapping as above using "hybrid table" style as well; the :class:`_schema.Column` objects that @@ -218,7 +218,7 @@ an ORM-maintained version counter that is updated and checked within the .. seealso:: - :ref:`mapper_version_counter` - background on the ORM version counter feature + ref_mapper_version_counter - background on the ORM version counter feature **Single Table Inheritance** @@ -406,7 +406,7 @@ be illustrated using :meth:`_orm.registry.mapped` as follows:: ``__abstract__`` causes declarative to skip the production of a table or mapper for the class entirely. A class can be added within a -hierarchy in the same way as mixin (see :ref:`declarative_mixins`), allowing +hierarchy in the same way as mixin (see ref_declarative_mixins), allowing subclasses to extend just from the special class:: class SomeAbstractBase(Base): diff --git a/doc/build/orm/declarative_mixins.rst b/doc/build/orm/declarative_mixins.rst index cf721cb4a..e46af29a9 100644 --- a/doc/build/orm/declarative_mixins.rst +++ b/doc/build/orm/declarative_mixins.rst @@ -141,7 +141,7 @@ attribute is used on the newly defined class. :func:`_orm.mapped_column`. .. versionchanged:: 2.0 For users coming from the 1.4 series of SQLAlchemy - who may have been using the :ref:`mypy plugin <mypy_toplevel>`, the + who may have been using the ref_mypy_toplevel, the :func:`_orm.declarative_mixin` class decorator is no longer needed to mark declarative mixins, assuming the mypy plugin is no longer in use. diff --git a/doc/build/orm/declarative_tables.rst b/doc/build/orm/declarative_tables.rst index 0ee40cd07..abd021950 100644 --- a/doc/build/orm/declarative_tables.rst +++ b/doc/build/orm/declarative_tables.rst @@ -130,7 +130,7 @@ itself (more on this at :ref:`mapper_column_distinct_names`). .. seealso:: - :ref:`mapping_columns_toplevel` - contains additional notes on affecting + ref_mapping_columns_toplevel - contains additional notes on affecting how :class:`_orm.Mapper` interprets incoming :class:`.Column` objects. .. _orm_declarative_mapped_column: @@ -890,7 +890,7 @@ Dataclass features in ``mapped_column()`` The :func:`_orm.mapped_column` construct integrates with SQLAlchemy's "native dataclasses" feature, discussed at -:ref:`orm_declarative_native_dataclasses`. See that section for current +ref_orm_declarative_native_dataclasses. See that section for current background on additional directives supported by :func:`_orm.mapped_column`. @@ -911,7 +911,7 @@ available via the ``__table__`` attribute:: The above table is ultimately the same one that corresponds to the :attr:`_orm.Mapper.local_table` attribute, which we can see through the -:ref:`runtime inspection system <inspection_toplevel>`:: +ref_inspection_toplevel:: from sqlalchemy import inspect @@ -1268,13 +1268,13 @@ the sections :ref:`orm_mapping_joins` and :ref:`orm_mapping_arbitrary_subqueries The "imperative table" form is of particular use when the class itself is using an alternative form of attribute declaration, such as Python -dataclasses. See the section :ref:`orm_declarative_dataclasses` for detail. +dataclasses. See the section ref_orm_declarative_dataclasses for detail. .. seealso:: :ref:`metadata_describing` - :ref:`orm_declarative_dataclasses` + ref_orm_declarative_dataclasses .. _orm_imperative_table_column_naming: @@ -1407,7 +1407,7 @@ associate additional parameters with the column. Options include: * :ref:`maptojoin` - * :ref:`mapper_sql_expressions` + * ref_mapper_sql_expressions For Declarative Table configuration with :func:`_orm.mapped_column`, most options are available directly; see the section @@ -1423,7 +1423,7 @@ Mapping Declaratively with Reflected Tables There are several patterns available which provide for producing mapped classes against a series of :class:`_schema.Table` objects that were introspected from the database, using the reflection process described at -:ref:`metadata_reflection`. +ref_metadata_reflection. A simple way to map a class to a table reflected from the database is to use a declarative hybrid mapping, passing the @@ -1535,7 +1535,7 @@ Using Automap ^^^^^^^^^^^^^^ A more automated solution to mapping against an existing database where table -reflection is to be used is to use the :ref:`automap_toplevel` extension. This +reflection is to be used is to use the ref_automap_toplevel extension. This extension will generate entire mapped classes from a database schema, including relationships between classes based on observed foreign key constraints. While it includes hooks for customization, such as hooks that allow custom @@ -1547,7 +1547,7 @@ class may be preferable for its less automated approach. .. seealso:: - :ref:`automap_toplevel` + ref_automap_toplevel .. _mapper_automated_reflection_schemes: @@ -1596,8 +1596,8 @@ with our event that adds a new ".key" element, such as in a mapping as below:: __table__ = Table("some_table", Base.metadata, autoload_with=some_engine) The approach also works with both the :class:`.DeferredReflection` base class -as well as with the :ref:`automap_toplevel` extension. For automap -specifically, see the section :ref:`automap_intercepting_columns` for +as well as with the ref_automap_toplevel extension. For automap +specifically, see the section ref_automap_intercepting_columns for background. .. seealso:: @@ -1606,7 +1606,7 @@ background. :meth:`_events.DDLEvents.column_reflect` - :ref:`automap_intercepting_columns` - in the :ref:`automap_toplevel` documentation + ref_automap_intercepting_columns - in the ref_automap_toplevel documentation .. _mapper_primary_key: @@ -1723,7 +1723,7 @@ still be in effect** for those :class:`_schema.Column` objects that include them even though they may be excluded from the ORM mapping. "Schema level column defaults" refers to the defaults described at -:ref:`metadata_defaults` including those configured by the +ref_metadata_defaults including those configured by the :paramref:`_schema.Column.default`, :paramref:`_schema.Column.onupdate`, :paramref:`_schema.Column.server_default` and :paramref:`_schema.Column.server_onupdate` parameters. These constructs diff --git a/doc/build/orm/events.rst b/doc/build/orm/events.rst index 1db1137e0..19ad55703 100644 --- a/doc/build/orm/events.rst +++ b/doc/build/orm/events.rst @@ -91,7 +91,7 @@ Attribute Events Attribute events are triggered as things occur on individual attributes of ORM mapped objects. These events form the basis for things like :ref:`custom validation functions <simple_validators>` as well as -:ref:`backref handlers <relationships_backref>`. +ref_relationships_backref. .. seealso:: diff --git a/doc/build/orm/inheritance.rst b/doc/build/orm/inheritance.rst index 6746a0cda..1645717a4 100644 --- a/doc/build/orm/inheritance.rst +++ b/doc/build/orm/inheritance.rst @@ -21,7 +21,7 @@ return objects of multiple types. :ref:`loading_joined_inheritance` - in the :ref:`queryguide_toplevel` - :ref:`examples_inheritance` - complete examples of joined, single and + ref_examples_inheritance - complete examples of joined, single and concrete inheritance .. _joined_inheritance: diff --git a/doc/build/orm/internals.rst b/doc/build/orm/internals.rst index 9bb7e83a4..529baf1d1 100644 --- a/doc/build/orm/internals.rst +++ b/doc/build/orm/internals.rst @@ -22,8 +22,8 @@ sections, are listed here. .. autoclass:: Composite -.. autoclass:: CompositeProperty - :members: +.. .. autoclass:: CompositeProperty + .. :members: .. autoclass:: AttributeEventToken :members: diff --git a/doc/build/orm/join_conditions.rst b/doc/build/orm/join_conditions.rst index 79c3e98ad..7a21a13d4 100644 --- a/doc/build/orm/join_conditions.rst +++ b/doc/build/orm/join_conditions.rst @@ -105,7 +105,7 @@ one :class:`_schema.Column` we need:: .. warning:: When passed as a Python-evaluable string, the :paramref:`_orm.relationship.foreign_keys` argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See - :ref:`declarative_relationship_eval` for details on declarative + ref_declarative_relationship_eval for details on declarative evaluation of :func:`_orm.relationship` arguments. @@ -168,7 +168,7 @@ argument. :paramref:`_orm.relationship.primaryjoin` argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. See - :ref:`declarative_relationship_eval` for details on declarative + ref_declarative_relationship_eval for details on declarative evaluation of :func:`_orm.relationship` arguments. @@ -600,7 +600,7 @@ use the string name of the table as it is present in the :class:`_schema.MetaDat :paramref:`_orm.relationship.primaryjoin` and :paramref:`_orm.relationship.secondaryjoin` arguments are interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THESE - STRINGS**. See :ref:`declarative_relationship_eval` for details on + STRINGS**. See ref_declarative_relationship_eval for details on declarative evaluation of :func:`_orm.relationship` arguments. diff --git a/doc/build/orm/mapped_attributes.rst b/doc/build/orm/mapped_attributes.rst index d0610f4e0..6f23f6f57 100644 --- a/doc/build/orm/mapped_attributes.rst +++ b/doc/build/orm/mapped_attributes.rst @@ -252,7 +252,7 @@ attribute, a SQL function is rendered which produces the same effect: (0, 12, 'address') {stop} -Read more about Hybrids at :ref:`hybrids_toplevel`. +Read more about Hybrids at ref_hybrids_toplevel. .. _synonyms: diff --git a/doc/build/orm/mapping_api.rst b/doc/build/orm/mapping_api.rst index 57ef5e00e..578c77948 100644 --- a/doc/build/orm/mapping_api.rst +++ b/doc/build/orm/mapping_api.rst @@ -76,7 +76,7 @@ Class Mapping API .. seealso:: - :ref:`declarative_inheritance` + ref_declarative_inheritance :ref:`mixin_inheritance_columns` diff --git a/doc/build/orm/mapping_styles.rst b/doc/build/orm/mapping_styles.rst index b4c21a353..4f650c593 100644 --- a/doc/build/orm/mapping_styles.rst +++ b/doc/build/orm/mapping_styles.rst @@ -364,7 +364,7 @@ An object of type ``User`` above will have a constructor which allows .. tip:: - The :ref:`orm_declarative_native_dataclasses` feature provides an alternate + The ref_orm_declarative_native_dataclasses feature provides an alternate means of generating a default ``__init__()`` method by using Python dataclasses, and allows for a highly configurable constructor form. @@ -453,7 +453,7 @@ Inspection of Mapper objects As illustrated in the previous section, the :class:`_orm.Mapper` object is available from any mapped class, regardless of method, using the -:ref:`core_inspection_toplevel` system. Using the +ref_core_inspection_toplevel system. Using the :func:`_sa.inspect` function, one can acquire the :class:`_orm.Mapper` from a mapped class:: @@ -528,7 +528,7 @@ The :class:`_orm.Session` to which the object is :term:`attached`, if any:: >>> insp.session <sqlalchemy.orm.session.Session object at 0x7f07e614f160> -Information about the current :ref:`persistence state <session_object_states>` +Information about the current ref_session_object_states for the object:: >>> insp.persistent diff --git a/doc/build/orm/persistence_techniques.rst b/doc/build/orm/persistence_techniques.rst index dca6cefff..d28965bf9 100644 --- a/doc/build/orm/persistence_techniques.rst +++ b/doc/build/orm/persistence_techniques.rst @@ -248,7 +248,7 @@ value and pass it through, rather than omitting it as a "missing" value:: Fetching Server-Generated Defaults =================================== -As introduced in the sections :ref:`server_defaults` and :ref:`triggered_columns`, +As introduced in the sections ref_server_defaults and ref_triggered_columns, the Core supports the notion of database columns for which the database itself generates a value upon INSERT and in less common cases upon UPDATE statements. The ORM features support for such columns regarding being @@ -375,7 +375,7 @@ to retreive the newly generated primary key value: .. seealso:: - :ref:`mssql_insert_behavior` - background on the SQL Server dialect's + ref_mssql_insert_behavior - background on the SQL Server dialect's methods of fetching newly generated primary key values Case 3: non primary key, RETURNING or equivalent is not supported or not needed @@ -574,7 +574,7 @@ INSERT looks like: .. seealso:: - :ref:`metadata_defaults_toplevel` + ref_metadata_defaults_toplevel Notes on eagerly fetching client invoked SQL expressions used for INSERT or UPDATE ----------------------------------------------------------------------------------- @@ -584,7 +584,7 @@ to create tables that include default-generation functions within their DDL. SQLAlchemy also supports non-DDL server side defaults, as documented at -:ref:`defaults_client_invoked_sql`; these "client invoked SQL expressions" +ref_defaults_client_invoked_sql; these "client invoked SQL expressions" are set up using the :paramref:`_schema.Column.default` and :paramref:`_schema.Column.onupdate` parameters. @@ -826,8 +826,8 @@ Horizontal partitioning partitions the rows of a single table (or a set of tables) across multiple databases. The SQLAlchemy :class:`.Session` contains support for this concept, however to use it fully requires that :class:`.Session` and :class:`_query.Query` subclasses are used. A basic version -of these subclasses are available in the :ref:`horizontal_sharding_toplevel` -ORM extension. An example of use is at: :ref:`examples_sharding`. +of these subclasses are available in the ref_horizontal_sharding_toplevel +ORM extension. An example of use is at: ref_examples_sharding. .. _bulk_operations: diff --git a/doc/build/orm/queryguide/api.rst b/doc/build/orm/queryguide/api.rst index 15301cbd0..a5b155447 100644 --- a/doc/build/orm/queryguide/api.rst +++ b/doc/build/orm/queryguide/api.rst @@ -118,7 +118,7 @@ The ``populate_existing`` execution option is equvialent to the :ref:`faq_session_identity` - in :doc:`/faq/index` - :ref:`session_expire` - in the ORM :class:`_orm.Session` + ref_session_expire - in the ORM :class:`_orm.Session` documentation .. _orm_queryguide_autoflush: @@ -288,7 +288,7 @@ Identity Token .. doctest-disable: .. deepalchemy:: This option is an advanced-use feature mostly intended - to be used with the :ref:`horizontal_sharding_toplevel` extension. For + to be used with the ref_horizontal_sharding_toplevel extension. For typical cases of loading objects with identical primary keys from different "shards" or partitions, consider using individual :class:`_orm.Session` objects per shard first. @@ -300,7 +300,7 @@ first and foremost to support extensions which perform per-row "sharding", where objects may be loaded from any number of replicas of a particular database table that nonetheless have overlapping primary key values. The primary consumer of "identity token" is the -:ref:`horizontal_sharding_toplevel` extension, which supplies a general +ref_horizontal_sharding_toplevel extension, which supplies a general framework for persisting objects among multiple "shards" of a particular database table. @@ -361,7 +361,7 @@ into both ``test_schema.my_table`` as well as ``test_schema_2.my_table``. The :class:`_orm.Session` objects above are independent. If we wanted to persist both objects in one transaction, we would need to use the -:ref:`horizontal_sharding_toplevel` extension to do this. +ref_horizontal_sharding_toplevel extension to do this. However, we can illustrate querying for these objects in one session as follows: @@ -399,14 +399,14 @@ to view the two distinct identity tokens:: The above logic takes place automatically when using the -:ref:`horizontal_sharding_toplevel` extension. +ref_horizontal_sharding_toplevel extension. .. versionadded:: 2.0.0rc1 - added the ``identity_token`` ORM level execution option. .. seealso:: - :ref:`examples_sharding` - in the :ref:`examples_toplevel` section. + ref_examples_sharding - in the ref_examples_toplevel section. See the script ``separate_schema_translates.py`` for a demonstration of the above use case using the full sharding API. diff --git a/doc/build/orm/queryguide/columns.rst b/doc/build/orm/queryguide/columns.rst index 255c1f902..56dbec238 100644 --- a/doc/build/orm/queryguide/columns.rst +++ b/doc/build/orm/queryguide/columns.rst @@ -104,7 +104,7 @@ See the section :ref:`orm_queryguide_deferred_raiseload` for background and examples. .. tip:: as noted elsewhere, lazy loading is not available when using - :ref:`asyncio_toplevel`. + ref_asyncio_toplevel. Using ``load_only()`` with multiple entities ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -437,8 +437,8 @@ when mapped SQL expressions should be loaded on a deferred basis: .. seealso:: - :ref:`mapper_column_property_sql_expressions` - in the section - :ref:`mapper_sql_expressions` + ref_mapper_column_property_sql_expressions - in the section + ref_mapper_sql_expressions :ref:`orm_imperative_table_column_options` - in the section :ref:`orm_declarative_table_config_toplevel` @@ -823,7 +823,7 @@ The :func:`.query_expression` mapping has these caveats: The :func:`_orm.with_expression` option is a special option used to apply SQL expressions to mapped classes dynamically at query time. For ordinary fixed SQL expressions configured on mappers, - see the section :ref:`mapper_sql_expressions`. + see the section ref_mapper_sql_expressions. .. _orm_queryguide_with_expression_unions: diff --git a/doc/build/orm/queryguide/dml.rst b/doc/build/orm/queryguide/dml.rst index 04a4fb2bb..ce3687d0b 100644 --- a/doc/build/orm/queryguide/dml.rst +++ b/doc/build/orm/queryguide/dml.rst @@ -75,7 +75,7 @@ as much as possible for many rows:: The parameter dictionaries contain key/value pairs which may correspond to ORM mapped attributes that line up with mapped :class:`._schema.Column` or :func:`_orm.mapped_column` declarations, as well as with -:ref:`composite <mapper_composite>` declarations. The keys should match +ref_mapper_composite declarations. The keys should match the **ORM mapped attribute name** and **not** the actual database column name, if these two names happen to be different. @@ -510,9 +510,9 @@ on the capabilities of the backend in use. The dialects included with SQLAlchemy that include dialect-specific "upsert" API features are: -* SQLite - using :class:`_sqlite.Insert` documented at :ref:`sqlite_on_conflict_insert` -* PostgreSQL - using :class:`_postgresql.Insert` documented at :ref:`postgresql_insert_on_conflict` -* MySQL/MariaDB - using :class:`_mysql.Insert` documented at :ref:`mysql_insert_on_duplicate_key_update` +* SQLite - using :class:`_sqlite.Insert` documented at ref_sqlite_on_conflict_insert +* PostgreSQL - using :class:`_postgresql.Insert` documented at ref_postgresql_insert_on_conflict +* MySQL/MariaDB - using :class:`_mysql.Insert` documented at ref_mysql_insert_on_duplicate_key_update Users should review the above sections for background on proper construction of these objects; in particular, the "upsert" method typically needs to diff --git a/doc/build/orm/queryguide/inheritance.rst b/doc/build/orm/queryguide/inheritance.rst index 7040128f4..00612dea5 100644 --- a/doc/build/orm/queryguide/inheritance.rst +++ b/doc/build/orm/queryguide/inheritance.rst @@ -100,7 +100,7 @@ loaded, in the case that the consuming application will need to be accessing subclass-specific attributes, as this would be an example of the :term:`N plus one` problem that emits additional SQL per row. This additional SQL can impact performance and also be incompatible with approaches such as -using :ref:`asyncio <asyncio_toplevel>`. Additionally, in our query for +using ref_asyncio_toplevel. Additionally, in our query for ``Employee`` objects, since the query is against the base table only, we did not have a way to add SQL criteria involving subclass-specific attributes in terms of ``Manager`` or ``Engineer``. The next two sections detail two diff --git a/doc/build/orm/queryguide/relationships.rst b/doc/build/orm/queryguide/relationships.rst index 9c621ea9a..70f9d318c 100644 --- a/doc/build/orm/queryguide/relationships.rst +++ b/doc/build/orm/queryguide/relationships.rst @@ -92,7 +92,7 @@ The primary forms of relationship loading are: :meth:`.WriteOnlyCollection.add_all` and :meth:`.WriteOnlyCollection.remove` methods. Querying the collection is performed by invoking a SELECT statement which is constructed using the :meth:`.WriteOnlyCollection.select` - method. Write only loading is discussed at :ref:`write_only_relationship`. + method. Write only loading is discussed at ref_write_only_relationship. * **dynamic loading** - available via ``lazy='dynamic'``, or by annotating the left side of the :class:`_orm.Relationship` object using the @@ -102,9 +102,9 @@ The primary forms of relationship loading are: contents. However, dynamic loaders will implicitly iterate the underlying collection in various circumstances which makes them less useful for managing truly large collections. Dynamic loaders are superseded by - :ref:`"write only" <write_only_relationship>` collections, which will prevent + ref_write_only_relationship collections, which will prevent the underlying collection from being implicitly loaded under any - circumstances. Dynamic loaders are discussed at :ref:`dynamic_relationship`. + circumstances. Dynamic loaders are discussed at ref_dynamic_relationship. .. _relationship_lazy_option: diff --git a/doc/build/orm/quickstart.rst b/doc/build/orm/quickstart.rst index 652ed235a..73bb30815 100644 --- a/doc/build/orm/quickstart.rst +++ b/doc/build/orm/quickstart.rst @@ -121,7 +121,7 @@ The :func:`_orm.relationship` construct is introduced in the Finally, the above example classes include a ``__repr__()`` method, which is not required but is useful for debugging. Mapped classes can be created with methods such as ``__repr__()`` generated automatically, using dataclasses. More -on dataclass mapping at :ref:`orm_declarative_native_dataclasses`. +on dataclass mapping at ref_orm_declarative_native_dataclasses. Create an Engine @@ -131,7 +131,7 @@ Create an Engine The :class:`_engine.Engine` is a **factory** that can create new database connections for us, which also holds onto connections inside of a :ref:`Connection Pool <pooling_toplevel>` for fast reuse. For learning -purposes, we normally use a :ref:`SQLite <sqlite_toplevel>` memory-only database +purposes, we normally use a ref_sqlite_toplevel memory-only database for convenience:: >>> from sqlalchemy import create_engine diff --git a/doc/build/orm/relationship_persistence.rst b/doc/build/orm/relationship_persistence.rst index 9a5a036c6..f56773caa 100644 --- a/doc/build/orm/relationship_persistence.rst +++ b/doc/build/orm/relationship_persistence.rst @@ -223,7 +223,7 @@ object, and we also illustrate the ``mysql_engine='InnoDB'`` setting which, on a MySQL backend, ensures that the ``InnoDB`` engine supporting referential integrity is used. When using SQLite, referential integrity should be enabled, using the configuration described at -:ref:`sqlite_foreign_keys`. +ref_sqlite_foreign_keys. .. seealso:: diff --git a/doc/build/orm/self_referential.rst b/doc/build/orm/self_referential.rst index 70dfb4be9..9f13468e2 100644 --- a/doc/build/orm/self_referential.rst +++ b/doc/build/orm/self_referential.rst @@ -87,7 +87,7 @@ relationship using the :func:`.backref` function:: .. seealso:: - :ref:`examples_adjacencylist` - working example + ref_examples_adjacencylist - working example Composite Adjacency Lists ~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/build/orm/session_basics.rst b/doc/build/orm/session_basics.rst index 12413336a..b3cdb829e 100644 --- a/doc/build/orm/session_basics.rst +++ b/doc/build/orm/session_basics.rst @@ -533,11 +533,11 @@ ways to refresh its contents with new data from the current transaction: .. Further discussion on the refresh / expire concept can be found at -:ref:`session_expire`. +ref_session_expire. .. seealso:: - :ref:`session_expire` + ref_session_expire :ref:`faq_session_identity` @@ -924,7 +924,7 @@ The :class:`.Session` is not designed to be a global object from which everyone consults as a "registry" of objects. That's more the job of a **second level cache**. SQLAlchemy provides a pattern for implementing second level caching using `dogpile.cache <https://dogpilecache.readthedocs.io/>`_, -via the :ref:`examples_caching` example. +via the ref_examples_caching example. How can I get the :class:`~sqlalchemy.orm.session.Session` for a certain object? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -934,7 +934,7 @@ available on :class:`~sqlalchemy.orm.session.Session`:: session = Session.object_session(someobject) -The newer :ref:`core_inspection_toplevel` system can also be used:: +The newer ref_core_inspection_toplevel system can also be used:: from sqlalchemy import inspect @@ -952,7 +952,7 @@ time. The :class:`.Session` should be used in such a way that one instance exists for a single series of operations within a single transaction. One expedient way to get this effect is by associating -a :class:`.Session` with the current thread (see :ref:`unitofwork_contextual` +a :class:`.Session` with the current thread (see ref_unitofwork_contextual for background). Another is to use a pattern where the :class:`.Session` is passed between functions and is otherwise not shared with other threads. diff --git a/doc/build/orm/session_events.rst b/doc/build/orm/session_events.rst index f61421ea9..584a3402e 100644 --- a/doc/build/orm/session_events.rst +++ b/doc/build/orm/session_events.rst @@ -108,7 +108,7 @@ apply to subsequent relationship loads, which includes lazy loads, selectinloads, etc. For a series of classes that all feature some common column structure, -if the classes are composed using a :ref:`declarative mixin <declarative_mixins>`, +if the classes are composed using a ref_declarative_mixins, the mixin class itself may be used in conjunction with the :func:`_orm.with_loader_criteria` option by making use of a Python lambda. The Python lambda will be invoked at query compilation time against the specific entities which match the criteria. @@ -160,7 +160,7 @@ to intercept all objects that extend from ``HasTimestamp`` and filter their .. seealso:: - :ref:`examples_session_orm_events` - includes working examples of the + ref_examples_session_orm_events - includes working examples of the above :func:`_orm.with_loader_criteria` recipes. .. _do_orm_execute_re_executing: @@ -244,7 +244,7 @@ result from the "frozen" result, the :func:`_orm.loading.merge_frozen_result` function is used to merge the "frozen" data from the result object into the current session. -The above example is implemented as a complete example in :ref:`examples_caching`. +The above example is implemented as a complete example in ref_examples_caching. The :meth:`_orm.ORMExecuteState.invoke_statement` method may also be called multiple times, passing along different information to the @@ -253,14 +253,14 @@ that the :class:`_orm.Session` will make use of different :class:`_engine.Engine` objects each time. This will return a different :class:`_engine.Result` object each time; these results can be merged together using the :meth:`_engine.Result.merge` method. This is the technique employed -by the :ref:`horizontal_sharding_toplevel` extension; see the source code to +by the ref_horizontal_sharding_toplevel extension; see the source code to familiarize. .. seealso:: - :ref:`examples_caching` + ref_examples_caching - :ref:`examples_sharding` + ref_examples_sharding @@ -296,8 +296,8 @@ scanning the collections :attr:`.Session.new`, :attr:`.Session.dirty` and where something will be happening. For illustrations of :meth:`.SessionEvents.before_flush`, see -examples such as :ref:`examples_versioned_history` and -:ref:`examples_versioned_rows`. +examples such as ref_examples_versioned_history and +ref_examples_versioned_rows. ``after_flush()`` ^^^^^^^^^^^^^^^^^ @@ -408,7 +408,7 @@ Object Lifecycle Events ----------------------- Another use case for events is to track the lifecycle of objects. This -refers to the states first introduced at :ref:`session_object_states`. +refers to the states first introduced at ref_session_object_states. All the states above can be tracked fully with events. Each event represents a distinct state transition, meaning, the starting state @@ -684,7 +684,7 @@ however, it is often much more convenient to use a "validator" hook, which uses these hooks behind the scenes; see :ref:`simple_validators` for background on this. The attribute events are also behind the mechanics of backreferences. An example illustrating use of attribute events -is in :ref:`examples_instrumentation`. +is in ref_examples_instrumentation. diff --git a/doc/build/tutorial/data_select.rst b/doc/build/tutorial/data_select.rst index 03bc459a1..2cc4ee29d 100644 --- a/doc/build/tutorial/data_select.rst +++ b/doc/build/tutorial/data_select.rst @@ -1683,7 +1683,7 @@ Oracle, and SQL Server. .. seealso:: - :ref:`postgresql_table_valued_overview` - in the :ref:`postgresql_toplevel` documentation. + ref_postgresql_table_valued_overview - in the :ref:`postgresql_toplevel` documentation. While many databases support table valued and other special forms, PostgreSQL tends to be where there is the most demand for these @@ -1719,7 +1719,7 @@ towards as ``value``, and then selected two of its three rows. .. seealso:: - :ref:`postgresql_table_valued` - in the :ref:`postgresql_toplevel` documentation - + ref_postgresql_table_valued - in the :ref:`postgresql_toplevel` documentation - this section will detail additional syntaxes such as special column derivations and "WITH ORDINALITY" that are known to work with PostgreSQL. @@ -1757,7 +1757,7 @@ it is usable for custom SQL functions:: .. seealso:: - :ref:`postgresql_column_valued` - in the :ref:`postgresql_toplevel` documentation. + ref_postgresql_column_valued - in the :ref:`postgresql_toplevel` documentation. .. _tutorial_casts: diff --git a/doc/build/tutorial/data_update.rst b/doc/build/tutorial/data_update.rst index a82f070a3..64c8bdd3c 100644 --- a/doc/build/tutorial/data_update.rst +++ b/doc/build/tutorial/data_update.rst @@ -294,7 +294,7 @@ Facts about :attr:`_engine.CursorResult.rowcount`: * "rowcount" is used by the ORM :term:`unit of work` process to validate that an UPDATE or DELETE statement matched the expected number of rows, and is also essential for the ORM versioning feature documented at - :ref:`mapper_version_counter`. + ref_mapper_version_counter. Using RETURNING with UPDATE, DELETE ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/build/tutorial/metadata.rst b/doc/build/tutorial/metadata.rst index 8ee87480a..5044e30f8 100644 --- a/doc/build/tutorial/metadata.rst +++ b/doc/build/tutorial/metadata.rst @@ -474,14 +474,14 @@ about these classes include: To automatically generate a full-featured ``__init__()`` method which provides for positional arguments as well as arguments with default keyword values, the dataclasses feature introduced at - :ref:`orm_declarative_native_dataclasses` may be used. It's of course + ref_orm_declarative_native_dataclasses may be used. It's of course always an option to use an explicit ``__init__()`` method as well. * The ``__repr__()`` methods are added so that we get a readable string output; there's no requirement for these methods to be here. As is the case with ``__init__()``, a ``__repr__()`` method can be generated automatically by using the - :ref:`dataclasses <orm_declarative_native_dataclasses>` feature. + ref_orm_declarative_native_dataclasses feature. .. topic:: Where'd the old Declarative go? @@ -500,7 +500,7 @@ about these classes include: checkers such as Mypy and Pyright, without the need for plugins. Secondly, deriving the declarations from type annotations is part of SQLAlchemy's integration with Python dataclasses, which can now be - :ref:`generated natively <orm_declarative_native_dataclasses>` from mappings. + ref_orm_declarative_native_dataclasses from mappings. For users who like the "old" way, but still desire their IDEs to not mistakenly report typing errors for their declarative mappings, the @@ -641,7 +641,7 @@ we declared explicitly:: .. seealso:: - Read more about table and schema reflection at :ref:`metadata_reflection_toplevel`. + Read more about table and schema reflection at ref_metadata_reflection_toplevel. For ORM-related variants of table reflection, the section :ref:`orm_declarative_reflected` includes an overview of the available diff --git a/lib/sqlalchemy/dialects/mysql/aiomysql.py b/lib/sqlalchemy/dialects/mysql/aiomysql.py index bc079ba17..19e352245 100644 --- a/lib/sqlalchemy/dialects/mysql/aiomysql.py +++ b/lib/sqlalchemy/dialects/mysql/aiomysql.py @@ -17,13 +17,13 @@ r""" SQLAlchemy’s continuous integration. As of September, 2021 the driver appears to be unmaintained and no longer functions for Python version 3.10, and additionally depends on a significantly outdated version of PyMySQL. - Please refer to the :ref:`asyncmy` dialect for current MySQL/MariaDB asyncio + Please refer to the ref_asyncmy dialect for current MySQL/MariaDB asyncio functionality. The aiomysql dialect is SQLAlchemy's second Python asyncio dialect. Using a special asyncio mediation layer, the aiomysql dialect is usable -as the backend for the :ref:`SQLAlchemy asyncio <asyncio_toplevel>` +as the backend for the ref_asyncio_toplevel extension package. This dialect should normally be used only with the diff --git a/lib/sqlalchemy/dialects/mysql/asyncmy.py b/lib/sqlalchemy/dialects/mysql/asyncmy.py index d3f809e6a..ce245258b 100644 --- a/lib/sqlalchemy/dialects/mysql/asyncmy.py +++ b/lib/sqlalchemy/dialects/mysql/asyncmy.py @@ -14,11 +14,11 @@ r""" :url: https://github.com/long2ice/asyncmy .. note:: The asyncmy dialect as of September, 2021 was added to provide - MySQL/MariaDB asyncio compatibility given that the :ref:`aiomysql` database + MySQL/MariaDB asyncio compatibility given that the ref_aiomysql database driver has become unmaintained, however asyncmy is itself very new. Using a special asyncio mediation layer, the asyncmy dialect is usable -as the backend for the :ref:`SQLAlchemy asyncio <asyncio_toplevel>` +as the backend for the ref_asyncio_toplevel extension package. This dialect should normally be used only with the diff --git a/lib/sqlalchemy/dialects/mysql/base.py b/lib/sqlalchemy/dialects/mysql/base.py index eb9ccc606..cd10db18c 100644 --- a/lib/sqlalchemy/dialects/mysql/base.py +++ b/lib/sqlalchemy/dialects/mysql/base.py @@ -463,7 +463,7 @@ Some limited direct support for MySQL / MariaDB extensions to SQL is currently available. * INSERT..ON DUPLICATE KEY UPDATE: See - :ref:`mysql_insert_on_duplicate_key_update` + ref_mysql_insert_on_duplicate_key_update * SELECT pragma, use :meth:`_expression.Select.prefix_with` and :meth:`_query.Query.prefix_with`:: @@ -810,7 +810,7 @@ reflection will not include foreign keys. For these tables, you may supply a .. seealso:: - :ref:`mysql_storage_engines` + ref_mysql_storage_engines .. _mysql_unique_constraints: diff --git a/lib/sqlalchemy/dialects/mysql/dml.py b/lib/sqlalchemy/dialects/mysql/dml.py index 7c724c6f1..cfab91aee 100644 --- a/lib/sqlalchemy/dialects/mysql/dml.py +++ b/lib/sqlalchemy/dialects/mysql/dml.py @@ -80,7 +80,7 @@ class Insert(StandardInsert): .. seealso:: - :ref:`mysql_insert_on_duplicate_key_update` - example of how + ref_mysql_insert_on_duplicate_key_update - example of how to use :attr:`_expression.Insert.inserted` """ @@ -139,7 +139,7 @@ class Insert(StandardInsert): .. seealso:: - :ref:`mysql_insert_on_duplicate_key_update` + ref_mysql_insert_on_duplicate_key_update """ if args and kw: diff --git a/lib/sqlalchemy/dialects/postgresql/asyncpg.py b/lib/sqlalchemy/dialects/postgresql/asyncpg.py index c879205e4..80ec8f565 100644 --- a/lib/sqlalchemy/dialects/postgresql/asyncpg.py +++ b/lib/sqlalchemy/dialects/postgresql/asyncpg.py @@ -16,7 +16,7 @@ r""" The asyncpg dialect is SQLAlchemy's first Python asyncio dialect. Using a special asyncio mediation layer, the asyncpg dialect is usable -as the backend for the :ref:`SQLAlchemy asyncio <asyncio_toplevel>` +as the backend for the ref_asyncio_toplevel extension package. This dialect should normally be used only with the diff --git a/lib/sqlalchemy/dialects/postgresql/base.py b/lib/sqlalchemy/dialects/postgresql/base.py index ad5e346b7..c334d1285 100644 --- a/lib/sqlalchemy/dialects/postgresql/base.py +++ b/lib/sqlalchemy/dialects/postgresql/base.py @@ -198,7 +198,7 @@ Valid values for ``isolation_level`` on most PostgreSQL dialects include: :ref:`dbapi_autocommit` - :ref:`postgresql_readonly_deferrable` + ref_postgresql_readonly_deferrable :ref:`psycopg2_isolation_level` @@ -353,7 +353,7 @@ Remote-Schema Table Introspection and PostgreSQL search_path attribute set up. The PostgreSQL dialect can reflect tables from any schema, as outlined in -:ref:`metadata_reflection_schemas`. +ref_metadata_reflection_schemas. With regards to tables which these :class:`_schema.Table` objects refer to via foreign key constraint, a decision must be made as to how @@ -1067,7 +1067,7 @@ construct, the DBAPI's "autocommit" mode must be used:: .. seealso:: - :ref:`postgresql_isolation_level` + ref_postgresql_isolation_level .. _postgresql_index_reflection: diff --git a/lib/sqlalchemy/dialects/postgresql/dml.py b/lib/sqlalchemy/dialects/postgresql/dml.py index e17b87d1e..190645ec4 100644 --- a/lib/sqlalchemy/dialects/postgresql/dml.py +++ b/lib/sqlalchemy/dialects/postgresql/dml.py @@ -77,7 +77,7 @@ class Insert(StandardInsert): .. seealso:: - :ref:`postgresql_insert_on_conflict` - example of how + ref_postgresql_insert_on_conflict - example of how to use :attr:`_expression.Insert.excluded` """ @@ -149,7 +149,7 @@ class Insert(StandardInsert): .. seealso:: - :ref:`postgresql_insert_on_conflict` + ref_postgresql_insert_on_conflict """ self._post_values_clause = OnConflictDoUpdate( @@ -186,7 +186,7 @@ class Insert(StandardInsert): .. seealso:: - :ref:`postgresql_insert_on_conflict` + ref_postgresql_insert_on_conflict """ self._post_values_clause = OnConflictDoNothing( diff --git a/lib/sqlalchemy/dialects/postgresql/ext.py b/lib/sqlalchemy/dialects/postgresql/ext.py index c79e90034..be2b066cd 100644 --- a/lib/sqlalchemy/dialects/postgresql/ext.py +++ b/lib/sqlalchemy/dialects/postgresql/ext.py @@ -198,14 +198,14 @@ class ExcludeConstraint(ColumnCollectionConstraint): :param ops: Optional dictionary. Used to define operator classes for the elements; works the same way as that of the - :ref:`postgresql_ops <postgresql_operator_classes>` + ref_postgresql_operator_classes parameter specified to the :class:`_schema.Index` construct. .. versionadded:: 1.3.21 .. seealso:: - :ref:`postgresql_operator_classes` - general description of how + ref_postgresql_operator_classes - general description of how PostgreSQL operator classes are specified. """ diff --git a/lib/sqlalchemy/dialects/postgresql/pg8000.py b/lib/sqlalchemy/dialects/postgresql/pg8000.py index 3f01b00e8..7eafad3e4 100644 --- a/lib/sqlalchemy/dialects/postgresql/pg8000.py +++ b/lib/sqlalchemy/dialects/postgresql/pg8000.py @@ -85,7 +85,7 @@ of the :ref:`psycopg2 <psycopg2_isolation_level>` dialect: .. seealso:: - :ref:`postgresql_isolation_level` + ref_postgresql_isolation_level :ref:`psycopg2_isolation_level` diff --git a/lib/sqlalchemy/dialects/postgresql/psycopg2.py b/lib/sqlalchemy/dialects/postgresql/psycopg2.py index e28bd8fda..3e758f989 100644 --- a/lib/sqlalchemy/dialects/postgresql/psycopg2.py +++ b/lib/sqlalchemy/dialects/postgresql/psycopg2.py @@ -52,7 +52,7 @@ may be passed to :func:`_sa.create_engine()`, and include the following: .. seealso:: - :ref:`psycopg2_executemany_mode` + ref_psycopg2_executemany_mode .. tip:: @@ -376,7 +376,7 @@ The psycopg2 dialect fully supports SAVEPOINT and two-phase commit operations. Psycopg2 Transaction Isolation Level ------------------------------------- -As discussed in :ref:`postgresql_isolation_level`, +As discussed in ref_postgresql_isolation_level, all PostgreSQL dialects support setting of transaction isolation level both via the ``isolation_level`` parameter passed to :func:`_sa.create_engine` , @@ -398,7 +398,7 @@ The psycopg2 dialect supports these constants for isolation level: .. seealso:: - :ref:`postgresql_isolation_level` + ref_postgresql_isolation_level :ref:`pg8000_isolation_level` diff --git a/lib/sqlalchemy/dialects/postgresql/types.py b/lib/sqlalchemy/dialects/postgresql/types.py index edab23935..fbe54a829 100644 --- a/lib/sqlalchemy/dialects/postgresql/types.py +++ b/lib/sqlalchemy/dialects/postgresql/types.py @@ -244,7 +244,7 @@ class TSVECTOR(sqltypes.TypeEngine[str]): .. seealso:: - :ref:`postgresql_match` + ref_postgresql_match """ diff --git a/lib/sqlalchemy/dialects/sqlite/aiosqlite.py b/lib/sqlalchemy/dialects/sqlite/aiosqlite.py index f9c60efc1..a0ca5135d 100644 --- a/lib/sqlalchemy/dialects/sqlite/aiosqlite.py +++ b/lib/sqlalchemy/dialects/sqlite/aiosqlite.py @@ -24,7 +24,7 @@ databases are not socket-based. However it does provide a working asyncio interface that's useful for testing and prototyping purposes. Using a special asyncio mediation layer, the aiosqlite dialect is usable -as the backend for the :ref:`SQLAlchemy asyncio <asyncio_toplevel>` +as the backend for the ref_asyncio_toplevel extension package. This dialect should normally be used only with the diff --git a/lib/sqlalchemy/dialects/sqlite/base.py b/lib/sqlalchemy/dialects/sqlite/base.py index 6200cee5a..53ac3ca86 100644 --- a/lib/sqlalchemy/dialects/sqlite/base.py +++ b/lib/sqlalchemy/dialects/sqlite/base.py @@ -214,7 +214,7 @@ by *not even emitting BEGIN* until the first write operation. SQLite's transactional scope is impacted by unresolved issues in the pysqlite driver, which defers BEGIN statements to a greater - degree than is often feasible. See the section :ref:`pysqlite_serializable` + degree than is often feasible. See the section ref_pysqlite_serializable for techniques to work around this behavior. .. seealso:: @@ -274,7 +274,7 @@ won't work at all with pysqlite unless workarounds are taken. SQLite's SAVEPOINT feature is impacted by unresolved issues in the pysqlite driver, which defers BEGIN statements to a greater - degree than is often feasible. See the section :ref:`pysqlite_serializable` + degree than is often feasible. See the section ref_pysqlite_serializable for techniques to work around this behavior. Transactional DDL @@ -290,7 +290,7 @@ workarounds are required. SQLite's transactional DDL is impacted by unresolved issues in the pysqlite driver, which fails to emit BEGIN and additionally forces a COMMIT to cancel any transaction when DDL is encountered. - See the section :ref:`pysqlite_serializable` + See the section ref_pysqlite_serializable for techniques to work around this behavior. .. _sqlite_foreign_keys: @@ -349,7 +349,7 @@ ON CONFLICT support for constraints .. seealso:: This section describes the :term:`DDL` version of "ON CONFLICT" for SQLite, which occurs within a CREATE TABLE statement. For "ON CONFLICT" as - applied to an INSERT statement, see :ref:`sqlite_on_conflict_insert`. + applied to an INSERT statement, see ref_sqlite_on_conflict_insert. SQLite supports a non-standard DDL clause known as ON CONFLICT which can be applied to primary key, unique, check, and not null constraints. In DDL, it is @@ -459,7 +459,7 @@ INSERT...ON CONFLICT (Upsert) .. seealso:: This section describes the :term:`DML` version of "ON CONFLICT" for SQLite, which occurs within an INSERT statement. For "ON CONFLICT" as - applied to a CREATE TABLE statement, see :ref:`sqlite_on_conflict_ddl`. + applied to a CREATE TABLE statement, see ref_sqlite_on_conflict_ddl. From version 3.24.0 onwards, SQLite supports "upserts" (update or insert) of rows into a table via the ``ON CONFLICT`` clause of the ``INSERT`` diff --git a/lib/sqlalchemy/dialects/sqlite/dml.py b/lib/sqlalchemy/dialects/sqlite/dml.py index 3f829076b..296a1d40c 100644 --- a/lib/sqlalchemy/dialects/sqlite/dml.py +++ b/lib/sqlalchemy/dialects/sqlite/dml.py @@ -53,7 +53,7 @@ class Insert(StandardInsert): .. seealso:: - :ref:`sqlite_on_conflict_insert` + ref_sqlite_on_conflict_insert """ diff --git a/lib/sqlalchemy/dialects/sqlite/pysqlcipher.py b/lib/sqlalchemy/dialects/sqlite/pysqlcipher.py index 28b900ea5..1eeafd445 100644 --- a/lib/sqlalchemy/dialects/sqlite/pysqlcipher.py +++ b/lib/sqlalchemy/dialects/sqlite/pysqlcipher.py @@ -80,7 +80,7 @@ Pooling Behavior ---------------- The driver makes a change to the default pool behavior of pysqlite -as described in :ref:`pysqlite_threading_pooling`. The pysqlcipher driver +as described in ref_pysqlite_threading_pooling. The pysqlcipher driver has been observed to be significantly slower on connection than the pysqlite driver, most likely due to the encryption overhead, so the dialect here defaults to using the :class:`.SingletonThreadPool` diff --git a/lib/sqlalchemy/engine/cursor.py b/lib/sqlalchemy/engine/cursor.py index aaf2c1918..b9cce9edf 100644 --- a/lib/sqlalchemy/engine/cursor.py +++ b/lib/sqlalchemy/engine/cursor.py @@ -1576,11 +1576,11 @@ class CursorResult(Result[_T]): .. note:: As indicated below, in current SQLAlchemy versions this accessor is only useful beyond what's already supplied by :attr:`_engine.CursorResult.inserted_primary_key` when using the - :ref:`postgresql_psycopg2` dialect. Future versions hope to + psycopg2 dialect. Future versions hope to generalize this feature to more dialects. This accessor is added to support dialects that offer the feature - that is currently implemented by the :ref:`psycopg2_executemany_mode` + that is currently implemented by the ref_psycopg2_executemany_mode feature, currently **only the psycopg2 dialect**, which provides for many rows to be INSERTed at once while still retaining the behavior of being able to return server-generated primary key values. diff --git a/lib/sqlalchemy/engine/default.py b/lib/sqlalchemy/engine/default.py index 8992334ee..635173392 100644 --- a/lib/sqlalchemy/engine/default.py +++ b/lib/sqlalchemy/engine/default.py @@ -2150,7 +2150,7 @@ class DefaultExecutionContext(ExecutionContext): """A dictionary of parameters applied to the current row. This attribute is only available in the context of a user-defined default - generation function, e.g. as described at :ref:`context_default_functions`. + generation function, e.g. as described at ref_context_default_functions. It consists of a dictionary which includes entries for each column/value pair that is to be part of the INSERT or UPDATE statement. The keys of the dictionary will be the key value of each :class:`_schema.Column`, @@ -2167,7 +2167,7 @@ class DefaultExecutionContext(ExecutionContext): :meth:`.DefaultExecutionContext.get_current_parameters` - :ref:`context_default_functions` + ref_context_default_functions """ @@ -2176,7 +2176,7 @@ class DefaultExecutionContext(ExecutionContext): This method can only be used in the context of a user-defined default generation function, e.g. as described at - :ref:`context_default_functions`. When invoked, a dictionary is + ref_context_default_functions. When invoked, a dictionary is returned which includes entries for each column/value pair that is part of the INSERT or UPDATE statement. The keys of the dictionary will be the key value of each :class:`_schema.Column`, @@ -2201,7 +2201,7 @@ class DefaultExecutionContext(ExecutionContext): :attr:`.DefaultExecutionContext.current_parameters` - :ref:`context_default_functions` + ref_context_default_functions """ try: diff --git a/lib/sqlalchemy/engine/events.py b/lib/sqlalchemy/engine/events.py index c1b182a0a..1ce2cfbd0 100644 --- a/lib/sqlalchemy/engine/events.py +++ b/lib/sqlalchemy/engine/events.py @@ -940,13 +940,13 @@ class DialectEvents(event.Events[Dialect]): .. seealso:: - :ref:`mssql_pyodbc_setinputsizes` + ref_mssql_pyodbc_setinputsizes .. versionadded:: 1.2.9 .. seealso:: - :ref:`cx_oracle_setinputsizes` + ref_cx_oracle_setinputsizes """ pass diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py index 0216c155d..74ba176d1 100644 --- a/lib/sqlalchemy/engine/interfaces.py +++ b/lib/sqlalchemy/engine/interfaces.py @@ -3388,7 +3388,7 @@ class AdaptedConnection: .. seealso:: - :ref:`asyncio_events_run_async` + ref_asyncio_events_run_async """ return await_only(fn(self._connection)) diff --git a/lib/sqlalchemy/event/api.py b/lib/sqlalchemy/event/api.py index bb1dbea0f..6822cd7e2 100644 --- a/lib/sqlalchemy/event/api.py +++ b/lib/sqlalchemy/event/api.py @@ -68,7 +68,7 @@ def listen( internal list upon discovery. This feature is not typically used or recommended by the SQLAlchemy maintainers, but is provided to ensure certain user defined functions can run before others, such as when - :ref:`Changing the sql_mode in MySQL <mysql_sql_mode>`. + ref_mysql_sql_mode. :param bool named: When using named argument passing, the names listed in the function argument specification will be used as keys in the diff --git a/lib/sqlalchemy/ext/associationproxy.py b/lib/sqlalchemy/ext/associationproxy.py index 243c140f8..863611448 100644 --- a/lib/sqlalchemy/ext/associationproxy.py +++ b/lib/sqlalchemy/ext/associationproxy.py @@ -156,13 +156,13 @@ def association_proxy( :ref:`cascade_scalar_deletes` - complete usage example - :param init: Specific to :ref:`orm_declarative_native_dataclasses`, + :param init: Specific to ref_orm_declarative_native_dataclasses, specifies if the mapped attribute should be part of the ``__init__()`` method as generated by the dataclass process. .. versionadded:: 2.0.0b4 - :param repr: Specific to :ref:`orm_declarative_native_dataclasses`, + :param repr: Specific to ref_orm_declarative_native_dataclasses, specifies if the attribute established by this :class:`.AssociationProxy` should be part of the ``__repr__()`` method as generated by the dataclass process. @@ -170,20 +170,20 @@ def association_proxy( .. versionadded:: 2.0.0b4 :param default_factory: Specific to - :ref:`orm_declarative_native_dataclasses`, specifies a default-value + ref_orm_declarative_native_dataclasses, specifies a default-value generation function that will take place as part of the ``__init__()`` method as generated by the dataclass process. .. versionadded:: 2.0.0b4 :param compare: Specific to - :ref:`orm_declarative_native_dataclasses`, indicates if this field + ref_orm_declarative_native_dataclasses, indicates if this field should be included in comparison operations when generating the ``__eq__()`` and ``__ne__()`` methods for the mapped class. .. versionadded:: 2.0.0b4 - :param kw_only: Specific to :ref:`orm_declarative_native_dataclasses`, + :param kw_only: Specific to ref_orm_declarative_native_dataclasses, indicates if this field should be marked as keyword-only when generating the ``__init__()`` method as generated by the dataclass process. diff --git a/lib/sqlalchemy/ext/asyncio/engine.py b/lib/sqlalchemy/ext/asyncio/engine.py index 6dfca463f..201009510 100644 --- a/lib/sqlalchemy/ext/asyncio/engine.py +++ b/lib/sqlalchemy/ext/asyncio/engine.py @@ -69,7 +69,7 @@ def create_async_engine(url: Union[str, URL], **kw: Any) -> AsyncEngine: Arguments passed to :func:`_asyncio.create_async_engine` are mostly identical to those passed to the :func:`_sa.create_engine` function. The specified dialect must be an asyncio-compatible dialect - such as :ref:`dialect-postgresql-asyncpg`. + such as ref_dialect-postgresql-asyncpg. .. versionadded:: 1.4 @@ -93,7 +93,7 @@ def async_engine_from_config( This function is analogous to the :func:`_sa.engine_from_config` function in SQLAlchemy Core, except that the requested dialect must be an - asyncio-compatible dialect such as :ref:`dialect-postgresql-asyncpg`. + asyncio-compatible dialect such as ref_dialect-postgresql-asyncpg. The argument signature of the function is identical to that of :func:`_sa.engine_from_config`. @@ -117,7 +117,7 @@ def create_async_pool_from_url(url: Union[str, URL], **kwargs: Any) -> Pool: Arguments passed to :func:`_asyncio.create_async_pool_from_url` are mostly identical to those passed to the :func:`_sa.create_pool_from_url` function. The specified dialect must be an asyncio-compatible dialect - such as :ref:`dialect-postgresql-asyncpg`. + such as ref_dialect-postgresql-asyncpg. .. versionadded:: 2.0.10 diff --git a/lib/sqlalchemy/ext/asyncio/scoping.py b/lib/sqlalchemy/ext/asyncio/scoping.py index 52eeb0828..f7c50d926 100644 --- a/lib/sqlalchemy/ext/asyncio/scoping.py +++ b/lib/sqlalchemy/ext/asyncio/scoping.py @@ -109,7 +109,7 @@ _T = TypeVar("_T", bound=Any) class async_scoped_session(Generic[_AS]): """Provides scoped management of :class:`.AsyncSession` objects. - See the section :ref:`asyncio_scoped_session` for usage details. + See the section ref_asyncio_scoped_session for usage details. .. versionadded:: 1.4.19 @@ -610,7 +610,7 @@ class async_scoped_session(Generic[_AS]): .. seealso:: - :ref:`session_expire` - introductory material + ref_session_expire - introductory material :meth:`.Session.expire` @@ -657,7 +657,7 @@ class async_scoped_session(Generic[_AS]): .. seealso:: - :ref:`session_expire` - introductory material + ref_session_expire - introductory material :meth:`.Session.expire` diff --git a/lib/sqlalchemy/ext/asyncio/session.py b/lib/sqlalchemy/ext/asyncio/session.py index dabe1824e..f8f071c5a 100644 --- a/lib/sqlalchemy/ext/asyncio/session.py +++ b/lib/sqlalchemy/ext/asyncio/session.py @@ -987,7 +987,7 @@ class AsyncSession(ReversibleProxy[Session]): .. seealso:: - :ref:`session_expire` - introductory material + ref_session_expire - introductory material :meth:`.Session.expire` @@ -1028,7 +1028,7 @@ class AsyncSession(ReversibleProxy[Session]): .. seealso:: - :ref:`session_expire` - introductory material + ref_session_expire - introductory material :meth:`.Session.expire` diff --git a/lib/sqlalchemy/ext/automap.py b/lib/sqlalchemy/ext/automap.py index f378f729a..8ca14a3fb 100644 --- a/lib/sqlalchemy/ext/automap.py +++ b/lib/sqlalchemy/ext/automap.py @@ -19,7 +19,7 @@ Declarative class techniques, :class:`.AutomapBase` seeks to provide a well-integrated approach to the issue of expediently auto-generating ad-hoc mappings. -.. tip:: The :ref:`automap_toplevel` extension is geared towards a +.. tip:: The ref_automap_toplevel extension is geared towards a "zero declaration" approach, where a complete ORM model including classes and pre-named relationships can be generated on the fly from a database schema. For applications that still want to use explicit class declarations @@ -991,7 +991,7 @@ class AutomapBase: .. seealso:: - :ref:`automap_toplevel` + ref_automap_toplevel """ @@ -1034,7 +1034,7 @@ class AutomapBase: .. seealso:: - :ref:`automap_by_module` + ref_automap_by_module """ @@ -1133,7 +1133,7 @@ class AutomapBase: .. seealso:: - :ref:`automap_by_module` + ref_automap_by_module :param name_for_scalar_relationship: callable function which will be used to produce relationship names for scalar relationships. Defaults @@ -1165,7 +1165,7 @@ class AutomapBase: For an overview of multiple-schema automap including the use of additional naming conventions to resolve table name - conflicts, see the section :ref:`automap_by_module`. + conflicts, see the section ref_automap_by_module. .. versionadded:: 2.0 :meth:`.AutomapBase.prepare` supports being directly invoked any number of times, keeping track of tables diff --git a/lib/sqlalchemy/ext/declarative/extensions.py b/lib/sqlalchemy/ext/declarative/extensions.py index 2cb55a5ae..b33c8e18d 100644 --- a/lib/sqlalchemy/ext/declarative/extensions.py +++ b/lib/sqlalchemy/ext/declarative/extensions.py @@ -190,7 +190,7 @@ class AbstractConcreteBase(ConcreteBase): Using this approach, we can specify columns and properties that will take place on mapped subclasses, in the way that - we normally do as in :ref:`declarative_mixins`:: + we normally do as in ref_declarative_mixins:: from sqlalchemy.ext.declarative import AbstractConcreteBase diff --git a/lib/sqlalchemy/ext/horizontal_shard.py b/lib/sqlalchemy/ext/horizontal_shard.py index e1741fe52..ac800917c 100644 --- a/lib/sqlalchemy/ext/horizontal_shard.py +++ b/lib/sqlalchemy/ext/horizontal_shard.py @@ -10,7 +10,7 @@ Defines a rudimental 'horizontal sharding' system which allows a Session to distribute queries and persistence operations across multiple databases. -For a usage example, see the :ref:`examples_sharding` example included in +For a usage example, see the ref_examples_sharding example included in the source distribution. .. deepalchemy:: The horizontal sharding extension is an advanced feature, diff --git a/lib/sqlalchemy/ext/hybrid.py b/lib/sqlalchemy/ext/hybrid.py index 4e0fd4604..5b058a4d8 100644 --- a/lib/sqlalchemy/ext/hybrid.py +++ b/lib/sqlalchemy/ext/hybrid.py @@ -171,7 +171,7 @@ The use of :attr:`.hybrid_property.inplace` indicates that the :meth:`.hybrid_property.expression` modifier should mutate the existing hybrid object at ``Interval.radius`` in place, without creating a new object. Notes on this modifier and its -rationale are discussed in the next section :ref:`hybrid_pep484_naming`. +rationale are discussed in the next section ref_hybrid_pep484_naming. The use of ``@classmethod`` is optional, and is strictly to give typing tools a hint that ``cls`` in this case is expected to be the ``Interval`` class, and not an instance of ``Interval``. @@ -501,7 +501,7 @@ We can, of course, forego being dependent on the enclosing query's usage of joins in favor of the correlated subquery, which can portably be packed into a single column expression. A correlated subquery is more portable, but often performs more poorly at the SQL level. Using the same technique -illustrated at :ref:`mapper_column_property_sql_expressions`, +illustrated at ref_mapper_column_property_sql_expressions, we can adjust our ``SavingsAccount`` example to aggregate the balances for *all* accounts, and use a correlated subquery for the column expression:: @@ -1018,7 +1018,7 @@ class hybrid_method(interfaces.InspectionAttrInfo, Generic[_P, _R]): .. seealso:: - :ref:`hybrid_pep484_naming` + ref_hybrid_pep484_naming """ return self @@ -1255,7 +1255,7 @@ class hybrid_property(interfaces.InspectionAttrInfo, ORMDescriptor[_T]): .. seealso:: - :ref:`hybrid_pep484_naming` + ref_hybrid_pep484_naming """ return hybrid_property._InPlace(self) diff --git a/lib/sqlalchemy/ext/instrumentation.py b/lib/sqlalchemy/ext/instrumentation.py index 688c762e7..22e60b343 100644 --- a/lib/sqlalchemy/ext/instrumentation.py +++ b/lib/sqlalchemy/ext/instrumentation.py @@ -20,7 +20,7 @@ on the class. their own instrumentation. It is not intended for general use. For examples of how the instrumentation extension is used, -see the example :ref:`examples_instrumentation`. +see the example ref_examples_instrumentation. """ import weakref diff --git a/lib/sqlalchemy/ext/mutable.py b/lib/sqlalchemy/ext/mutable.py index 7d23f9fda..b8159714e 100644 --- a/lib/sqlalchemy/ext/mutable.py +++ b/lib/sqlalchemy/ext/mutable.py @@ -233,14 +233,14 @@ Establishing Mutability on Composites Composites are a special ORM feature which allow a single scalar attribute to be assigned an object value which represents information "composed" from one or more columns from the underlying mapped table. The usual example is that of -a geometric "point", and is introduced in :ref:`mapper_composite`. +a geometric "point", and is introduced in ref_mapper_composite. As is the case with :class:`.Mutable`, the user-defined composite class subclasses :class:`.MutableComposite` as a mixin, and detects and delivers change events to its parents via the :meth:`.MutableComposite.changed` method. In the case of a composite class, the detection is usually via the usage of the special Python method ``__setattr__()``. In the example below, we expand upon the ``Point`` -class introduced in :ref:`mapper_composite` to include +class introduced in ref_mapper_composite to include :class:`.MutableComposite` in its bases and to route attribute set events via ``__setattr__`` to the :meth:`.MutableComposite.changed` method:: diff --git a/lib/sqlalchemy/orm/_orm_constructors.py b/lib/sqlalchemy/orm/_orm_constructors.py index 563fef3c5..207c4410d 100644 --- a/lib/sqlalchemy/orm/_orm_constructors.py +++ b/lib/sqlalchemy/orm/_orm_constructors.py @@ -228,7 +228,7 @@ def mapped_column( :param default: Passed directly to the :paramref:`_schema.Column.default` parameter if the :paramref:`_orm.mapped_column.insert_default` parameter is not present. - Additionally, when used with :ref:`orm_declarative_native_dataclasses`, + Additionally, when used with ref_orm_declarative_native_dataclasses, indicates a default Python value that should be applied to the keyword constructor within the generated ``__init__()`` method. @@ -274,26 +274,26 @@ def mapped_column( .. versionadded:: 2.0.10 - :param init: Specific to :ref:`orm_declarative_native_dataclasses`, + :param init: Specific to ref_orm_declarative_native_dataclasses, specifies if the mapped attribute should be part of the ``__init__()`` method as generated by the dataclass process. - :param repr: Specific to :ref:`orm_declarative_native_dataclasses`, + :param repr: Specific to ref_orm_declarative_native_dataclasses, specifies if the mapped attribute should be part of the ``__repr__()`` method as generated by the dataclass process. :param default_factory: Specific to - :ref:`orm_declarative_native_dataclasses`, + ref_orm_declarative_native_dataclasses, specifies a default-value generation function that will take place as part of the ``__init__()`` method as generated by the dataclass process. :param compare: Specific to - :ref:`orm_declarative_native_dataclasses`, indicates if this field + ref_orm_declarative_native_dataclasses, indicates if this field should be included in comparison operations when generating the ``__eq__()`` and ``__ne__()`` methods for the mapped class. .. versionadded:: 2.0.0b4 :param kw_only: Specific to - :ref:`orm_declarative_native_dataclasses`, indicates if this field + ref_orm_declarative_native_dataclasses, indicates if this field should be marked as keyword-only when generating the ``__init__()``. :param \**kw: All remaining keyword arguments are passed through to the @@ -435,7 +435,7 @@ def column_property( .. seealso:: - :ref:`mapper_column_property_sql_expressions` - general use of + ref_mapper_column_property_sql_expressions - general use of :func:`_orm.column_property` to map SQL expressions :ref:`orm_imperative_table_column_options` - usage of @@ -619,7 +619,7 @@ def composite( ) -> Composite[Any]: r"""Return a composite column-based property for use with a Mapper. - See the mapping documentation section :ref:`mapper_composite` for a + See the mapping documentation section ref_mapper_composite for a full usage example. The :class:`.MapperProperty` returned by :func:`.composite` @@ -664,27 +664,27 @@ def composite( :param info: Optional data dictionary which will be populated into the :attr:`.MapperProperty.info` attribute of this object. - :param init: Specific to :ref:`orm_declarative_native_dataclasses`, + :param init: Specific to ref_orm_declarative_native_dataclasses, specifies if the mapped attribute should be part of the ``__init__()`` method as generated by the dataclass process. - :param repr: Specific to :ref:`orm_declarative_native_dataclasses`, + :param repr: Specific to ref_orm_declarative_native_dataclasses, specifies if the mapped attribute should be part of the ``__repr__()`` method as generated by the dataclass process. :param default_factory: Specific to - :ref:`orm_declarative_native_dataclasses`, + ref_orm_declarative_native_dataclasses, specifies a default-value generation function that will take place as part of the ``__init__()`` method as generated by the dataclass process. :param compare: Specific to - :ref:`orm_declarative_native_dataclasses`, indicates if this field + ref_orm_declarative_native_dataclasses, indicates if this field should be included in comparison operations when generating the ``__eq__()`` and ``__ne__()`` methods for the mapped class. .. versionadded:: 2.0.0b4 :param kw_only: Specific to - :ref:`orm_declarative_native_dataclasses`, indicates if this field + ref_orm_declarative_native_dataclasses, indicates if this field should be marked as keyword-only when generating the ``__init__()``. """ @@ -871,7 +871,7 @@ def with_loader_criteria( .. seealso:: - :ref:`examples_session_orm_events` - includes examples of using + ref_examples_session_orm_events - includes examples of using :func:`_orm.with_loader_criteria`. :ref:`do_orm_execute_global_criteria` - basic example on how to @@ -1009,7 +1009,7 @@ def relationship( .. warning:: When passed as a Python-evaluable string, the argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. - See :ref:`declarative_relationship_eval` for details on + See ref_declarative_relationship_eval for details on declarative evaluation of :func:`_orm.relationship` arguments. The :paramref:`_orm.relationship.secondary` keyword argument is @@ -1031,7 +1031,7 @@ def relationship( :ref:`self_referential_many_to_many` - Specifics on using many-to-many in a self-referential case. - :ref:`declarative_many_to_many` - Additional options when using + ref_declarative_many_to_many - Additional options when using Declarative. :ref:`association_pattern` - an alternative to @@ -1070,7 +1070,7 @@ def relationship( .. seealso:: - :ref:`relationships_backref` - notes on using + ref_relationships_backref - notes on using :paramref:`_orm.relationship.backref` :ref:`tutorial_orm_related_objects` - in the :ref:`unified_tutorial`, @@ -1246,7 +1246,7 @@ def relationship( .. warning:: When passed as a Python-evaluable string, the argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. - See :ref:`declarative_relationship_eval` for details on + See ref_declarative_relationship_eval for details on declarative evaluation of :func:`_orm.relationship` arguments. .. seealso:: @@ -1331,7 +1331,7 @@ def relationship( * ``noload`` - no loading should occur at any time. The related collection will remain empty. The ``noload`` strategy is not recommended for general use. For a general use "never load" - approach, see :ref:`write_only_relationship` + approach, see ref_write_only_relationship * ``raise`` - lazy loading is disallowed; accessing the attribute, if its value were not already loaded via eager @@ -1366,13 +1366,13 @@ def relationship( The ``write_only`` loader style is configured automatically when the :class:`_orm.WriteOnlyMapped` annotation is provided on the left hand side within a Declarative mapping. See the section - :ref:`write_only_relationship` for examples. + ref_write_only_relationship for examples. .. versionadded:: 2.0 .. seealso:: - :ref:`write_only_relationship` - in the :ref:`queryguide_toplevel` + ref_write_only_relationship - in the :ref:`queryguide_toplevel` * ``dynamic`` - the attribute will return a pre-configured :class:`_query.Query` object for all read @@ -1382,17 +1382,17 @@ def relationship( The ``dynamic`` loader style is configured automatically when the :class:`_orm.DynamicMapped` annotation is provided on the left hand side within a Declarative mapping. See the section - :ref:`dynamic_relationship` for examples. + ref_dynamic_relationship for examples. .. legacy:: The "dynamic" lazy loader strategy is the legacy form of what is now the "write_only" strategy described in the section - :ref:`write_only_relationship`. + ref_write_only_relationship. .. seealso:: - :ref:`dynamic_relationship` - in the :ref:`queryguide_toplevel` + ref_dynamic_relationship - in the :ref:`queryguide_toplevel` - :ref:`write_only_relationship` - more generally useful approach + ref_write_only_relationship - more generally useful approach for large collections that should not fully load into memory * True - a synonym for 'select' @@ -1448,7 +1448,7 @@ def relationship( .. warning:: When passed as a Python-evaluable string, the argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. - See :ref:`declarative_relationship_eval` for details on + See ref_declarative_relationship_eval for details on declarative evaluation of :func:`_orm.relationship` arguments. :param passive_deletes=False: @@ -1545,7 +1545,7 @@ def relationship( .. warning:: When passed as a Python-evaluable string, the argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. - See :ref:`declarative_relationship_eval` for details on + See ref_declarative_relationship_eval for details on declarative evaluation of :func:`_orm.relationship` arguments. .. seealso:: @@ -1564,7 +1564,7 @@ def relationship( .. warning:: When passed as a Python-evaluable string, the argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. - See :ref:`declarative_relationship_eval` for details on + See ref_declarative_relationship_eval for details on declarative evaluation of :func:`_orm.relationship` arguments. .. seealso:: @@ -1589,7 +1589,7 @@ def relationship( .. seealso:: - :ref:`dynamic_relationship` - Introduction to "dynamic" + ref_dynamic_relationship - Introduction to "dynamic" relationship loaders. :param secondaryjoin: @@ -1606,7 +1606,7 @@ def relationship( .. warning:: When passed as a Python-evaluable string, the argument is interpreted using Python's ``eval()`` function. **DO NOT PASS UNTRUSTED INPUT TO THIS STRING**. - See :ref:`declarative_relationship_eval` for details on + See ref_declarative_relationship_eval for details on declarative evaluation of :func:`_orm.relationship` arguments. .. seealso:: @@ -1730,26 +1730,26 @@ def relationship( .. versionadded:: 1.3 - :param init: Specific to :ref:`orm_declarative_native_dataclasses`, + :param init: Specific to ref_orm_declarative_native_dataclasses, specifies if the mapped attribute should be part of the ``__init__()`` method as generated by the dataclass process. - :param repr: Specific to :ref:`orm_declarative_native_dataclasses`, + :param repr: Specific to ref_orm_declarative_native_dataclasses, specifies if the mapped attribute should be part of the ``__repr__()`` method as generated by the dataclass process. :param default_factory: Specific to - :ref:`orm_declarative_native_dataclasses`, + ref_orm_declarative_native_dataclasses, specifies a default-value generation function that will take place as part of the ``__init__()`` method as generated by the dataclass process. :param compare: Specific to - :ref:`orm_declarative_native_dataclasses`, indicates if this field + ref_orm_declarative_native_dataclasses, indicates if this field should be included in comparison operations when generating the ``__eq__()`` and ``__ne__()`` methods for the mapped class. .. versionadded:: 2.0.0b4 :param kw_only: Specific to - :ref:`orm_declarative_native_dataclasses`, indicates if this field + ref_orm_declarative_native_dataclasses, indicates if this field should be marked as keyword-only when generating the ``__init__()``. @@ -2001,7 +2001,7 @@ def dynamic_loader( relationship(SomeClass, lazy="dynamic") - See the section :ref:`dynamic_relationship` for more details + See the section ref_dynamic_relationship for more details on dynamic loading. """ @@ -2027,7 +2027,7 @@ def backref(name: str, **kwargs: Any) -> ORMBackrefArgument: .. seealso:: - :ref:`relationships_backref` - background on backrefs + ref_relationships_backref - background on backrefs """ diff --git a/lib/sqlalchemy/orm/base.py b/lib/sqlalchemy/orm/base.py index 5d19cf20a..3e178d524 100644 --- a/lib/sqlalchemy/orm/base.py +++ b/lib/sqlalchemy/orm/base.py @@ -798,7 +798,7 @@ class Mapped( The :class:`_orm.Mapped` class represents attributes that are handled directly by the :class:`_orm.Mapper` class. It does not include other Python descriptor classes that are provided as extensions, including - :ref:`hybrids_toplevel` and the :ref:`associationproxy_toplevel`. + ref_hybrids_toplevel and the ref_associationproxy_toplevel. While these systems still make use of ORM-specific superclasses and structures, they are not :term:`instrumented` by the :class:`_orm.Mapper` and instead provide their own functionality @@ -885,7 +885,7 @@ class DynamicMapped(_MappedAnnotationBase[_T]): .. legacy:: The "dynamic" lazy loader strategy is the legacy form of what is now the "write_only" strategy described in the section - :ref:`write_only_relationship`. + ref_write_only_relationship. E.g.:: @@ -896,13 +896,13 @@ class DynamicMapped(_MappedAnnotationBase[_T]): cascade="all,delete-orphan" ) - See the section :ref:`dynamic_relationship` for background. + See the section ref_dynamic_relationship for background. .. versionadded:: 2.0 .. seealso:: - :ref:`dynamic_relationship` - complete background + ref_dynamic_relationship - complete background :class:`.WriteOnlyMapped` - fully 2.0 style version @@ -938,13 +938,13 @@ class WriteOnlyMapped(_MappedAnnotationBase[_T]): cascade="all,delete-orphan" ) - See the section :ref:`write_only_relationship` for background. + See the section ref_write_only_relationship for background. .. versionadded:: 2.0 .. seealso:: - :ref:`write_only_relationship` - complete background + ref_write_only_relationship - complete background :class:`.DynamicMapped` - includes legacy :class:`_orm.Query` support diff --git a/lib/sqlalchemy/orm/decl_api.py b/lib/sqlalchemy/orm/decl_api.py index 2f8289acf..ecb1993bc 100644 --- a/lib/sqlalchemy/orm/decl_api.py +++ b/lib/sqlalchemy/orm/decl_api.py @@ -509,7 +509,7 @@ def declarative_mixin(cls: Type[_T]) -> Type[_T]: The :func:`_orm.declarative_mixin` decorator currently does not modify the given class in any way; it's current purpose is strictly to assist - the :ref:`Mypy plugin <mypy_toplevel>` in being able to identify + the ref_mypy_toplevel in being able to identify SQLAlchemy declarative mixin classes when no other context is present. .. versionadded:: 1.4.6 @@ -518,8 +518,8 @@ def declarative_mixin(cls: Type[_T]) -> Type[_T]: :ref:`orm_mixins_toplevel` - :ref:`mypy_declarative_mixins` - in the - :ref:`Mypy plugin documentation <mypy_toplevel>` + ref_mypy_declarative_mixins - in the + ref_mypy_toplevel """ # noqa: E501 @@ -573,7 +573,7 @@ class MappedAsDataclass(metaclass=DCTransformDeclarative): .. seealso:: - :ref:`orm_declarative_native_dataclasses` - complete background + ref_orm_declarative_native_dataclasses - complete background on SQLAlchemy native dataclass mapping .. versionadded:: 2.0 @@ -1594,7 +1594,7 @@ class registry: .. seealso:: - :ref:`orm_declarative_native_dataclasses` - complete background + ref_orm_declarative_native_dataclasses - complete background on SQLAlchemy native dataclass mapping diff --git a/lib/sqlalchemy/orm/descriptor_props.py b/lib/sqlalchemy/orm/descriptor_props.py index 2e57fd0f4..af94773d7 100644 --- a/lib/sqlalchemy/orm/descriptor_props.py +++ b/lib/sqlalchemy/orm/descriptor_props.py @@ -187,7 +187,7 @@ class CompositeProperty( .. seealso:: - :ref:`mapper_composite` + ref_mapper_composite """ @@ -729,7 +729,7 @@ class CompositeProperty( """Produce boolean, comparison, and other operators for :class:`.Composite` attributes. - See the example in :ref:`composite_operations` for an overview + See the example in ref_composite_operations for an overview of usage , as well as the documentation for :class:`.PropComparator`. .. seealso:: @@ -858,7 +858,7 @@ class Composite(CompositeProperty[_T], _DeclarativeMapped[_T]): .. seealso:: - :ref:`mapper_composite` + ref_mapper_composite """ diff --git a/lib/sqlalchemy/orm/events.py b/lib/sqlalchemy/orm/events.py index 9a1fd569a..538ac8979 100644 --- a/lib/sqlalchemy/orm/events.py +++ b/lib/sqlalchemy/orm/events.py @@ -579,7 +579,7 @@ class InstanceEvents(event.Events[ClassManager[Any]]): :ref:`orm_server_defaults` - :ref:`metadata_defaults_toplevel` + ref_metadata_defaults_toplevel """ @@ -962,7 +962,7 @@ class MapperEvents(event.Events[mapperlib.Mapper[Any]]): .. seealso:: - :ref:`examples_versioning` - an example which illustrates the use + ref_examples_versioning - an example which illustrates the use of the :meth:`_orm.MapperEvents.before_mapper_configured` event to create new mappers to record change-audit histories on objects. @@ -1735,14 +1735,14 @@ class SessionEvents(event.Events[Session]): and parameters as well as an option that allows programmatic invocation of the statement at any point. - :ref:`examples_session_orm_events` - includes examples of using + ref_examples_session_orm_events - includes examples of using :meth:`_orm.SessionEvents.do_orm_execute` - :ref:`examples_caching` - an example of how to integrate + ref_examples_caching - an example of how to integrate Dogpile caching with the ORM :class:`_orm.Session` making use of the :meth:`_orm.SessionEvents.do_orm_execute` event hook. - :ref:`examples_sharding` - the Horizontal Sharding example / + ref_examples_sharding - the Horizontal Sharding example / extension relies upon the :meth:`_orm.SessionEvents.do_orm_execute` event hook to invoke a SQL statement on multiple backends and return a merged result. @@ -2878,7 +2878,7 @@ class AttributeEvents(event.Events[QueryableAttribute[Any]]): we indicate that this value is to be persisted to the database. This supersedes the use of ``SOME_CONSTANT`` in the default generator for the :class:`_schema.Column`. The ``active_column_defaults.py`` - example given at :ref:`examples_instrumentation` illustrates using + example given at ref_examples_instrumentation illustrates using the same approach for a changing default, e.g. a timestamp generator. In this particular example, it is not strictly necessary to do this since ``SOME_CONSTANT`` would be part of the @@ -2939,7 +2939,7 @@ class AttributeEvents(event.Events[QueryableAttribute[Any]]): :class:`.AttributeEvents` - background on listener options such as propagation to subclasses. - :ref:`examples_instrumentation` - see the + ref_examples_instrumentation - see the ``active_column_defaults.py`` example. """ @@ -3070,7 +3070,7 @@ class QueryEvents(event.Events[Query[Any]]): the :meth:`_orm.QueryEvents.before_compile` event is **no longer used** for ORM-level attribute loads, such as loads of deferred or expired attributes as well as relationship loaders. See the - new examples in :ref:`examples_session_orm_events` which + new examples in ref_examples_session_orm_events which illustrate new ways of intercepting and modifying ORM queries for the most common purpose of adding arbitrary filter criteria. @@ -3121,7 +3121,7 @@ class QueryEvents(event.Events[Query[Any]]): :meth:`.QueryEvents.before_compile_delete` - :ref:`baked_with_before_compile` + ref_baked_with_before_compile """ diff --git a/lib/sqlalchemy/orm/mapper.py b/lib/sqlalchemy/orm/mapper.py index 731983ff4..863c0286c 100644 --- a/lib/sqlalchemy/orm/mapper.py +++ b/lib/sqlalchemy/orm/mapper.py @@ -432,7 +432,7 @@ class Mapper( be consistent in more scenarios independently of whether or not an orphan object has been flushed yet or not. - See the change note and example at :ref:`legacy_is_orphan_addition` + See the change note and example at ref_legacy_is_orphan_addition for more detail on this change. :param non_primary: Specify that this :class:`_orm.Mapper` @@ -668,7 +668,7 @@ class Mapper( .. seealso:: - :ref:`mapper_version_counter` - discussion of version counting + ref_mapper_version_counter - discussion of version counting and rationale. :param version_id_generator: Define how new version ids should @@ -682,14 +682,14 @@ class Mapper( Alternatively, server-side versioning functions such as triggers, or programmatic versioning schemes outside of the version id generator may be used, by specifying the value ``False``. - Please see :ref:`server_side_version_counter` for a discussion + Please see ref_server_side_version_counter for a discussion of important points when using this option. .. seealso:: - :ref:`custom_version_counter` + ref_custom_version_counter - :ref:`server_side_version_counter` + ref_server_side_version_counter :param with_polymorphic: A tuple in the form ``(<classes>, diff --git a/lib/sqlalchemy/orm/properties.py b/lib/sqlalchemy/orm/properties.py index 916b9d901..97032e070 100644 --- a/lib/sqlalchemy/orm/properties.py +++ b/lib/sqlalchemy/orm/properties.py @@ -283,7 +283,7 @@ class ColumnProperty( .. seealso:: - :ref:`mapper_column_property_sql_expressions_composed` + ref_mapper_column_property_sql_expressions_composed """ return self.columns[0] diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py index 5cd7cc117..dcda45bd4 100644 --- a/lib/sqlalchemy/orm/query.py +++ b/lib/sqlalchemy/orm/query.py @@ -1761,7 +1761,7 @@ class Query( statement executions, as the :class:`_orm.Session` will not track objects from different schema translate maps within a single session. For multiple schema translate maps within the scope of a - single :class:`_orm.Session`, see :ref:`examples_sharding`. + single :class:`_orm.Session`, see ref_examples_sharding. .. seealso:: @@ -3003,7 +3003,7 @@ class Query( The 'load' argument is the same as that of :meth:`.Session.merge`. For an example of how :meth:`_query.Query.merge_result` is used, see - the source code for the example :ref:`examples_caching`, where + the source code for the example ref_examples_caching, where :meth:`_query.Query.merge_result` is used to efficiently restore state from a cache back into a target :class:`.Session`. diff --git a/lib/sqlalchemy/orm/scoping.py b/lib/sqlalchemy/orm/scoping.py index 19217ec32..4d1bba555 100644 --- a/lib/sqlalchemy/orm/scoping.py +++ b/lib/sqlalchemy/orm/scoping.py @@ -143,11 +143,11 @@ __all__ = ["scoped_session"] class scoped_session(Generic[_S]): """Provides scoped management of :class:`.Session` objects. - See :ref:`unitofwork_contextual` for a tutorial. + See ref_unitofwork_contextual for a tutorial. .. note:: - When using :ref:`asyncio_toplevel`, the async-compatible + When using ref_asyncio_toplevel, the async-compatible :class:`_asyncio.async_scoped_session` class should be used in place of :class:`.scoped_session`. @@ -463,7 +463,7 @@ class scoped_session(Generic[_S]): :ref:`session_begin_nested` - :ref:`pysqlite_serializable` - special workarounds required + ref_pysqlite_serializable - special workarounds required with the SQLite driver in order for SAVEPOINT to work correctly. @@ -545,7 +545,7 @@ class scoped_session(Generic[_S]): :ref:`unitofwork_transaction` - :ref:`asyncio_orm_avoid_lazyloads` + ref_asyncio_orm_avoid_lazyloads """ # noqa: E501 @@ -765,7 +765,7 @@ class scoped_session(Generic[_S]): .. seealso:: - :ref:`session_expire` - introductory material + ref_session_expire - introductory material :meth:`.Session.expire` @@ -806,7 +806,7 @@ class scoped_session(Generic[_S]): .. seealso:: - :ref:`session_expire` - introductory material + ref_session_expire - introductory material :meth:`.Session.expire` @@ -1423,7 +1423,7 @@ class scoped_session(Generic[_S]): This operation cascades to associated instances if the association is mapped with ``cascade="merge"``. - See :ref:`unitofwork_merging` for a detailed discussion of merging. + See ref_unitofwork_merging for a detailed discussion of merging. :param instance: Instance to be merged. :param load: Boolean, when False, :meth:`.merge` switches into @@ -1658,7 +1658,7 @@ class scoped_session(Generic[_S]): .. seealso:: - :ref:`session_expire` - introductory material + ref_session_expire - introductory material :meth:`.Session.expire` diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py index 792b59e81..3b65e728a 100644 --- a/lib/sqlalchemy/orm/session.py +++ b/lib/sqlalchemy/orm/session.py @@ -1589,7 +1589,7 @@ class Session(_SessionClassMethods, EventTarget): .. tip:: When using SQLite, the SQLite driver included through Python 3.11 does not handle SAVEPOINTs correctly in all cases without workarounds. See the section - :ref:`pysqlite_serializable` for details on current workarounds. + ref_pysqlite_serializable for details on current workarounds. * ``"control_fully"`` - the :class:`_orm.Session` will take control of the given transaction as its own; @@ -1838,7 +1838,7 @@ class Session(_SessionClassMethods, EventTarget): :ref:`session_begin_nested` - :ref:`pysqlite_serializable` - special workarounds required + ref_pysqlite_serializable - special workarounds required with the SQLite driver in order for SAVEPOINT to work correctly. @@ -1895,7 +1895,7 @@ class Session(_SessionClassMethods, EventTarget): :ref:`unitofwork_transaction` - :ref:`asyncio_orm_avoid_lazyloads` + ref_asyncio_orm_avoid_lazyloads """ trans = self._transaction @@ -2972,7 +2972,7 @@ class Session(_SessionClassMethods, EventTarget): .. seealso:: - :ref:`session_expire` - introductory material + ref_session_expire - introductory material :meth:`.Session.expire` @@ -3051,7 +3051,7 @@ class Session(_SessionClassMethods, EventTarget): .. seealso:: - :ref:`session_expire` - introductory material + ref_session_expire - introductory material :meth:`.Session.expire` @@ -3093,7 +3093,7 @@ class Session(_SessionClassMethods, EventTarget): .. seealso:: - :ref:`session_expire` - introductory material + ref_session_expire - introductory material :meth:`.Session.expire` @@ -3704,7 +3704,7 @@ class Session(_SessionClassMethods, EventTarget): This operation cascades to associated instances if the association is mapped with ``cascade="merge"``. - See :ref:`unitofwork_merging` for a detailed discussion of merging. + See ref_unitofwork_merging for a detailed discussion of merging. :param instance: Instance to be merged. :param load: Boolean, when False, :meth:`.merge` switches into diff --git a/lib/sqlalchemy/orm/state.py b/lib/sqlalchemy/orm/state.py index 708939531..75ecb2bbe 100644 --- a/lib/sqlalchemy/orm/state.py +++ b/lib/sqlalchemy/orm/state.py @@ -221,7 +221,7 @@ class InstanceState(interfaces.InspectionAttrInfo, Generic[_O]): .. seealso:: - :ref:`session_object_states` + ref_session_object_states """ return self.key is None and not self._attached @@ -233,7 +233,7 @@ class InstanceState(interfaces.InspectionAttrInfo, Generic[_O]): .. seealso:: - :ref:`session_object_states` + ref_session_object_states """ return self.key is None and self._attached @@ -263,7 +263,7 @@ class InstanceState(interfaces.InspectionAttrInfo, Generic[_O]): .. seealso:: - :ref:`session_object_states` + ref_session_object_states """ return self.key is not None and self._attached and self._deleted @@ -284,7 +284,7 @@ class InstanceState(interfaces.InspectionAttrInfo, Generic[_O]): :func:`.orm.util.was_deleted` - standalone function - :ref:`session_object_states` + ref_session_object_states """ return self._deleted @@ -299,7 +299,7 @@ class InstanceState(interfaces.InspectionAttrInfo, Generic[_O]): .. seealso:: - :ref:`session_object_states` + ref_session_object_states """ return self.key is not None and self._attached and not self._deleted @@ -310,7 +310,7 @@ class InstanceState(interfaces.InspectionAttrInfo, Generic[_O]): .. seealso:: - :ref:`session_object_states` + ref_session_object_states """ return self.key is not None and not self._attached @@ -377,7 +377,7 @@ class InstanceState(interfaces.InspectionAttrInfo, Generic[_O]): .. seealso:: - :ref:`asyncio_toplevel` + ref_asyncio_toplevel """ if _async_provider is None: diff --git a/lib/sqlalchemy/orm/util.py b/lib/sqlalchemy/orm/util.py index d3e36a494..62d800745 100644 --- a/lib/sqlalchemy/orm/util.py +++ b/lib/sqlalchemy/orm/util.py @@ -679,7 +679,7 @@ class AliasedClass( same attribute and method interface as the original mapped class, allowing :class:`.AliasedClass` to be compatible with any attribute technique which works on the original class, - including hybrid attributes (see :ref:`hybrids_toplevel`). + including hybrid attributes (see ref_hybrids_toplevel). The :class:`.AliasedClass` can be inspected for its underlying :class:`_orm.Mapper`, aliased selectable, and other information @@ -885,7 +885,7 @@ class AliasedInsp( .. seealso:: - :ref:`inspection_toplevel` + ref_inspection_toplevel """ diff --git a/lib/sqlalchemy/orm/writeonly.py b/lib/sqlalchemy/orm/writeonly.py index a362750f6..9f7de7446 100644 --- a/lib/sqlalchemy/orm/writeonly.py +++ b/lib/sqlalchemy/orm/writeonly.py @@ -500,13 +500,13 @@ class WriteOnlyCollection(AbstractCollectionWriter[_T]): The :class:`.WriteOnlyCollection` is used in a mapping by using the ``"write_only"`` lazy loading strategy with :func:`_orm.relationship`. For background on this configuration, - see :ref:`write_only_relationship`. + see ref_write_only_relationship. .. versionadded:: 2.0 .. seealso:: - :ref:`write_only_relationship` + ref_write_only_relationship """ diff --git a/lib/sqlalchemy/pool/impl.py b/lib/sqlalchemy/pool/impl.py index 99779d54f..30efd8602 100644 --- a/lib/sqlalchemy/pool/impl.py +++ b/lib/sqlalchemy/pool/impl.py @@ -327,7 +327,7 @@ class SingletonThreadPool(Pool): :class:`.SingletonThreadPool` is used by the SQLite dialect automatically when a memory-based database is used. - See :ref:`sqlite_toplevel`. + See ref_sqlite_toplevel. """ diff --git a/lib/sqlalchemy/sql/_elements_constructors.py b/lib/sqlalchemy/sql/_elements_constructors.py index 99a839cc9..a2f9564bd 100644 --- a/lib/sqlalchemy/sql/_elements_constructors.py +++ b/lib/sqlalchemy/sql/_elements_constructors.py @@ -667,7 +667,7 @@ def bindparam( :meth:`.ColumnOperators.in_` - :ref:`baked_in` - with baked queries + ref_baked_in - with baked queries .. note:: The "expanding" feature does not support "executemany"- style parameter sets. diff --git a/lib/sqlalchemy/sql/dml.py b/lib/sqlalchemy/sql/dml.py index 911061640..2ea3b3b34 100644 --- a/lib/sqlalchemy/sql/dml.py +++ b/lib/sqlalchemy/sql/dml.py @@ -1257,7 +1257,7 @@ class Insert(ValuesBase): correspond. :param include_defaults: if True, non-server default values and SQL expressions as specified on :class:`_schema.Column` objects - (as documented in :ref:`metadata_defaults_toplevel`) not + (as documented in ref_metadata_defaults_toplevel) not otherwise specified in the list of names will be rendered into the INSERT and SELECT statements, so that these values are also included in the data to be inserted. diff --git a/lib/sqlalchemy/sql/events.py b/lib/sqlalchemy/sql/events.py index b34d07412..1cd0aabdf 100644 --- a/lib/sqlalchemy/sql/events.py +++ b/lib/sqlalchemy/sql/events.py @@ -446,10 +446,10 @@ class DDLEvents(event.Events[SchemaEventTarget]): :ref:`mapper_automated_reflection_schemes` - in the ORM mapping documentation - :ref:`automap_intercepting_columns` - - in the :ref:`automap_toplevel` documentation + ref_automap_intercepting_columns - + in the ref_automap_toplevel documentation - :ref:`metadata_reflection_dbagnostic_types` - in - the :ref:`metadata_reflection_toplevel` documentation + ref_metadata_reflection_dbagnostic_types - in + the ref_metadata_reflection_toplevel documentation """ diff --git a/lib/sqlalchemy/sql/functions.py b/lib/sqlalchemy/sql/functions.py index 30ef0b7e3..0b8fd626c 100644 --- a/lib/sqlalchemy/sql/functions.py +++ b/lib/sqlalchemy/sql/functions.py @@ -276,7 +276,7 @@ class FunctionElement(Executable, ColumnElement[_T], FromClause, Generative): :ref:`tutorial_functions_table_valued` - in the :ref:`unified_tutorial` - :ref:`postgresql_table_valued` - in the :ref:`postgresql_toplevel` documentation + ref_postgresql_table_valued - in the :ref:`postgresql_toplevel` documentation :meth:`_functions.FunctionElement.scalar_table_valued` - variant of :meth:`_functions.FunctionElement.table_valued` which delivers the @@ -336,7 +336,7 @@ class FunctionElement(Executable, ColumnElement[_T], FromClause, Generative): :ref:`tutorial_functions_column_valued` - in the :ref:`unified_tutorial` - :ref:`postgresql_column_valued` - in the :ref:`postgresql_toplevel` documentation + ref_postgresql_column_valued - in the :ref:`postgresql_toplevel` documentation :meth:`_functions.FunctionElement.table_valued` @@ -840,7 +840,7 @@ class _FunctionGenerator: Functions which are interpreted as "generic" functions know how to calculate their return type automatically. For a listing of known generic - functions, see :ref:`generic_functions`. + functions, see ref_generic_functions. .. note:: diff --git a/lib/sqlalchemy/sql/operators.py b/lib/sqlalchemy/sql/operators.py index 352e5b62d..fbc0153f6 100644 --- a/lib/sqlalchemy/sql/operators.py +++ b/lib/sqlalchemy/sql/operators.py @@ -1521,7 +1521,7 @@ class ColumnOperators(Operators): .. versionchanged:: 2.0 ``plainto_tsquery()`` is used instead of ``to_tsquery()`` for PostgreSQL now; for compatibility with - other forms, see :ref:`postgresql_match`. + other forms, see ref_postgresql_match. * MySQL - renders ``MATCH (x) AGAINST (y IN BOOLEAN MODE)`` diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py index 192096469..fa2110947 100644 --- a/lib/sqlalchemy/sql/schema.py +++ b/lib/sqlalchemy/sql/schema.py @@ -590,11 +590,11 @@ class Table( .. seealso:: - :ref:`metadata_reflection_toplevel` + ref_metadata_reflection_toplevel :meth:`_events.DDLEvents.column_reflect` - :ref:`metadata_reflection_dbagnostic_types` + ref_metadata_reflection_dbagnostic_types :param extend_existing: When ``True``, indicates that if this :class:`_schema.Table` is already present in the given @@ -662,7 +662,7 @@ class Table( In modern SQLAlchemy there is generally no reason to alter this setting, except for some backend specific cases - (see :ref:`mssql_triggers` in the SQL Server dialect documentation + (see ref_mssql_triggers in the SQL Server dialect documentation for one such example). :param include_columns: A list of strings indicating a subset of @@ -1699,7 +1699,7 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause[_T]): to render the special SQLite keyword ``AUTOINCREMENT`` is not included as this is unnecessary and not recommended by the database vendor. See the section - :ref:`sqlite_autoincrement` for more background. + ref_sqlite_autoincrement for more background. * Oracle - The Oracle dialect has no default "autoincrement" feature available at this time, instead the :class:`.Identity` construct is recommended to achieve this (the :class:`.Sequence` @@ -1755,7 +1755,7 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause[_T]): .. seealso:: - :ref:`metadata_defaults_toplevel` + ref_metadata_defaults_toplevel :param doc: optional String that can be used by the ORM or similar to document attributes on the Python side. This attribute does @@ -1852,7 +1852,7 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause[_T]): .. seealso:: - :ref:`metadata_defaults` - complete discussion of onupdate + ref_metadata_defaults - complete discussion of onupdate :param primary_key: If ``True``, marks this column as a primary key column. Multiple columns can have this flag set to specify @@ -1915,7 +1915,7 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause[_T]): .. seealso:: - :ref:`server_defaults` - complete discussion of server side + ref_server_defaults - complete discussion of server side defaults :param server_onupdate: A :class:`.FetchedValue` instance @@ -1929,12 +1929,12 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause[_T]): .. warning:: This directive **does not** currently produce MySQL's "ON UPDATE CURRENT_TIMESTAMP()" clause. See - :ref:`mysql_timestamp_onupdate` for background on how to + ref_mysql_timestamp_onupdate for background on how to produce this clause. .. seealso:: - :ref:`triggered_columns` + ref_triggered_columns :param quote: Force quoting of this column's name on or off, corresponding to ``True`` or ``False``. When left at its default @@ -3681,7 +3681,7 @@ class Sequence(HasSchemaAttr, IdentityOptions, DefaultGenerator): .. seealso:: - :ref:`defaults_sequences` + ref_defaults_sequences :class:`.CreateSequence` @@ -3955,7 +3955,7 @@ class FetchedValue(SchemaEventTarget): .. seealso:: - :ref:`triggered_columns` + ref_triggered_columns """ @@ -5140,13 +5140,13 @@ class Index( :ref:`schema_indexes` - General information on :class:`.Index`. - :ref:`postgresql_indexes` - PostgreSQL-specific options available for + ref_postgresql_indexes - PostgreSQL-specific options available for the :class:`.Index` construct. - :ref:`mysql_indexes` - MySQL-specific options available for the + ref_mysql_indexes - MySQL-specific options available for the :class:`.Index` construct. - :ref:`mssql_indexes` - MSSQL-specific options available for the + ref_mssql_indexes - MSSQL-specific options available for the :class:`.Index` construct. """ @@ -5676,13 +5676,13 @@ class MetaData(HasSchemaAttr): .. seealso:: - :ref:`metadata_reflection_toplevel` + ref_metadata_reflection_toplevel :meth:`_events.DDLEvents.column_reflect` - Event used to customize the reflected columns. Usually used to generalize the types using :meth:`_types.TypeEngine.as_generic` - :ref:`metadata_reflection_dbagnostic_types` - describes how to + ref_metadata_reflection_dbagnostic_types - describes how to reflect tables using general types. """ diff --git a/lib/sqlalchemy/sql/sqltypes.py b/lib/sqlalchemy/sql/sqltypes.py index 4e7514e38..60ca40a50 100644 --- a/lib/sqlalchemy/sql/sqltypes.py +++ b/lib/sqlalchemy/sql/sqltypes.py @@ -1775,7 +1775,7 @@ class PickleType(TypeDecorator[object]): a serialized binary field. To allow ORM change events to propagate for elements associated - with :class:`.PickleType`, see :ref:`mutable_toplevel`. + with :class:`.PickleType`, see ref_mutable_toplevel. """ diff --git a/lib/sqlalchemy/sql/type_api.py b/lib/sqlalchemy/sql/type_api.py index 5af12cb93..e031c5efa 100644 --- a/lib/sqlalchemy/sql/type_api.py +++ b/lib/sqlalchemy/sql/type_api.py @@ -863,7 +863,7 @@ class TypeEngine(Visitable, Generic[_T]): .. seealso:: - :ref:`metadata_reflection_dbagnostic_types` - describes the + ref_metadata_reflection_dbagnostic_types - describes the use of :meth:`_types.TypeEngine.as_generic` in conjunction with the :meth:`_sql.DDLEvents.column_reflect` event, which is its intended use. |