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 99131e3e9a7afdb114ebdab180ae2b9e1feae777..374ae5cc8e0fc222308f5b111256760ef41b5278 100644 (file)
--- 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 e419236f6dc569581c6d08665b09e8beb031afb7..b012009c88feb43bea02398e2a73790d608ab358 100644 (file)
--- 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 d6fadc449cd73262dfecf44a74c9891ce8011908..883a58292eab35dea247720cc526c61353578981 100644 (file)
--- 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)