From: Mike Bayer Date: Wed, 22 Sep 2021 15:16:04 +0000 (-0400) Subject: changelog, doc edits X-Git-Tag: rel_1_4_24~1 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=9ed0d194bd7918a1e87cc8e02a55fcd8134de66d;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git changelog, doc edits Change-Id: Iafb50de7e28626d9cee755db9c05ac7189b4d963 --- diff --git a/doc/build/changelog/unreleased_14/4132.rst b/doc/build/changelog/unreleased_14/4123.rst similarity index 88% rename from doc/build/changelog/unreleased_14/4132.rst rename to doc/build/changelog/unreleased_14/4123.rst index bb0ed35291..cc2ad97689 100644 --- a/doc/build/changelog/unreleased_14/4132.rst +++ b/doc/build/changelog/unreleased_14/4123.rst @@ -2,7 +2,7 @@ :tags: usecase, sql :tickets: 4123 - Added new parameter :meth:`_sql.HasCte.cte.nesting` to the + Added new parameter :paramref:`_sql.HasCTE.cte.nesting` to the :class:`_sql.CTE` constructor and :meth:`_sql.HasCTE.cte` method, which flags the CTE as one which should remain nested within an enclosing CTE, rather than being moved to the top level of the outermost SELECT. While in diff --git a/doc/build/changelog/unreleased_14/6746.rst b/doc/build/changelog/unreleased_14/6746.rst index cff1a4ae94..f0fd1614ec 100644 --- a/doc/build/changelog/unreleased_14/6746.rst +++ b/doc/build/changelog/unreleased_14/6746.rst @@ -1,7 +1,7 @@ .. change:: - :tags: orm + :tags: asyncio, bug :tickets: 6746 - Deprecate usage of :class:`_orm.scoped_session` with asyncio drivers. - When using Asyncio the :class:`_asyncio.async_scoped_session` should - be used instead. + Deprecate usage of :class:`_orm.scoped_session` with asyncio drivers. When + using Asyncio the :class:`_asyncio.async_scoped_session` should be used + instead. diff --git a/doc/build/changelog/unreleased_14/6832.rst b/doc/build/changelog/unreleased_14/6832.rst index fcc5b6f6ef..22c50e2218 100644 --- a/doc/build/changelog/unreleased_14/6832.rst +++ b/doc/build/changelog/unreleased_14/6832.rst @@ -1,5 +1,5 @@ .. change:: - :tags: engine, asyncio + :tags: engine, asyncio, usecase :tickets: 6832 Improve the interface used by adapted drivers, like the asyncio ones, diff --git a/doc/build/changelog/unreleased_14/6913.rst b/doc/build/changelog/unreleased_14/6913.rst index 43ce34c218..0acad24ce4 100644 --- a/doc/build/changelog/unreleased_14/6913.rst +++ b/doc/build/changelog/unreleased_14/6913.rst @@ -3,7 +3,7 @@ :tickets: 6913 Fixed issue where the ability of the - :meth:`_engine.ConnectionEvents.before_execute` method to alter the SQL + :meth:`_events.ConnectionEvents.before_execute` method to alter the SQL statement object passed, returning the new object to be invoked, was inadvertently removed. This behavior has been restored. diff --git a/doc/build/changelog/unreleased_14/6955.rst b/doc/build/changelog/unreleased_14/6955.rst index 5896f3b4a4..c9ddbf12e5 100644 --- a/doc/build/changelog/unreleased_14/6955.rst +++ b/doc/build/changelog/unreleased_14/6955.rst @@ -3,7 +3,8 @@ :tickets: 6955 Added loader options to :meth:`_orm.Session.merge` and - :meth:`_asyncio.AsyncSession.merge`, which will apply the given loader - options to the ``get()`` used internally by merge, allowing eager loading - of relationships etc. to be applied when the merge process loads a new - object. Pull request courtesy Daniel Stone. + :meth:`_asyncio.AsyncSession.merge` via a new + :paramref:`_orm.Session.merge.options` parameter, which will apply the + given loader options to the ``get()`` used internally by merge, allowing + eager loading of relationships etc. to be applied when the merge process + loads a new object. Pull request courtesy Daniel Stone. diff --git a/doc/build/changelog/unreleased_14/6958.rst b/doc/build/changelog/unreleased_14/6958.rst index 61fd141310..1b9c8d0367 100644 --- a/doc/build/changelog/unreleased_14/6958.rst +++ b/doc/build/changelog/unreleased_14/6958.rst @@ -2,8 +2,9 @@ :tags: bug, engine :tickets: 6958 - Ensure that ``str()`` is called on the an ``URL.password`` argument, - allowing usage of objects that implement the ``__str__()`` method - as password attributes. - Also clarified that one such object is not appropriate to dynamically - change the password. + Ensure that ``str()`` is called on the an + :paramref:`_url.URL.create.password` argument, allowing usage of objects + that implement the ``__str__()`` method as password attributes. Also + clarified that one such object is not appropriate to dynamically change the + password for each database connection; the approaches at + :ref:`engines_dynamic_tokens` should be used instead. diff --git a/doc/build/changelog/unreleased_14/6963.rst b/doc/build/changelog/unreleased_14/6963.rst index 8b0473b169..130f741cb4 100644 --- a/doc/build/changelog/unreleased_14/6963.rst +++ b/doc/build/changelog/unreleased_14/6963.rst @@ -2,11 +2,12 @@ :tags: bug, engine, postgresql :tickets: 6963 - Fixed issue where an engine that had ``implicit_returning`` set to False - would fail to function when PostgreSQL's "fast insertmany" feature were - used in conjunction with a ``Sequence``, as well as if any kind of - "executemany" with "return_defaults()" were used in conjunction with a - ``Sequence``. Note that PostgreSQL "fast insertmany" uses "RETURNING" by - definition, when the SQL statement is passed to the driver; overall, the - ``implicit_returning`` flag is legacy and has no real use in modern - SQLAlchemy, and will be deprecated in a separate change. \ No newline at end of file + Fixed issue where an engine that had + :paramref:`_sa.create_engine.implicit_returning` set to False would fail to + function when PostgreSQL's "fast insertmany" feature were used in + conjunction with a ``Sequence``, as well as if any kind of "executemany" + with "return_defaults()" were used in conjunction with a ``Sequence``. Note + that PostgreSQL "fast insertmany" uses "RETURNING" by definition, when the + SQL statement is passed to the driver; overall, the + :paramref:`_sa.create_engine.implicit_returning` flag is legacy and has no + real use in modern SQLAlchemy, and will be deprecated in a separate change. \ No newline at end of file diff --git a/doc/build/changelog/unreleased_14/6983.rst b/doc/build/changelog/unreleased_14/6983.rst index 2aa31e8eba..ae69bdbaa6 100644 --- a/doc/build/changelog/unreleased_14/6983.rst +++ b/doc/build/changelog/unreleased_14/6983.rst @@ -2,5 +2,6 @@ :tags: bug, engine :tickets: 6983 - Fixed issue in ``URL`` where validation of "drivername" would not - appropriately respond to the ``None`` value where a string were expected. + Fixed issue in :class:`_engine.URL` where validation of "drivername" would + not appropriately respond to the ``None`` value where a string were + expected. diff --git a/doc/build/changelog/unreleased_14/7024.rst b/doc/build/changelog/unreleased_14/7024.rst index f0c44a0421..9f9e1b4fbe 100644 --- a/doc/build/changelog/unreleased_14/7024.rst +++ b/doc/build/changelog/unreleased_14/7024.rst @@ -1,5 +1,5 @@ .. change:: - :tags: bug, installation + :tags: bug, platform :tickets: 7024 Further adjusted the "greenlet" package specifier in setup.cfg to use a diff --git a/doc/build/changelog/unreleased_14/7036.rst b/doc/build/changelog/unreleased_14/7036.rst index f908206d02..69b6f8db86 100644 --- a/doc/build/changelog/unreleased_14/7036.rst +++ b/doc/build/changelog/unreleased_14/7036.rst @@ -2,6 +2,6 @@ :tags: bug, sql :tickets: 7036 - Fixed issue related to new ``add_cte()`` feature where pairing two - "INSERT..FROM SELECT" statements simultaneously would lose track of the two - independent SELECT statements, leading to the wrong SQL. + Fixed issue related to new :meth:`_sql.HasCTE.add_cte` feature where + pairing two "INSERT..FROM SELECT" statements simultaneously would lose + track of the two independent SELECT statements, leading to the wrong SQL. diff --git a/doc/build/changelog/unreleased_14/7052.rst b/doc/build/changelog/unreleased_14/7052.rst index 3c927c333b..748011b151 100644 --- a/doc/build/changelog/unreleased_14/7052.rst +++ b/doc/build/changelog/unreleased_14/7052.rst @@ -2,5 +2,6 @@ :tags: bug, sql :tickets: 7052 - Implemented a method in ``FunctionElement`` that is essentially abstract in - an ancestor class (even though not used), leading to pylint complaints. + Implemented missing methods in :class:`_functions.FunctionElement` which, + while unused, would lead pylint to report them as unimplemented abstract + methods. diff --git a/lib/sqlalchemy/engine/create.py b/lib/sqlalchemy/engine/create.py index f9dccb66ce..5e56ecdd9f 100644 --- a/lib/sqlalchemy/engine/create.py +++ b/lib/sqlalchemy/engine/create.py @@ -261,14 +261,18 @@ def create_engine(url, **kwargs): :ref:`dbengine_logging` - further detail on how to configure logging. - :param implicit_returning=True: When ``True``, a RETURNING- - compatible construct, if available, will be used to - fetch newly generated primary key values when a single row - INSERT statement is emitted with no existing returning() - clause. This applies to those backends which support RETURNING - or a compatible construct, including PostgreSQL, Firebird, Oracle, - Microsoft SQL Server. Set this to ``False`` to disable - the automatic usage of RETURNING. + :param implicit_returning=True: Legacy flag that when set to ``False`` + will disable the use of ``RETURNING`` on supporting backends where it + would normally be used to fetch newly generated primary key values for + single-row INSERT statements that do not otherwise specify a RETURNING + clause. This behavior applies primarily to the PostgreSQL, Oracle, + SQL Server backends. + + .. warning:: this flag originally allowed the "implicit returning" + feature to be *enabled* back when it was very new and there was not + well-established database support. In modern SQLAlchemy, this flag + should **always be set to True**. Some SQLAlchemy features will + fail to function properly if this flag is set to ``False``. :param isolation_level: this string parameter is interpreted by various dialects in order to affect the transaction isolation level of the