From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Wed, 3 Aug 2022 22:59:05 +0000 (-0400)
Subject: deprecate Query.instances()
X-Git-Tag: rel_2_0_0b1~131^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8032bfdcee30023aa2facf80be0d3627a8467149;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

deprecate Query.instances()

this method no longer does the thing that it was originally
intended to do, which is to get ORM results from arbitrary
result sets.   Modern patterns should supersede the
use of this construct.

Change-Id: Ia1656c84d7c323f55e3a9594b950a40763d63d90
References: #8347
---

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 99131e3e9a..374ae5cc8e 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -2783,6 +2783,13 @@ class Query(
 
         return _column_descriptions(self, legacy=True)
 
+    @util.deprecated(
+        "2.0",
+        "The :meth:`_orm.Query.instances` method is deprecated and will "
+        "be removed in a future release. "
+        "Use the Select.from_statement() method or aliased() construct in "
+        "conjunction with Session.execute() instead.",
+    )
     def instances(
         self,
         result_proxy: CursorResult[Any],
diff --git a/test/orm/test_deprecations.py b/test/orm/test_deprecations.py
index e419236f6d..b012009c88 100644
--- a/test/orm/test_deprecations.py
+++ b/test/orm/test_deprecations.py
@@ -1594,7 +1594,10 @@ class InstancesTest(QueryTest, AssertsCompiledSQL):
         # the statement where it would be able to create an adapter
         def go():
             with testing.expect_deprecated(
-                r"Using the Query.instances\(\) method without a context"
+                r"Using the Query.instances\(\) method without a context",
+                r"The Query.instances\(\) method is deprecated and will be "
+                r"removed in a future release.",
+                raise_on_any_unexpected=True,
             ):
                 result = list(
                     q.options(
@@ -1638,7 +1641,10 @@ class InstancesTest(QueryTest, AssertsCompiledSQL):
 
         def go():
             with testing.expect_deprecated(
-                r"Using the Query.instances\(\) method without a context"
+                r"Using the Query.instances\(\) method without a context",
+                r"The Query.instances\(\) method is deprecated and will be "
+                r"removed in a future release.",
+                raise_on_any_unexpected=True,
             ):
                 result = list(
                     q.options(
diff --git a/test/orm/test_options.py b/test/orm/test_options.py
index d6fadc449c..883a58292e 100644
--- a/test/orm/test_options.py
+++ b/test/orm/test_options.py
@@ -19,6 +19,7 @@ from sqlalchemy.orm import exc as orm_exc
 from sqlalchemy.orm import joinedload
 from sqlalchemy.orm import Load
 from sqlalchemy.orm import load_only
+from sqlalchemy.orm import loading
 from sqlalchemy.orm import relationship
 from sqlalchemy.orm import strategy_options
 from sqlalchemy.orm import subqueryload
@@ -1694,7 +1695,8 @@ class MapperOptionsTest(_fixtures.FixtureTest):
         ctx = sess.query(User)._compile_context()
 
         def go():
-            result = list(sess.query(User).instances(r, ctx))
+            result = loading.instances(r, ctx).scalars().unique()
+            result = list(result)
             eq_(result, self.static.user_address_result)
 
         self.sql_count_(4, go)
@@ -1793,7 +1795,8 @@ class MapperOptionsTest(_fixtures.FixtureTest):
         ctx = sess.query(User)._compile_context()
 
         def go():
-            result = list(sess.query(User).instances(r, ctx))
+            result = loading.instances(r, ctx).scalars().unique()
+            result = list(result)
             eq_(result, self.static.user_all_result)
 
         self.assert_sql_count(testing.db, go, 6)