move backref to "legacy"

in the interests of consistency as well as new typing features,
backref should be considered legacy and is fully superseded
by back_populates.

this commit is for 2.0 /1.4, in 2.0 further updates will be
made for new ORM syntaxes.

Change-Id: Idd3b7a3b07843b73304df69e476dc4239c60b3f8

1 files changed, 41 insertions, 26 deletions

diff --git a/lib/sqlalchemy/orm/_orm_constructors.py b/lib/sqlalchemy/orm/_orm_constructors.py
index bafad09f2..ea95f1420 100644
--- a/lib/sqlalchemy/orm/_orm_constructors.py
+++ b/lib/sqlalchemy/orm/_orm_constructors.py
@@ -978,41 +978,50 @@ def relationship(
       the "previous" value of the attribute.
 
     :param backref:
-      Indicates the string name of a property to be placed on the related
-      mapper's class that will handle this relationship in the other
-      direction. The other property will be created automatically
-      when the mappers are configured.  Can also be passed as a
-      :func:`.backref` object to control the configuration of the
-      new relationship.
+      A reference to a string relationship name, or a :func:`_orm.backref`
+      construct, which will be used to automatically generate a new
+      :func:`_orm.relationship` on the related class, which then refers to this
+      one using a bi-directional :paramref:`_orm.relationship.back_populates`
+      configuration.
+
+      In modern Python, explicit use of :func:`_orm.relationship`
+      with :paramref:`_orm.relationship.back_populates` should be preferred,
+      as it is more robust in terms of mapper configuration as well as
+      more conceptually straightforward.  It also integrates with
+      new :pep:`484` typing features introduced in SQLAlchemy 2.0 which
+      is not possible with dynamically generated attributes.
 
       .. seealso::
 
-        :ref:`relationships_backref` - Introductory documentation and
-        examples.
+        :ref:`relationships_backref` - notes on using
+        :paramref:`_orm.relationship.backref`
 
-        :paramref:`_orm.relationship.back_populates` - alternative form
-        of backref specification.
+        :ref:`tutorial_orm_related_objects` - in the :ref:`unified_tutorial`,
+        presents an overview of bi-directional relationship configuration
+        and behaviors using :paramref:`_orm.relationship.back_populates`
 
         :func:`.backref` - allows control over :func:`_orm.relationship`
         configuration when using :paramref:`_orm.relationship.backref`.
 
 
     :param back_populates:
-      Takes a string name and has the same meaning as
-      :paramref:`_orm.relationship.backref`, except the complementing
-      property is **not** created automatically, and instead must be
-      configured explicitly on the other mapper.  The complementing
-      property should also indicate
-      :paramref:`_orm.relationship.back_populates` to this relationship to
-      ensure proper functioning.
+      Indicates the name of a :func:`_orm.relationship` on the related
+      class that will be synchronized with this one.   It is usually
+      expected that the :func:`_orm.relationship` on the related class
+      also refer to this one.  This allows objects on both sides of
+      each :func:`_orm.relationship` to synchronize in-Python state
+      changes and also provides directives to the :term:`unit of work`
+      flush process how changes along these relationships should
+      be persisted.
 
       .. seealso::
 
-        :ref:`relationships_backref` - Introductory documentation and
-        examples.
+        :ref:`tutorial_orm_related_objects` - in the :ref:`unified_tutorial`,
+        presents an overview of bi-directional relationship configuration
+        and behaviors.
 
-        :paramref:`_orm.relationship.backref` - alternative form
-        of backref specification.
+        :ref:`relationship_patterns` - includes many examples of
+        :paramref:`_orm.relationship.back_populates`.
 
     :param overlaps:
        A string name or comma-delimited set of names of other relationships
@@ -1876,18 +1885,24 @@ def dynamic_loader(
 
 
 def backref(name: str, **kwargs: Any) -> _ORMBackrefArgument:
-    """Create a back reference with explicit keyword arguments, which are the
-    same arguments one can send to :func:`relationship`.
+    """When using the :paramref:`_orm.relationship.backref` parameter,
+    provides specific parameters to be used when the new
+    :func:`_orm.relationship` is generated.
 
-    Used with the ``backref`` keyword argument to :func:`relationship` in
-    place of a string argument, e.g.::
+    E.g.::
 
         'items':relationship(
             SomeItem, backref=backref('parent', lazy='subquery'))
 
+    The :paramref:`_orm.relationship.backref` parameter is generally
+    considered to be legacy; for modern applications, using
+    explicit :func:`_orm.relationship` constructs linked together using
+    the :paramref:`_orm.relationship.back_populates` parameter should be
+    preferred.
+
     .. seealso::
 
-        :ref:`relationships_backref`
+        :ref:`relationships_backref` - background on backrefs
 
     """