Deprecate objects param of flush

The :paramref:`_orm.Session.flush.objects` parameter is now deprecated.

Fixes: #10816
Change-Id: I4a535e91aefa16774c2549ecec09113d6e669df4

diff --git a/doc/build/changelog/unreleased_21/10816.rst b/doc/build/changelog/unreleased_21/10816.rst
new file mode 100644 (file)
index 0000000..1b037bc
--- /dev/null
+++ b/doc/build/changelog/unreleased_21/10816.rst
@@ -0,0 +1,6 @@
+.. change::
+    :tags: usecase, orm
+    :tickets: 10816
+
+    The :paramref:`_orm.Session.flush.objects` parameter is now
+    deprecated.
\ No newline at end of file

diff --git a/lib/sqlalchemy/orm/scoping.py b/lib/sqlalchemy/orm/scoping.py
index 8a333401be7a134dda696139273a4b5383b71618..a53b1fecfeca2faf597a8c9ee5e3b158ff0417d5 100644 (file)
--- a/lib/sqlalchemy/orm/scoping.py
+++ b/lib/sqlalchemy/orm/scoping.py
@@ -937,6 +937,8 @@ class scoped_session(Generic[_S]):
           particular objects may need to be operated upon before the
           full flush() occurs.  It is not intended for general use.
 
+          .. deprecated:: 2.1
+
 
         """  # noqa: E501
 

diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index 28a32b3f23cc5a958db29730981dc768b6006d9d..48be64fc31771f01168457f0b1568628ab80c986 100644 (file)
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -89,6 +89,7 @@ from ..sql.base import CompileState
 from ..sql.schema import Table
 from ..sql.selectable import ForUpdateArg
 from ..sql.selectable import LABEL_STYLE_TABLENAME_PLUS_COL
+from ..util import deprecated_params
 from ..util import IdentitySet
 from ..util.typing import Literal
 from ..util.typing import TupleAny
@@ -4355,6 +4356,8 @@ class Session(_SessionClassMethods, EventTarget):
           particular objects may need to be operated upon before the
           full flush() occurs.  It is not intended for general use.
 
+          .. deprecated:: 2.1
+
         """
 
         if self._flushing:
@@ -4383,6 +4386,14 @@ class Session(_SessionClassMethods, EventTarget):
             and not self._new
         )
 
+    # have this here since it otherwise causes issues with the proxy
+    # method generation
+    @deprecated_params(
+        objects=(
+            "2.1",
+            "The `objects` parameter of `Session.flush` is deprecated",
+        )
+    )
     def _flush(self, objects: Optional[Sequence[object]] = None) -> None:
         dirty = self._dirty_states
         if not dirty and not self._deleted and not self._new:

diff --git a/lib/sqlalchemy/util/deprecations.py b/lib/sqlalchemy/util/deprecations.py
index 88b687240382ede48f8923814fe21dc3934a5993..0c7407959943bb5602b74d2d730123e1398b3c1f 100644 (file)
--- a/lib/sqlalchemy/util/deprecations.py
+++ b/lib/sqlalchemy/util/deprecations.py
@@ -280,7 +280,7 @@ def deprecated_params(**specs: Tuple[str, str]) -> Callable[[_F], _F]:
                     )
             return fn(*args, **kwargs)  # type: ignore[no-any-return]
 
-        doc = fn.__doc__ is not None and fn.__doc__ or ""
+        doc = fn.__doc__ if fn.__doc__ is not None else ""
         if doc:
             doc = inject_param_text(
                 doc,

diff --git a/test/orm/test_cascade.py b/test/orm/test_cascade.py
index fab8f5bb0c28185ccea305538823c811de113151..a7c326f730181c178ef8dd17084638c1d1ca6e67 100644 (file)
--- a/test/orm/test_cascade.py
+++ b/test/orm/test_cascade.py
@@ -29,6 +29,7 @@ from sqlalchemy.testing import eq_
 from sqlalchemy.testing import fixtures
 from sqlalchemy.testing import in_
 from sqlalchemy.testing import not_in
+from sqlalchemy.testing.assertions import uses_deprecated
 from sqlalchemy.testing.assertsql import CompiledSQL
 from sqlalchemy.testing.entities import ComparableEntity
 from sqlalchemy.testing.fixtures import fixture_session
@@ -4078,6 +4079,9 @@ class PartialFlushTest(fixtures.MappedTest):
             Column("parent_id", Integer, ForeignKey("parent.id")),
         )
 
+    @uses_deprecated(
+        "The `objects` parameter of `Session.flush` is deprecated"
+    )
     def test_o2m_m2o(self):
         base, noninh_child = self.tables.base, self.tables.noninh_child
 
@@ -4131,6 +4135,9 @@ class PartialFlushTest(fixtures.MappedTest):
         assert c2 in sess and c2 not in sess.new
         assert b1 in sess and b1 in sess.new
 
+    @uses_deprecated(
+        "The `objects` parameter of `Session.flush` is deprecated"
+    )
     def test_circular_sort(self):
         """test ticket 1306"""
 

diff --git a/test/orm/test_session.py b/test/orm/test_session.py
index 1495932744a5dc8d1b3eb6d80e2a46202b936a47..7efa284b2260b75a1d41bedf348a53bf6af2cc07 100644 (file)
--- a/test/orm/test_session.py
+++ b/test/orm/test_session.py
@@ -2120,7 +2120,10 @@ class SessionInterface(fixtures.MappedTest):
 
             s = fixture_session()
             s.add(OK())
-            x_raises_(s, "flush", objects=(user_arg,))
+            with assertions.expect_deprecated(
+                "The `objects` parameter of `Session.flush` is deprecated"
+            ):
+                x_raises_(s, "flush", objects=(user_arg,))
 
         _()