Update docs and HasDescriptionCode per review

Rename the mixin class and make a few changes to the docs. Notably,
put the '_error_s9r1' ReST ref in the errors doc. This requires a new
(small) section there to make sense.

diff --git a/doc/build/errors.rst b/doc/build/errors.rst
index 3bd7b7a5b80502e4cc2e7614a27bad345f0ca747..70ccb9db142932983e8ffa10c6431067b3a7fec0 100644 (file)
--- a/doc/build/errors.rst
+++ b/doc/build/errors.rst
@@ -172,6 +172,24 @@ In SQLAlchemy 1.4, this :term:`2.0 style` behavior is enabled when the
 :paramref:`_orm.Session.future` flag is set on :class:`_orm.sessionmaker`
 or :class:`_orm.Session`.
 
+.. _error_s9r1:
+
+Object is being merged into a Session along the backref cascade
+---------------------------------------------------------------
+
+Backref cascades are being removed in SQLAlchemy 2.0. This is a behavior in
+which ORM relationships add objects to the session in a potentially
+surprising way.
+
+To get the 2.0 behavior, set the :paramref:`_orm.relationship.cascade_backrefs` and
+:paramref:`_orm.backref.cascade_backrefs` parameters.
+:paramref:`_orm.relationship.backref` values should be updated from strings, if
+used, to :func:`~.sqlalchemy.orm.backref` function calls.
+
+For more details on the backref cascade, see the section
+:ref:`backref_cascade`. You can also read more about the deprecation and its
+rationale in the section :ref:`change_5150`.
+
 Connections and Transactions
 ============================
 

diff --git a/doc/build/orm/cascades.rst b/doc/build/orm/cascades.rst
index 716de0b6e3cdafaa8187fdd75ffe674e4442062d..bd428807d1a94d1eb84d8152ed241bf0779c1076 100644 (file)
--- a/doc/build/orm/cascades.rst
+++ b/doc/build/orm/cascades.rst
@@ -555,8 +555,6 @@ operation should be propagated down to referred objects.
 
 .. _backref_cascade:
 
-.. _error_s9r1:
-
 Controlling Cascade on Backrefs
 -------------------------------
 
@@ -605,9 +603,10 @@ option may be helpful for situations where an object needs to be kept out of a
 session until it's construction is completed, but still needs to be given
 associations to objects which are already persistent in the target session.
 
-When relationships are created by the ``backref`` parameter to
-``relationship()``, ``cascade_backrefs=False`` can be set by using the
-``backref()`` function instead of a string. For example, the above relationship
+When relationships are created by the :paramref:`_orm.relationship.backref`
+parameter on :func:`_orm.relationship`, the :paramref:`_orm.cascade_backrefs`
+parameter may be set to ``False`` on the backref side by using the
+:func:`_orm.backref` function instead of a string. For example, the above relationship
 could be declared::
 
     mapper_registry.map_imperatively(Order, order_table, properties={

diff --git a/lib/sqlalchemy/exc.py b/lib/sqlalchemy/exc.py
index 266294afa0ce6a202ef5154577016a3edcdc125f..55b1eb8a39784c822f78e80152fe39a7d9e5943e 100644 (file)
--- a/lib/sqlalchemy/exc.py
+++ b/lib/sqlalchemy/exc.py
@@ -19,7 +19,7 @@ from .util import compat
 _version_token = None
 
 
-class _CodeStrMixin(object):
+class HasDescriptionCode:
     """helper which adds 'code' as an attribute and '_code_str' as a method"""
 
     code = None
@@ -28,7 +28,7 @@ class _CodeStrMixin(object):
         code = kw.pop("code", None)
         if code is not None:
             self.code = code
-        super(_CodeStrMixin, self).__init__(*arg, **kw)
+        super(HasDescriptionCode, self).__init__(*arg, **kw)
 
     def _code_str(self):
         if not self.code:
@@ -44,7 +44,7 @@ class _CodeStrMixin(object):
             )
 
 
-class SQLAlchemyError(_CodeStrMixin, Exception):
+class SQLAlchemyError(HasDescriptionCode, Exception):
     """Generic error class."""
 
     def _message(self, as_unicode=compat.py3k):
@@ -654,7 +654,7 @@ class NotSupportedError(DatabaseError):
 # Warnings
 
 
-class SADeprecationWarning(_CodeStrMixin, DeprecationWarning):
+class SADeprecationWarning(HasDescriptionCode, DeprecationWarning):
     """Issued for usage of deprecated APIs."""
 
     deprecated_since = None