From 71e368081a63b323bea092b379523d8cd0ab3fdb Mon Sep 17 00:00:00 2001
From: Federico Caselli <cfederico87@gmail.com>
Date: Tue, 10 Mar 2020 19:33:51 +0100
Subject: [PATCH] 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
---
 doc/build/changelog/unreleased_14/5192.rst |  8 ++++++++
 lib/sqlalchemy/orm/__init__.py             |  2 ++
 test/orm/test_deprecations.py              | 12 ++++++++++++
 test/orm/test_froms.py                     |  5 +++--
 test/orm/test_relationships.py             |  5 ++---
 5 files changed, 27 insertions(+), 5 deletions(-)
 create mode 100644 doc/build/changelog/unreleased_14/5192.rst

diff --git a/doc/build/changelog/unreleased_14/5192.rst b/doc/build/changelog/unreleased_14/5192.rst
new file mode 100644
index 0000000000..cb8833b5db
--- /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 307f55ad0a..8f6e3c2180 100644
--- 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 1097af245c..91b15d14a2 100644
--- 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 2425cd7562..5ac4a15ec5 100644
--- 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 53295c688d..591ef41282 100644
--- 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)
 
-- 
2.47.3