diff options
36 files changed, 134 insertions, 85 deletions
diff --git a/doc/build/changelog/changelog_06.rst b/doc/build/changelog/changelog_06.rst index cd3b32d95..739df36b2 100644 --- a/doc/build/changelog/changelog_06.rst +++ b/doc/build/changelog/changelog_06.rst @@ -2,6 +2,7 @@ 0.6 Changelog ============= + .. changelog:: :version: 0.6.9 :released: Sat May 05 2012 diff --git a/doc/build/changelog/changelog_08.rst b/doc/build/changelog/changelog_08.rst index f65006100..decf36559 100644 --- a/doc/build/changelog/changelog_08.rst +++ b/doc/build/changelog/changelog_08.rst @@ -7,6 +7,7 @@ .. include:: changelog_07.rst :start-line: 5 + .. changelog:: :version: 0.8.7 :released: July 22, 2014 diff --git a/doc/build/changelog/changelog_09.rst b/doc/build/changelog/changelog_09.rst index 7ee874e02..acf1ede92 100644 --- a/doc/build/changelog/changelog_09.rst +++ b/doc/build/changelog/changelog_09.rst @@ -1920,7 +1920,7 @@ .. change:: :tags: feature, sql - Added :paramref:`.MetaData.reflect.**dialect_kwargs` + Added :paramref:`.MetaData.reflect.dialect_kwargs` to support dialect-level reflection options for all :class:`_schema.Table` objects reflected. diff --git a/doc/build/changelog/changelog_11.rst b/doc/build/changelog/changelog_11.rst index 1988b69b3..c84effc39 100644 --- a/doc/build/changelog/changelog_11.rst +++ b/doc/build/changelog/changelog_11.rst @@ -20,7 +20,6 @@ :start-line: 5 - .. changelog:: :version: 1.1.18 :released: March 6, 2018 @@ -1076,7 +1075,7 @@ :tickets: 3842 Fixed bug where newly added warning for primary key on insert w/o - autoincrement setting (see :ref:`change_3216`) would fail to emit + autoincrement setting (see :ticket:`3216`) would fail to emit correctly when invoked upon a lower-case :func:`.table` construct. .. change:: 3852 diff --git a/doc/build/changelog/changelog_12.rst b/doc/build/changelog/changelog_12.rst index 6dc7d7f88..b5d331e71 100644 --- a/doc/build/changelog/changelog_12.rst +++ b/doc/build/changelog/changelog_12.rst @@ -453,7 +453,7 @@ :tickets: 4352 The column conflict resolution technique discussed at - :ref:`declarative_column_conflicts` is now functional for a :class:`_schema.Column` + :ref:`orm_inheritance_column_conflicts` is now functional for a :class:`_schema.Column` that is also a primary key column. Previously, a check for primary key columns declared on a single-inheritance subclass would occur before the column copy were allowed to pass. diff --git a/doc/build/changelog/changelog_13.rst b/doc/build/changelog/changelog_13.rst index 96002c19e..aba0f4950 100644 --- a/doc/build/changelog/changelog_13.rst +++ b/doc/build/changelog/changelog_13.rst @@ -950,8 +950,8 @@ :tags: usecase, postgresql :tickets: 5265 - Added support for columns or type :class:`.ARRAY` of :class:`.Enum`, - :class:`.JSON` or :class:`_postgresql.JSONB` in PostgreSQL. + Added support for columns or type :class:`_sqltypes.ARRAY` of :class:`.Enum`, + :class:`_postgresql.JSON` or :class:`_postgresql.JSONB` in PostgreSQL. Previously a workaround was required in these use cases. @@ -1002,7 +1002,7 @@ :tickets: 5266 Raise an explicit :class:`.exc.CompileError` when adding a table with a - column of type :class:`.ARRAY` of :class:`.Enum` configured with + column of type :class:`_sqltypes.ARRAY` of :class:`.Enum` configured with :paramref:`.Enum.native_enum` set to ``False`` when :paramref:`.Enum.create_constraint` is not set to ``False`` @@ -1966,13 +1966,13 @@ :class:`_types.JSON` - :meth:`.JSON.Comparator.as_string` + :meth:`_sqltypes.JSON.Comparator.as_string` - :meth:`.JSON.Comparator.as_boolean` + :meth:`_sqltypes.JSON.Comparator.as_boolean` - :meth:`.JSON.Comparator.as_float` + :meth:`_sqltypes.JSON.Comparator.as_float` - :meth:`.JSON.Comparator.as_integer` + :meth:`_sqltypes.JSON.Comparator.as_integer` .. change:: :tags: usecase, oracle @@ -3828,7 +3828,7 @@ Added support for the parameters in an ON DUPLICATE KEY UPDATE statement on MySQL to be ordered, since parameter order in a MySQL UPDATE clause is significant, in a similar manner as that described at - :ref:`updates_order_parameters`. Pull request courtesy Maxim Bublis. + :ref:`tutorial_parameter_ordered_updates`. Pull request courtesy Maxim Bublis. .. seealso:: diff --git a/doc/build/changelog/changelog_14.rst b/doc/build/changelog/changelog_14.rst index e0b464974..e457a4c46 100644 --- a/doc/build/changelog/changelog_14.rst +++ b/doc/build/changelog/changelog_14.rst @@ -34,7 +34,7 @@ This document details individual issue-level changes made throughout :tickets: 7936 Fixed regression where the change made for :ticket:`7861`, released in - version 1.4.33, that brought the :class:`.Insert` construct to be partially + version 1.4.33, that brought the :class:`_sql.Insert` construct to be partially recognized as an ORM-enabled statement did not properly transfer the correct mapper / mapped table state to the :class:`.Session`, causing the :meth:`.Session.get_bind` method to fail for a :class:`.Session` that was @@ -58,7 +58,7 @@ This document details individual issue-level changes made throughout :tags: bug, postgresql :tickets: 6515 - Fixed bug in :class:`.ARRAY` datatype in combination with :class:`.Enum` on + Fixed bug in :class:`_sqltypes.ARRAY` datatype in combination with :class:`.Enum` on PostgreSQL where using the ``.any()`` or ``.all()`` methods to render SQL ANY() or ALL(), given members of the Python enumeration as arguments, would produce a type adaptation failure on all drivers. @@ -87,7 +87,7 @@ This document details individual issue-level changes made throughout :tickets: 7930 Fixed an issue in the psycopg2 dialect when using the - :paramref:`.create_engine.pool_pre_ping` parameter which would cause + :paramref:`_sa.create_engine.pool_pre_ping` parameter which would cause user-configured ``AUTOCOMMIT`` isolation level to be inadvertently reset by the "ping" handler. @@ -105,15 +105,15 @@ This document details individual issue-level changes made throughout :tags: bug, engine :tickets: 7953 - Added a warning regarding a bug which exists in the :meth:`.Result.columns` - method when passing 0 for the index in conjunction with a :class:`.Result` + Added a warning regarding a bug which exists in the :meth:`_result.Result.columns` + method when passing 0 for the index in conjunction with a :class:`_result.Result` that will return a single ORM entity, which indicates that the current - behavior of :meth:`.Result.columns` is broken in this case as the - :class:`.Result` object will yield scalar values and not :class:`.Row` + behavior of :meth:`_result.Result.columns` is broken in this case as the + :class:`_result.Result` object will yield scalar values and not :class:`.Row` objects. The issue will be fixed in 2.0, which would be a backwards-incompatible change for code that relies on the current broken behavior. Code which wants to receive a collection of scalar values should - use the :meth:`.Result.scalars` method, which will return a new + use the :meth:`_result.Result.scalars` method, which will return a new :class:`.ScalarResult` object that yields non-row scalar objects. @@ -199,7 +199,7 @@ This document details individual issue-level changes made throughout :tickets: 7878 Fixed regression caused by :ticket:`7861` where invoking an - :class:`.Insert` construct which contained ORM entities directly via + :class:`_sql.Insert` construct which contained ORM entities directly via :meth:`_orm.Session.execute` would fail. .. change:: @@ -226,8 +226,8 @@ This document details individual issue-level changes made throughout and COMMIT log messages do not actually indicate a real transaction when the AUTOCOMMIT isolation level is in use; messaging has been extended to include the BEGIN message itself, and the messaging has also been fixed to - accommodate when the :class:`.Engine` level - :paramref:`.create_engine.isolation_level` parameter was used directly. + accommodate when the :class:`_engine.Engine` level + :paramref:`_sa.create_engine.isolation_level` parameter was used directly. .. change:: :tags: bug, mssql, regression @@ -314,7 +314,7 @@ This document details individual issue-level changes made throughout :tags: usecase, engine :tickets: 7877, 7815 - Added new parameter :paramref:`.Engine.dispose.close`, defaulting to True. + Added new parameter :paramref:`_engine.Engine.dispose.close`, defaulting to True. When False, the engine disposal does not touch the connections in the old pool at all, simply dropping the pool and replacing it. This use case is so that when the original pool is transferred from a parent process, the @@ -339,7 +339,7 @@ This document details individual issue-level changes made throughout Added new attributes :attr:`.UpdateBase.returning_column_descriptions` and :attr:`.UpdateBase.entity_description` to allow for inspection of ORM - attributes and entities that are installed as part of an :class:`.Insert`, + attributes and entities that are installed as part of an :class:`_sql.Insert`, :class:`.Update`, or :class:`.Delete` construct. The :attr:`.Select.column_descriptions` accessor is also now implemented for Core-only selectables. @@ -1638,15 +1638,15 @@ This document details individual issue-level changes made throughout :tags: bug, orm :tickets: 7128 - Fixed bug where iterating a :class:`.Result` from a :class:`_orm.Session` + Fixed bug where iterating a :class:`_result.Result` from a :class:`_orm.Session` after that :class:`_orm.Session` were closed would partially attach objects to that session in an essentially invalid state. It now raises an exception with a link to new documentation if an **un-buffered** result is iterated from a :class:`_orm.Session` that was closed or otherwise had the - :meth:`_orm.Session.expunge_all` method called after that :class:`.Result` + :meth:`_orm.Session.expunge_all` method called after that :class:`_result.Result` was generated. The ``prebuffer_rows`` execution option, as is used automatically by the asyncio extension for client-side result sets, may be - used to produce a :class:`.Result` where the ORM objects are prebuffered, + used to produce a :class:`_result.Result` where the ORM objects are prebuffered, and in this case iterating the result will produce a series of detached objects. @@ -3484,7 +3484,7 @@ This document details individual issue-level changes made throughout :tickets: 6361 Fixed issue where usage of an explicit :class:`.Sequence` would produce - inconsistent "inline" behavior for an :class:`.Insert` construct that + inconsistent "inline" behavior for an :class:`_sql.Insert` construct that includes multiple values phrases; the first seq would be inline but subsequent ones would be "pre-execute", leading to inconsistent sequence ordering. The sequence expressions are now fully inline. @@ -4931,7 +4931,7 @@ This document details individual issue-level changes made throughout :tags: bug, engine, sqlite :tickets: 5845 - Fixed bug in the 2.0 "future" version of :class:`.Engine` where emitting + Fixed bug in the 2.0 "future" version of :class:`_engine.Engine` where emitting SQL during the :meth:`.EngineEvents.begin` event hook would cause a re-entrant (recursive) condition due to autobegin, affecting among other things the recipe documented for SQLite to allow for savepoints and diff --git a/doc/build/conf.py b/doc/build/conf.py index 037c93bb7..46fd6147f 100644 --- a/doc/build/conf.py +++ b/doc/build/conf.py @@ -109,7 +109,7 @@ changelog_render_pullreq = { changelog_render_changeset = "https://www.sqlalchemy.org/trac/changeset/%s" -exclude_patterns = ["build", "**/unreleased*/*", "*_include.rst"] +exclude_patterns = ["build", "**/unreleased*/*", "**/*_include.rst"] autodoc_class_signature = "separated" autodoc_typehints_format = "short" diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst index a3d85896d..123c9b6a1 100644 --- a/doc/build/core/connections.rst +++ b/doc/build/core/connections.rst @@ -1981,11 +1981,12 @@ Connection / Engine API Result Set API ================= -.. autoclass:: BaseCursorResult +.. autoclass:: ChunkedIteratorResult :members: -.. autoclass:: ChunkedIteratorResult +.. autoclass:: CursorResult :members: + :inherited-members: .. autoclass:: FrozenResult :members: @@ -1999,22 +2000,14 @@ Result Set API .. autoclass:: Result :members: :inherited-members: - :exclude-members: memoized_attribute, memoized_instancemethod .. autoclass:: ScalarResult :members: :inherited-members: - :exclude-members: memoized_attribute, memoized_instancemethod .. autoclass:: MappingResult :members: :inherited-members: - :exclude-members: memoized_attribute, memoized_instancemethod - -.. autoclass:: CursorResult - :members: - :inherited-members: - :exclude-members: memoized_attribute, memoized_instancemethod .. autoclass:: Row :members: diff --git a/doc/build/core/constraints.rst b/doc/build/core/constraints.rst index 97a043aab..6815da4dc 100644 --- a/doc/build/core/constraints.rst +++ b/doc/build/core/constraints.rst @@ -768,6 +768,7 @@ The above schema will produce:: Constraints API --------------- + .. autoclass:: Constraint :members: :inherited-members: diff --git a/doc/build/core/ddl.rst b/doc/build/core/ddl.rst index c34a4e1a3..bccfb76cc 100644 --- a/doc/build/core/ddl.rst +++ b/doc/build/core/ddl.rst @@ -320,8 +320,6 @@ DDL Expression Constructs API .. autoclass:: BaseDDLElement :members: -.. autoattr:: DDLElement - .. autoclass:: ExecutableDDLElement :members: diff --git a/doc/build/core/index.rst b/doc/build/core/index.rst index 4c6cfc840..fda2b65ed 100644 --- a/doc/build/core/index.rst +++ b/doc/build/core/index.rst @@ -20,3 +20,5 @@ Language provides a schema-centric usage paradigm. .. toctree:: :hidden: + + tutorial
\ No newline at end of file diff --git a/doc/build/core/metadata.rst b/doc/build/core/metadata.rst index 551fe918c..38edab642 100644 --- a/doc/build/core/metadata.rst +++ b/doc/build/core/metadata.rst @@ -384,7 +384,7 @@ at once, such as:: :ref:`multipart_schema_names` - describes use of dotted schema names with the SQL Server dialect. - :ref:`schema_table_reflection` + :ref:`metadata_reflection_schemas` .. _schema_metadata_schema_name: diff --git a/doc/build/core/reflection.rst b/doc/build/core/reflection.rst index f91a7453e..7002722c6 100644 --- a/doc/build/core/reflection.rst +++ b/doc/build/core/reflection.rst @@ -139,7 +139,7 @@ a :class:`_schema.MetaData` object configured with a default schema name >>> metadata_obj = MetaData(schema="project") -The :method:`.MetaData.reflect` will then utilize that configured ``.schema`` +The :meth:`.MetaData.reflect` will then utilize that configured ``.schema`` for reflection:: >>> # uses `schema` configured in metadata_obj diff --git a/doc/build/dialects/mssql.rst b/doc/build/dialects/mssql.rst index 9de56338f..c107e4ca6 100644 --- a/doc/build/dialects/mssql.rst +++ b/doc/build/dialects/mssql.rst @@ -29,6 +29,10 @@ they originate from :mod:`sqlalchemy.types` or from the local dialect:: Types which are specific to SQL Server, or have SQL Server-specific construction arguments, are as follows: +.. note: where :noindex: is used, indicates a type that is not redefined + in the dialect module, just imported from sqltypes. this avoids warnings + in the sphinx build + .. currentmodule:: sqlalchemy.dialects.mssql .. autoclass:: BIT @@ -37,6 +41,7 @@ construction arguments, are as follows: .. autoclass:: CHAR :members: __init__ + :noindex: .. autoclass:: DATETIME2 @@ -61,6 +66,7 @@ construction arguments, are as follows: .. autoclass:: NCHAR :members: __init__ + :noindex: .. autoclass:: NTEXT @@ -69,7 +75,7 @@ construction arguments, are as follows: .. autoclass:: NVARCHAR :members: __init__ - + :noindex: .. autoclass:: REAL :members: __init__ @@ -91,7 +97,7 @@ construction arguments, are as follows: .. autoclass:: TEXT :members: __init__ - + :noindex: .. autoclass:: TIME :members: __init__ @@ -110,9 +116,11 @@ construction arguments, are as follows: .. autoclass:: VARBINARY :members: __init__ + :noindex: .. autoclass:: VARCHAR :members: __init__ + :noindex: .. autoclass:: XML diff --git a/doc/build/dialects/mysql.rst b/doc/build/dialects/mysql.rst index 4ad43cf56..83aa30bcb 100644 --- a/doc/build/dialects/mysql.rst +++ b/doc/build/dialects/mysql.rst @@ -29,6 +29,10 @@ valid with MySQL are importable from the top level dialect:: Types which are specific to MySQL, or have MySQL-specific construction arguments, are as follows: +.. note: where :noindex: is used, indicates a type that is not redefined + in the dialect module, just imported from sqltypes. this avoids warnings + in the sphinx build + .. currentmodule:: sqlalchemy.dialects.mysql .. autoclass:: BIGINT @@ -36,6 +40,7 @@ construction arguments, are as follows: .. autoclass:: BINARY + :noindex: :members: __init__ @@ -45,10 +50,12 @@ construction arguments, are as follows: .. autoclass:: BLOB :members: __init__ + :noindex: .. autoclass:: BOOLEAN :members: __init__ + :noindex: .. autoclass:: CHAR @@ -57,6 +64,7 @@ construction arguments, are as follows: .. autoclass:: DATE :members: __init__ + :noindex: .. autoclass:: DATETIME @@ -131,6 +139,7 @@ construction arguments, are as follows: .. autoclass:: TEXT :members: __init__ + :noindex: .. autoclass:: TIME @@ -155,6 +164,7 @@ construction arguments, are as follows: .. autoclass:: VARBINARY :members: __init__ + :noindex: .. autoclass:: VARCHAR diff --git a/doc/build/dialects/postgresql.rst b/doc/build/dialects/postgresql.rst index d3c9928c7..dc1f7a21e 100644 --- a/doc/build/dialects/postgresql.rst +++ b/doc/build/dialects/postgresql.rst @@ -22,6 +22,10 @@ they originate from :mod:`sqlalchemy.types` or from the local dialect:: Types which are specific to PostgreSQL, or have PostgreSQL-specific construction arguments, are as follows: +.. note: where :noindex: is used, indicates a type that is not redefined + in the dialect module, just imported from sqltypes. this avoids warnings + in the sphinx build + .. currentmodule:: sqlalchemy.dialects.postgresql .. autoclass:: aggregate_order_by @@ -80,6 +84,7 @@ construction arguments, are as follows: .. autoclass:: REAL :members: __init__ + :noindex: .. autoclass:: REGCLASS diff --git a/doc/build/glossary.rst b/doc/build/glossary.rst index 2e7411308..a54d7715e 100644 --- a/doc/build/glossary.rst +++ b/doc/build/glossary.rst @@ -25,6 +25,19 @@ Glossary :ref:`migration_20_toplevel` + + imperative + declarative + + In the SQLAlchemy ORM, these terms refer to two different styles of + mapping Python classes to database tables. + + .. seealso:: + + :ref:`orm_declarative_mapping` + + :ref:`orm_imperative_mapping` + facade An object that serves as a front-facing interface masking more complex @@ -1453,3 +1466,11 @@ Glossary :ref:`session_object_states` + attached + Indicates an ORM object that is presently associated with a specific + :term:`Session`. + + .. seealso:: + + :ref:`session_object_states` + diff --git a/doc/build/index.rst b/doc/build/index.rst index f27202d33..cfab3c543 100644 --- a/doc/build/index.rst +++ b/doc/build/index.rst @@ -161,3 +161,4 @@ SQLAlchemy Documentation * :doc:`Error Message Guide <errors>` - Explainations of many SQLAlchemy Errors * :doc:`Complete table of of contents <contents>` * :doc:`Index <index>` + diff --git a/doc/build/orm/collections.rst b/doc/build/orm/collections.rst index 716fea74e..b34ce7f14 100644 --- a/doc/build/orm/collections.rst +++ b/doc/build/orm/collections.rst @@ -658,8 +658,6 @@ Various internal methods. .. autofunction:: bulk_replace -.. autoclass:: collection - .. autodata:: collection_adapter .. autoclass:: CollectionAdapter diff --git a/doc/build/orm/contextual.rst b/doc/build/orm/contextual.rst index 5cd2ab441..f821b271f 100644 --- a/doc/build/orm/contextual.rst +++ b/doc/build/orm/contextual.rst @@ -22,7 +22,7 @@ Architecture <https://martinfowler.com/eaaCatalog/registry.html>`_. .. warning:: The :class:`.scoped_session` registry by default uses a Python - `threading.local() <https://docs.python.org/3/library/threading.html#thread-local-data>`_ + ``threading.local()`` in order to track :class:`_orm.Session` instances. **This is not necessarily compatible with all application servers**, particularly those which make use of greenlets or other alternative forms of concurrency diff --git a/doc/build/orm/extensions/associationproxy.rst b/doc/build/orm/extensions/associationproxy.rst index cf51ee9a6..b788c3b61 100644 --- a/doc/build/orm/extensions/associationproxy.rst +++ b/doc/build/orm/extensions/associationproxy.rst @@ -592,4 +592,4 @@ API Documentation :members: :inherited-members: -.. autodata:: ASSOCIATION_PROXY +.. autoclass:: AssociationProxyExtensionType diff --git a/doc/build/orm/extensions/hybrid.rst b/doc/build/orm/extensions/hybrid.rst index 16cdafebc..571aca722 100644 --- a/doc/build/orm/extensions/hybrid.rst +++ b/doc/build/orm/extensions/hybrid.rst @@ -15,8 +15,6 @@ API Reference :members: .. autoclass:: Comparator - -.. autodata:: HYBRID_METHOD -.. autodata:: HYBRID_PROPERTY +.. autoclass:: HybridExtensionType diff --git a/doc/build/orm/internals.rst b/doc/build/orm/internals.rst index 9aa3b2db6..ee0064271 100644 --- a/doc/build/orm/internals.rst +++ b/doc/build/orm/internals.rst @@ -16,7 +16,6 @@ sections, are listed here. .. autoclass:: ClassManager :members: - :inherited-members: .. autoclass:: ColumnProperty :members: diff --git a/doc/build/orm/mapping_styles.rst b/doc/build/orm/mapping_styles.rst index 41afa768b..e1b2b78c8 100644 --- a/doc/build/orm/mapping_styles.rst +++ b/doc/build/orm/mapping_styles.rst @@ -189,7 +189,7 @@ Imperative Mapping with Dataclasses and Attrs --------------------------------------------- As described in the section :ref:`orm_declarative_dataclasses`, the -``@dataclass`` decorator and the attrs_ library both work as class +``@dataclass`` decorator and the ``attrs`` library both work as class decorators that are applied to a class first, before it is passed to SQLAlchemy for mapping. Just like we can use the :meth:`_orm.registry.mapped` decorator in order to apply declarative-style diff --git a/doc/build/orm/queryguide.rst b/doc/build/orm/queryguide.rst index f6b1eefae..f184c4c44 100644 --- a/doc/build/orm/queryguide.rst +++ b/doc/build/orm/queryguide.rst @@ -1101,8 +1101,8 @@ matching objects locally present in the :class:`_orm.Session`. See the section Inspecting entities and columns from ORM-enabled SELECT and DML statements ========================================================================== -The :func:`.select` construct, as well as the :func:`.insert`, :func:`.update` -and :func:`.delete` constructs (for the latter DML constructs, as of SQLAlchemy +The :func:`_sql.select` construct, as well as the :func:`_sql.insert`, :func:`_sql.update` +and :func:`_sql.delete` constructs (for the latter DML constructs, as of SQLAlchemy 1.4.33), all support the ability to inspect the entities in which these statements are created against, as well as the columns and datatypes that would be returned in a result set. @@ -1158,7 +1158,7 @@ cases:: this would raise ``NotImplementedError``. -For :func:`.insert`, :func:`.update` and :func:`.delete` constructs, there are +For :func:`_sql.insert`, :func:`.update` and :func:`.delete` constructs, there are two separate attributes. One is :attr:`.UpdateBase.entity_description` which returns information about the primary ORM entity and database table which the DML construct would be affecting:: diff --git a/doc/build/tutorial/data_update.rst b/doc/build/tutorial/data_update.rst index 8e88eb2f7..46236a6e9 100644 --- a/doc/build/tutorial/data_update.rst +++ b/doc/build/tutorial/data_update.rst @@ -174,6 +174,7 @@ order to refer to additional tables:: SET address.email_address=%s, user_account.fullname=%s WHERE user_account.id = address.user_id AND address.email_address = %s +.. _tutorial_parameter_ordered_updates: Parameter Ordered Updates ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/build/tutorial/index.rst b/doc/build/tutorial/index.rst index ecf45f5aa..cc5cb660c 100644 --- a/doc/build/tutorial/index.rst +++ b/doc/build/tutorial/index.rst @@ -141,8 +141,6 @@ verify that we are on **version 2.0** of SQLAlchemy: >>> sqlalchemy.__version__ # doctest: +SKIP 2.0.0 -.. rst-class:: core-header, orm-dependency - diff --git a/lib/sqlalchemy/dialects/postgresql/base.py b/lib/sqlalchemy/dialects/postgresql/base.py index c923f7014..987e36ed9 100644 --- a/lib/sqlalchemy/dialects/postgresql/base.py +++ b/lib/sqlalchemy/dialects/postgresql/base.py @@ -285,7 +285,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:`schema_table_reflection`. +: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 diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index 80e458e7c..b2bdd6a8d 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -87,22 +87,22 @@ NO_OPTIONS: Mapping[str, Any] = util.EMPTY_DICT class Connection(ConnectionEventsTarget, inspection.Inspectable["Inspector"]): """Provides high-level functionality for a wrapped DB-API connection. - The :class:`_engine.Connection` object is procured by calling - the :meth:`_engine.Engine.connect` method of the :class:`_engine.Engine` + The :class:`_engine.Connection` object is procured by calling the + :meth:`_engine.Engine.connect` method of the :class:`_engine.Engine` object, and provides services for execution of SQL statements as well as transaction control. - The Connection object is **not** thread-safe. While a Connection can be + The Connection object is **not** thread-safe. While a Connection can be shared among threads using properly synchronized access, it is still possible that the underlying DBAPI connection may not support shared - access between threads. Check the DBAPI documentation for details. + access between threads. Check the DBAPI documentation for details. The Connection object represents a single DBAPI connection checked out - from the connection pool. In this state, the connection pool has no affect - upon the connection, including its expiration or timeout state. For the - connection pool to properly manage connections, connections should be - returned to the connection pool (i.e. ``connection.close()``) whenever the - connection is not in use. + from the connection pool. In this state, the connection pool has no + affect upon the connection, including its expiration or timeout state. + For the connection pool to properly manage connections, connections + should be returned to the connection pool (i.e. ``connection.close()``) + whenever the connection is not in use. .. index:: single: thread safety; Connection @@ -2631,6 +2631,12 @@ class Engine( @property def engine(self) -> Engine: + """Returns this :class:`.Engine`. + + Used for legacy schemes that accept :class:`.Connection` / + :class:`.Engine` objects within the same variable. + + """ return self def clear_compiled_cache(self) -> None: diff --git a/lib/sqlalchemy/engine/cursor.py b/lib/sqlalchemy/engine/cursor.py index d5f0d8126..ec1e1abe1 100644 --- a/lib/sqlalchemy/engine/cursor.py +++ b/lib/sqlalchemy/engine/cursor.py @@ -7,7 +7,7 @@ # mypy: allow-untyped-defs, allow-untyped-calls """Define cursor-specific result set constructs including -:class:`.BaseCursorResult`, :class:`.CursorResult`.""" +:class:`.CursorResult`.""" from __future__ import annotations diff --git a/lib/sqlalchemy/ext/asyncio/session.py b/lib/sqlalchemy/ext/asyncio/session.py index f2a69e9cd..eac2e5806 100644 --- a/lib/sqlalchemy/ext/asyncio/session.py +++ b/lib/sqlalchemy/ext/asyncio/session.py @@ -747,8 +747,8 @@ class AsyncSession(ReversibleProxy[Session]): This method may also be used to establish execution options for the database connection used by the current transaction. - .. versionadded:: 1.4.24 Added **kw arguments which are passed through - to the underlying :meth:`_orm.Session.connection` method. + .. versionadded:: 1.4.24 Added \**kw arguments which are passed + through to the underlying :meth:`_orm.Session.connection` method. .. seealso:: diff --git a/lib/sqlalchemy/schema.py b/lib/sqlalchemy/schema.py index 86166f9f6..d16bf36b3 100644 --- a/lib/sqlalchemy/schema.py +++ b/lib/sqlalchemy/schema.py @@ -55,10 +55,12 @@ from .sql.schema import DefaultGenerator as DefaultGenerator from .sql.schema import FetchedValue as FetchedValue from .sql.schema import ForeignKey as ForeignKey from .sql.schema import ForeignKeyConstraint as ForeignKeyConstraint +from .sql.schema import HasConditionalDDL as HasConditionalDDL from .sql.schema import Identity as Identity from .sql.schema import Index as Index from .sql.schema import MetaData as MetaData from .sql.schema import PrimaryKeyConstraint as PrimaryKeyConstraint +from .sql.schema import SchemaConst as SchemaConst from .sql.schema import SchemaItem as SchemaItem from .sql.schema import Sequence as Sequence from .sql.schema import Table as Table diff --git a/lib/sqlalchemy/sql/schema.py b/lib/sqlalchemy/sql/schema.py index 472979952..598bacc59 100644 --- a/lib/sqlalchemy/sql/schema.py +++ b/lib/sqlalchemy/sql/schema.py @@ -1450,7 +1450,7 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause[_T]): value automatically for this column, which will be accessible after the statement is invoked via the :attr:`.CursorResult.inserted_primary_key` attribute upon the - :class:`.Result` object. This also applies towards use of the + :class:`_result.Result` object. This also applies towards use of the ORM when ORM-mapped objects are persisted to the database, indicating that a new integer primary key will be available to become part of the :term:`identity key` for that object. This @@ -1497,9 +1497,9 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause[_T]): Column('id', ForeignKey('other.id'), primary_key=True, autoincrement='ignore_fk') - It is typically not desirable to have "autoincrement" enabled on a - column that refers to another via foreign key, as such a column is - required to refer to a value that originates from elsewhere. + It is typically not desirable to have "autoincrement" enabled on a + column that refers to another via foreign key, as such a column is + required to refer to a value that originates from elsewhere. The setting has these effects on columns that meet the above criteria: @@ -1537,9 +1537,9 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause[_T]): using a method specific to the database driver in use: * MySQL, SQLite - calling upon ``cursor.lastrowid()`` - (see - `https://www.python.org/dev/peps/pep-0249/#lastrowid - <https://www.python.org/dev/peps/pep-0249/#lastrowid>`_) + (see + `https://www.python.org/dev/peps/pep-0249/#lastrowid + <https://www.python.org/dev/peps/pep-0249/#lastrowid>`_) * PostgreSQL, SQL Server, Oracle - use RETURNING or an equivalent construct when rendering an INSERT statement, and then retrieving the newly generated primary key values after execution @@ -1564,7 +1564,6 @@ class Column(DialectKWArgs, SchemaItem, ColumnClause[_T]): "fast insertmany" feature. Such features are very new and may not yet be well covered in documentation. - :param default: A scalar, Python callable, or :class:`_expression.ColumnElement` expression representing the *default value* for this column, which will be invoked upon insert diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py index fd98f17e3..733def377 100644 --- a/lib/sqlalchemy/sql/selectable.py +++ b/lib/sqlalchemy/sql/selectable.py @@ -1078,7 +1078,7 @@ class SelectLabelStyle(Enum): Below, all column names are given a label so that the two same-named columns ``columna`` are disambiguated as ``table1_columna`` and - ``table2_columna`:: + ``table2_columna``:: >>> from sqlalchemy import table, column, select, true, LABEL_STYLE_TABLENAME_PLUS_COL >>> table1 = table("table1", column("columna"), column("columnb")) diff --git a/lib/sqlalchemy/util/langhelpers.py b/lib/sqlalchemy/util/langhelpers.py index e54f33475..a23bee875 100644 --- a/lib/sqlalchemy/util/langhelpers.py +++ b/lib/sqlalchemy/util/langhelpers.py @@ -1225,7 +1225,11 @@ class HasMemoized: self._memoized_keys |= {key} class memoized_attribute(memoized_property[_T]): - """A read-only @property that is only evaluated once.""" + """A read-only @property that is only evaluated once. + + :meta private: + + """ fget: Callable[..., _T] __doc__: Optional[str] @@ -1254,7 +1258,11 @@ class HasMemoized: @classmethod def memoized_instancemethod(cls, fn: _F) -> _F: - """Decorate a method memoize its return value.""" + """Decorate a method memoize its return value. + + :meta private: + + """ def oneshot(self: Any, *args: Any, **kw: Any) -> Any: result = fn(self, *args, **kw) |