Deprecate :func:`.eagerload` and :func:`.relation`

The :func:`.eagerload` and :func:`.relation` were old
aliases and are now deprecated. Use :func:`.joinedload`
and :func:`.relationship` respectively.

Fixes: #5192
Change-Id: Ie13186e117e93e04a9c19d42fed4ef1af629b465

diff --git a/doc/build/changelog/unreleased_14/5192.rst b/doc/build/changelog/unreleased_14/5192.rst
new file mode 100644 (file)
index 0000000..cb8833b
--- /dev/null
+++ b/doc/build/changelog/unreleased_14/5192.rst
@@ -0,0 +1,8 @@
+.. change::
+    :tags: orm
+    :tickets: 5192
+
+    The :func:`.eagerload` and :func:`.relation` were old aliases and are
+    now deprecated. Use :func:`.joinedload` and :func:`.relationship`
+    respectively.
+

diff --git a/lib/sqlalchemy/orm/__init__.py b/lib/sqlalchemy/orm/__init__.py
index 307f55ad0a3f65c392696b7b8e20eec11e1197cb..8f6e3c21805c178ef87769168e94492581364588 100644 (file)
--- a/lib/sqlalchemy/orm/__init__.py
+++ b/lib/sqlalchemy/orm/__init__.py
@@ -97,6 +97,7 @@ def create_session(bind=None, **kwargs):
 relationship = public_factory(RelationshipProperty, ".orm.relationship")
 
 
+@_sa_util.deprecated_20("relation", "Please use :func:`.relationship`.")
 def relation(*arg, **kw):
     """A synonym for :func:`relationship`."""
 
@@ -254,6 +255,7 @@ defaultload = strategy_options.defaultload._unbound_fn
 selectin_polymorphic = strategy_options.selectin_polymorphic._unbound_fn
 
 
+@_sa_util.deprecated_20("relation", "Please use :func:`joinedload`.")
 def eagerload(*args, **kwargs):
     """A synonym for :func:`joinedload()`."""
     return joinedload(*args, **kwargs)

diff --git a/test/orm/test_deprecations.py b/test/orm/test_deprecations.py
index 1097af245c392a15e2d1805b71c0a6803f01156c..91b15d14a233c5f745c700957291ce50a29b4a5f 100644 (file)
--- a/test/orm/test_deprecations.py
+++ b/test/orm/test_deprecations.py
@@ -21,12 +21,14 @@ from sqlalchemy.orm import contains_eager
 from sqlalchemy.orm import create_session
 from sqlalchemy.orm import defer
 from sqlalchemy.orm import deferred
+from sqlalchemy.orm import eagerload
 from sqlalchemy.orm import foreign
 from sqlalchemy.orm import identity
 from sqlalchemy.orm import instrumentation
 from sqlalchemy.orm import joinedload
 from sqlalchemy.orm import mapper
 from sqlalchemy.orm import PropComparator
+from sqlalchemy.orm import relation
 from sqlalchemy.orm import relationship
 from sqlalchemy.orm import Session
 from sqlalchemy.orm import sessionmaker
@@ -2331,3 +2333,13 @@ class InstancesTest(QueryTest, AssertsCompiledSQL):
             assert self.static.user_order_result == result
 
         self.assert_sql_count(testing.db, go, 1)
+
+
+class TestDeprecation20(fixtures.TestBase):
+    def test_relation(self):
+        with testing.expect_deprecated_20(".*relationship"):
+            relation("foo")
+
+    def test_eagerloading(self):
+        with testing.expect_deprecated_20(".*joinedload"):
+            eagerload("foo")

diff --git a/test/orm/test_froms.py b/test/orm/test_froms.py
index 2425cd75629bd10e474ad4abdbe620990f1d101d..5ac4a15ec5d358af20af341406a75eaf5ad44ebd 100644 (file)
--- a/test/orm/test_froms.py
+++ b/test/orm/test_froms.py
@@ -28,7 +28,6 @@ from sqlalchemy.orm import contains_eager
 from sqlalchemy.orm import create_session
 from sqlalchemy.orm import joinedload
 from sqlalchemy.orm import mapper
-from sqlalchemy.orm import relation
 from sqlalchemy.orm import relationship
 from sqlalchemy.orm import Session
 from sqlalchemy.orm.util import join
@@ -791,7 +790,9 @@ class AddEntityEquivalenceTest(fixtures.MappedTest, AssertsCompiledSQL):
             polymorphic_identity="a",
             polymorphic_on=a.c.type,
             with_polymorphic=("*", None),
-            properties={"link": relation(B, uselist=False, backref="back")},
+            properties={
+                "link": relationship(B, uselist=False, backref="back")
+            },
         )
         mapper(
             B,

diff --git a/test/orm/test_relationships.py b/test/orm/test_relationships.py
index 53295c688d16fc7ea75b1ff38344c8fd7ec5e573..591ef41282a35d1ffaa3f323ce14c67589b05ba5 100644 (file)
--- a/test/orm/test_relationships.py
+++ b/test/orm/test_relationships.py
@@ -25,7 +25,6 @@ from sqlalchemy.orm import exc as orm_exc
 from sqlalchemy.orm import foreign
 from sqlalchemy.orm import joinedload
 from sqlalchemy.orm import mapper
-from sqlalchemy.orm import relation
 from sqlalchemy.orm import relationship
 from sqlalchemy.orm import remote
 from sqlalchemy.orm import selectinload
@@ -5580,7 +5579,7 @@ class RelationDeprecationTest(fixtures.MappedTest):
             ),
         )
 
-    def test_relation(self):
+    def test_relationship(self):
         addresses_table, User, users_table, Address = (
             self.tables.addresses_table,
             self.classes.User,
@@ -5591,7 +5590,7 @@ class RelationDeprecationTest(fixtures.MappedTest):
         mapper(
             User,
             users_table,
-            properties=dict(addresses=relation(Address, backref="user")),
+            properties=dict(addresses=relationship(Address, backref="user")),
         )
         mapper(Address, addresses_table)