From: Federico Caselli <cfederico87@gmail.com>
Date: Wed, 5 Feb 2025 21:38:08 +0000 (+0100)
Subject: Deprecate objects param of flush
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ea734ab5f6f6a8f00bb8a29fcb1e2b334c2e1876;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

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
index 0000000000..1b037bcb31
--- /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 8a333401be..a53b1fecfe 100644
--- 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 28a32b3f23..48be64fc31 100644
--- 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 88b6872403..0c74079599 100644
--- 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 fab8f5bb0c..a7c326f730 100644
--- 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 1495932744..7efa284b22 100644
--- 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,))
 
         _()