From 755316e66e0543f2524aeef0f11c107f95420d8a Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Mon, 15 Mar 2021 10:15:48 -0400 Subject: [PATCH] documentation updates Change-Id: I43d0e8de1f90abcff4b278637808d1ebc8fd6c97 --- doc/build/changelog/unreleased_13/5919.rst | 1 + doc/build/changelog/unreleased_13/5929.rst | 1 + doc/build/changelog/unreleased_13/5952.rst | 3 ++- doc/build/changelog/unreleased_13/5983.rst | 1 + doc/build/changelog/unreleased_13/5989.rst | 8 +++++--- doc/build/changelog/unreleased_13/6001.rst | 1 + doc/build/changelog/unreleased_13/6007.rst | 1 + doc/build/changelog/unreleased_14/5953.rst | 6 +++++- doc/build/changelog/unreleased_14/6016.rst | 2 +- doc/build/changelog/unreleased_14/cte_str.rst | 4 ++-- lib/sqlalchemy/engine/base.py | 17 ++++++++++++----- lib/sqlalchemy/future/engine.py | 17 +++++++++++++---- 12 files changed, 45 insertions(+), 17 deletions(-) diff --git a/doc/build/changelog/unreleased_13/5919.rst b/doc/build/changelog/unreleased_13/5919.rst index ddae6c2b03..f56da617d2 100644 --- a/doc/build/changelog/unreleased_13/5919.rst +++ b/doc/build/changelog/unreleased_13/5919.rst @@ -1,6 +1,7 @@ .. change:: :tags: bug, schema :tickets: 5919 + :versions: 1.4.0 Repaired / implemented support for primary key constraint naming conventions that use column names/keys/etc as part of the convention. In diff --git a/doc/build/changelog/unreleased_13/5929.rst b/doc/build/changelog/unreleased_13/5929.rst index 9b9b6214c4..38bca63a22 100644 --- a/doc/build/changelog/unreleased_13/5929.rst +++ b/doc/build/changelog/unreleased_13/5929.rst @@ -1,6 +1,7 @@ .. change:: :tags: bug, engine :tickets: 5929 + :versions: 1.4.0 Fixed bug where the "schema_translate_map" feature failed to be taken into account for the use case of direct execution of diff --git a/doc/build/changelog/unreleased_13/5952.rst b/doc/build/changelog/unreleased_13/5952.rst index 7166e92675..8f70df710a 100644 --- a/doc/build/changelog/unreleased_13/5952.rst +++ b/doc/build/changelog/unreleased_13/5952.rst @@ -1,11 +1,12 @@ .. change:: :tags: bug, orm :tickets: 5952 + :versions: 1.4.0 Fixed issue where the process of joining two tables could fail if one of the tables had an unrelated, unresolvable foreign key constraint which would raise :class:`_exc.NoReferenceError` within the join process, which nonetheless could be bypassed to allow the join to complete. The logic - which tested the exception for signficance within the process would make + which tested the exception for significance within the process would make assumptions about the construct which would fail. diff --git a/doc/build/changelog/unreleased_13/5983.rst b/doc/build/changelog/unreleased_13/5983.rst index a5724ebe28..42b3f1adb6 100644 --- a/doc/build/changelog/unreleased_13/5983.rst +++ b/doc/build/changelog/unreleased_13/5983.rst @@ -1,6 +1,7 @@ .. change:: :tags: bug, orm :tickets: 5983 + :versions: 1.4.0 Removed very old warning that states that passive_deletes is not intended for many-to-one relationships. While it is likely that in many cases diff --git a/doc/build/changelog/unreleased_13/5989.rst b/doc/build/changelog/unreleased_13/5989.rst index cccf227fcd..018d56afe7 100644 --- a/doc/build/changelog/unreleased_13/5989.rst +++ b/doc/build/changelog/unreleased_13/5989.rst @@ -1,6 +1,8 @@ .. change:: - :tags: bug, orm, postgresql + :tags: bug, postgresql :tickets: 5989 + :versions: 1.4.0 - Fixed issue where using :class:`_ext.aggregate_order_by` would return - ARRAY(NullType) under certain conditions. + Fixed issue where using :class:`_postgresql.aggregate_order_by` would + return ARRAY(NullType) under certain conditions, interfering with + the ability of the result object to return data correctly. diff --git a/doc/build/changelog/unreleased_13/6001.rst b/doc/build/changelog/unreleased_13/6001.rst index 2b6f1bc093..728ce20a43 100644 --- a/doc/build/changelog/unreleased_13/6001.rst +++ b/doc/build/changelog/unreleased_13/6001.rst @@ -1,6 +1,7 @@ .. change:: :tags: bug, orm :tickets: 6001 + :versions: 1.4.0 Fixed issue where the :class:`_mutable.MutableComposite` construct could be placed into an invalid state when the parent object was already loaded, and diff --git a/doc/build/changelog/unreleased_13/6007.rst b/doc/build/changelog/unreleased_13/6007.rst index 6523ba8bd0..5b06e18b6b 100644 --- a/doc/build/changelog/unreleased_13/6007.rst +++ b/doc/build/changelog/unreleased_13/6007.rst @@ -1,6 +1,7 @@ .. change:: :tags: bug, sql, sqlite :tickets: 6007 + :versions: 1.4.0 Fixed issue where the CHECK constraint generated by :class:`_types.Boolean` or :class:`_types.Enum` would fail to render the naming convention diff --git a/doc/build/changelog/unreleased_14/5953.rst b/doc/build/changelog/unreleased_14/5953.rst index 9b559737ae..237df47b0c 100644 --- a/doc/build/changelog/unreleased_14/5953.rst +++ b/doc/build/changelog/unreleased_14/5953.rst @@ -3,4 +3,8 @@ :tickets: 5953 Deprecated all schema-level ``.copy()`` methods and renamed to - ``_copy()``. + ``_copy()``. These are not standard Python "copy()" methods as they + typically rely upon being instantiated within particular contexts + which are passed to the method as optional keyword arguments. The + :meth:`_schema.Table.tometadata` method is the public API that provides + copying for :class:`_schema.Table` objects. diff --git a/doc/build/changelog/unreleased_14/6016.rst b/doc/build/changelog/unreleased_14/6016.rst index 7dd7db7134..7214d3b357 100644 --- a/doc/build/changelog/unreleased_14/6016.rst +++ b/doc/build/changelog/unreleased_14/6016.rst @@ -4,7 +4,7 @@ Fixed bug where the "percent escaping" feature that occurs with dialects that use the "format" or "pyformat" bound parameter styles was not enabled - for the :meth:`.Operations.op` and :meth:`.Operations.custom_op` methods, + for the :meth:`_sql.Operators.op` and :class:`_sql.custom_op` constructs, for custom operators that use percent signs. The percent sign will now be automatically doubled based on the paramstyle as necessary. diff --git a/doc/build/changelog/unreleased_14/cte_str.rst b/doc/build/changelog/unreleased_14/cte_str.rst index 1dfaad27ec..3c82def30c 100644 --- a/doc/build/changelog/unreleased_14/cte_str.rst +++ b/doc/build/changelog/unreleased_14/cte_str.rst @@ -4,8 +4,8 @@ Altered the compilation for the :class:`.CTE` construct so that a string is returned representing the inner SELECT statement if the :class:`.CTE` is stringified directly, outside of the context of an enclosing SELECT; This - is the same behavior of :meth:`_FromClause.alias` and - :meth:`_SelectStatement.subquery`. Previously, a blank string would be + is the same behavior of :meth:`_sql.FromClause.alias` and + :meth:`_sql.Select.subquery`. Previously, a blank string would be returned as the CTE is normally placed above a SELECT after that SELECT has been generated, which is generally misleading when debugging. diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index 906de08bb4..a748270d0f 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -31,11 +31,14 @@ _EMPTY_EXECUTION_OPTS = util.immutabledict() class Connection(Connectable): """Provides high-level functionality for a wrapped DB-API connection. - Provides execution support for string-based SQL statements as well as - :class:`_expression.ClauseElement`, :class:`.Compiled` and - :class:`.DefaultGenerator` - objects. Provides a :meth:`begin` method to return :class:`.Transaction` - objects. + **This is the SQLAlchemy 1.x.x version** of the :class:`_engine.Connection` + class. For the :term:`2.0 style` version, which features some API + differences, see :class:`_future.Connection`. + + 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 shared among threads using properly synchronized access, it is still @@ -2581,6 +2584,10 @@ class Engine(Connectable, log.Identified): :class:`~sqlalchemy.engine.interfaces.Dialect` together to provide a source of database connectivity and behavior. + This is the **SQLAlchemy 1.x version** of :class:`_engine.Engine`. For + the :term:`2.0 style` version, which includes some API differences, + see :class:`_future.Engine`. + An :class:`_engine.Engine` object is instantiated publicly using the :func:`~sqlalchemy.create_engine` function. diff --git a/lib/sqlalchemy/future/engine.py b/lib/sqlalchemy/future/engine.py index bfdcdfc7f8..efd0b0eab9 100644 --- a/lib/sqlalchemy/future/engine.py +++ b/lib/sqlalchemy/future/engine.py @@ -24,13 +24,20 @@ def create_engine(*arg, **kw): class Connection(_LegacyConnection): """Provides high-level functionality for a wrapped DB-API connection. + The :class:`_future.Connection` object is procured by calling + the :meth:`_future.Engine.connect` method of the :class:`_future.Engine` + object, and provides services for execution of SQL statements as well + as transaction control. + **This is the SQLAlchemy 2.0 version** of the :class:`_engine.Connection` class. The API and behavior of this object is largely the same, with the following differences in behavior: - * The result object returned for results is the :class:`_engine.Result` - object. This object has a slightly different API and behavior than the - prior :class:`_engine.CursorResult` object. + * The result object returned for results is the + :class:`_engine.CursorResult` + object, which is a subclass of the :class:`_engine.Result`. + This object has a slightly different API and behavior than the + :class:`_engine.LegacyCursorResult` returned for 1.x style usage. * The object has :meth:`_future.Connection.commit` and :meth:`_future.Connection.rollback` methods which commit or roll back @@ -61,7 +68,9 @@ class Connection(_LegacyConnection): any special instructions for the SAVEPOINT (this will typically have the effect that one desires). - * There are no "nested" connections or transactions. + * The :class:`_future.Connection` object does not support "branching", + which was a pattern by which a sub "connection" would be used that + refers to this connection as a parent. -- 2.47.2