From 5bb0fdedfdd53e8430d47dbc5a41d131a27ff567 Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Thu, 15 Apr 2021 16:49:17 +0000 Subject: [PATCH] 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. --- doc/build/errors.rst | 18 ++++++++++++++++++ doc/build/orm/cascades.rst | 9 ++++----- lib/sqlalchemy/exc.py | 8 ++++---- 3 files changed, 26 insertions(+), 9 deletions(-) diff --git a/doc/build/errors.rst b/doc/build/errors.rst index 3bd7b7a5b8..70ccb9db14 100644 --- 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 716de0b6e3..bd428807d1 100644 --- 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 266294afa0..55b1eb8a39 100644 --- 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 -- 2.47.2