Improve cascade backrefs warning and add `code` to deprecation warnings

This adds a new description to errors.rst and adds support
for any SQLAlchemy warning to refer to an errors.rst code.

Fixes: #6148
Closes: #6250
Pull-request: https://github.com/sqlalchemy/sqlalchemy/pull/6250
Pull-request-sha: dbcaeb54e31517fe88f6f8c515f1024002675f13

Change-Id: I4303c62ac9b1f13f67a34f825687014f1771c98c

2 files changed, 16 insertions, 16 deletions

diff --git a/lib/sqlalchemy/util/deprecations.py b/lib/sqlalchemy/util/deprecations.py
index 19c55aa33..425a5f044 100644
--- a/lib/sqlalchemy/util/deprecations.py
+++ b/lib/sqlalchemy/util/deprecations.py
@@ -26,42 +26,42 @@ if os.getenv("SQLALCHEMY_WARN_20", "false").lower() in ("true", "yes", "1"):
     SQLALCHEMY_WARN_20 = True
 
 
-def _warn_with_version(msg, version, type_, stacklevel):
-    is_20 = issubclass(type_, exc.RemovedIn20Warning)
-
-    if is_20 and not SQLALCHEMY_WARN_20:
+def _warn_with_version(msg, version, type_, stacklevel, code=None):
+    if issubclass(type_, exc.RemovedIn20Warning) and not SQLALCHEMY_WARN_20:
         return
 
-    if is_20:
-        msg += " (Background on SQLAlchemy 2.0 at: http://sqlalche.me/e/b8d9)"
-
-    warn = type_(msg)
+    warn = type_(msg, code=code)
     warn.deprecated_since = version
 
     _warnings_warn(warn, stacklevel=stacklevel + 1)
 
 
-def warn_deprecated(msg, version, stacklevel=3):
-    _warn_with_version(msg, version, exc.SADeprecationWarning, stacklevel)
+def warn_deprecated(msg, version, stacklevel=3, code=None):
+    _warn_with_version(
+        msg, version, exc.SADeprecationWarning, stacklevel, code=code
+    )
 
 
-def warn_deprecated_limited(msg, args, version, stacklevel=3):
+def warn_deprecated_limited(msg, args, version, stacklevel=3, code=None):
     """Issue a deprecation warning with a parameterized string,
     limiting the number of registrations.
 
     """
     if args:
         msg = _hash_limit_string(msg, 10, args)
-    _warn_with_version(msg, version, exc.SADeprecationWarning, stacklevel)
+    _warn_with_version(
+        msg, version, exc.SADeprecationWarning, stacklevel, code=code
+    )
 
 
-def warn_deprecated_20(msg, stacklevel=3):
+def warn_deprecated_20(msg, stacklevel=3, code=None):
 
     _warn_with_version(
         msg,
         exc.RemovedIn20Warning.deprecated_since,
         exc.RemovedIn20Warning,
         stacklevel,
+        code=code,
     )
 
 
diff --git a/lib/sqlalchemy/util/langhelpers.py b/lib/sqlalchemy/util/langhelpers.py
index c5ca76f01..7796d4106 100644
--- a/lib/sqlalchemy/util/langhelpers.py
+++ b/lib/sqlalchemy/util/langhelpers.py
@@ -1616,9 +1616,9 @@ def warn(msg, code=None):
 
     """
     if code:
-        msg = "%s %s" % (msg, exc.SQLAlchemyError(msg, code=code)._code_str())
-
-    _warnings_warn(msg, exc.SAWarning)
+        _warnings_warn(exc.SAWarning(msg, code=code))
+    else:
+        _warnings_warn(msg, exc.SAWarning)
 
 
 def warn_limited(msg, args):