Deprecate strings indicating attribute names

Using strings to represent relationship names in ORM operations such as
:meth:`_orm.Query.join`, as well as strings for all ORM attribute names
in loader options like :func:`_orm.selectinload`
is deprecated and will be removed in SQLAlchemy 2.0.  The class-bound
attribute should be passed instead.  This provides much better specificity
to the given method, allows for modifiers such as ``of_type()``, and
reduces internal complexity.

Additionally, the ``aliased`` and ``from_joinpoint`` parameters to
:meth:`_orm.Query.join` are also deprecated.   The :func:`_orm.aliased`
construct now provides for a great deal of flexibility and capability
and should be used directly.

Fixes: #4705
Fixes: #5202
Change-Id: I32f61663d68026154906932913c288f269991adc

1 files changed, 36 insertions, 2 deletions

diff --git a/lib/sqlalchemy/sql/coercions.py b/lib/sqlalchemy/sql/coercions.py
index 558ced8bd..9b3acf5ad 100644
--- a/lib/sqlalchemy/sql/coercions.py
+++ b/lib/sqlalchemy/sql/coercions.py
@@ -352,7 +352,7 @@ class _CoerceLiterals(object):
             if self._coerce_star and element == "*":
                 return elements.ColumnClause("*", is_literal=True)
             else:
-                return self._text_coercion(element, argname)
+                return self._text_coercion(element, argname, **kw)
 
         if self._coerce_consts:
             if element is None:
@@ -528,6 +528,32 @@ class OnClauseImpl(_CoerceLiterals, _ColumnCoercions, RoleImpl):
 
     _coerce_consts = True
 
+    def _implicit_coercions(
+        self, original_element, resolved, argname=None, legacy=False, **kw
+    ):
+        if legacy and isinstance(resolved, str):
+            return resolved
+        else:
+            return super(OnClauseImpl, self)._implicit_coercions(
+                original_element,
+                resolved,
+                argname=argname,
+                legacy=legacy,
+                **kw
+            )
+
+    def _text_coercion(self, element, argname=None, legacy=False):
+        if legacy and isinstance(element, str):
+            util.warn_deprecated_20(
+                "Using strings to indicate relationship names in "
+                "Query.join() is deprecated and will be removed in "
+                "SQLAlchemy 2.0.  Please use the class-bound attribute "
+                "directly."
+            )
+            return element
+
+        return super(OnClauseImpl, self)._text_coercion(element, argname)
+
     def _post_coercion(self, resolved, original_element=None, **kw):
         # this is a hack right now as we want to use coercion on an
         # ORM InstrumentedAttribute, but we want to return the object
@@ -802,7 +828,15 @@ class JoinTargetImpl(RoleImpl):
     ):
         if isinstance(original_element, roles.JoinTargetRole):
             return original_element
-        elif legacy and isinstance(resolved, (str, roles.WhereHavingRole)):
+        elif legacy and isinstance(resolved, str):
+            util.warn_deprecated_20(
+                "Using strings to indicate relationship names in "
+                "Query.join() is deprecated and will be removed in "
+                "SQLAlchemy 2.0.  Please use the class-bound attribute "
+                "directly."
+            )
+            return resolved
+        elif legacy and isinstance(resolved, roles.WhereHavingRole):
             return resolved
         elif legacy and resolved._is_select_statement:
             util.warn_deprecated(