Add warn_deprecated_limited feature

Fixes: #5268
Change-Id: I2f976048af4f8d6dd03a14efa31d179bd7324ba6

diff --git a/lib/sqlalchemy/util/deprecations.py b/lib/sqlalchemy/util/deprecations.py
index 8ea8e8695c5f26ddb870073cfd0f4226f198dfe5..e0669c4e840ca04934098416208ab3d9b93c697a 100644 (file)
--- a/lib/sqlalchemy/util/deprecations.py
+++ b/lib/sqlalchemy/util/deprecations.py
@@ -12,6 +12,7 @@ import re
 import warnings
 
 from . import compat
+from .langhelpers import _hash_limit_string
 from .langhelpers import decorator
 from .langhelpers import inject_docstring_text
 from .langhelpers import inject_param_text
@@ -29,6 +30,16 @@ def warn_deprecated(msg, version, stacklevel=3):
     _warn_with_version(msg, version, exc.SADeprecationWarning, stacklevel)
 
 
+def warn_deprecated_limited(msg, args, version, stacklevel=3):
+    """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)
+
+
 def warn_deprecated_20(msg, stacklevel=3):
     msg += " (Background on SQLAlchemy 2.0 at: http://sqlalche.me/e/b8d9)"
 

diff --git a/test/base/test_warnings.py b/test/base/test_warnings.py
new file mode 100644 (file)
index 0000000..c8807df
--- /dev/null
+++ b/test/base/test_warnings.py
@@ -0,0 +1,36 @@
+from sqlalchemy.testing import eq_
+from sqlalchemy.testing import expect_deprecated
+from sqlalchemy.testing import fixtures
+from sqlalchemy.util.deprecations import warn_deprecated_limited
+from sqlalchemy.util.langhelpers import _hash_limit_string
+
+
+class WarnDeprecatedLimitedTest(fixtures.TestBase):
+    __backend__ = False
+
+    def test_warn_deprecated_limited_text(self):
+        with expect_deprecated("foo has been deprecated"):
+            warn_deprecated_limited(
+                "%s has been deprecated [%d]", ("foo", 1), "1.3"
+            )
+
+    def test_warn_deprecated_limited_cap(self):
+        """ warn_deprecated_limited() and warn_limited() use
+        _hash_limit_string
+
+        actually just verifying that _hash_limit_string works as expected
+        """
+        occurrences = 100
+        cap = 10
+
+        printouts = set()
+        messages = set()
+        for i in range(occurrences):
+            message = _hash_limit_string(
+                "this is a unique message: %d", cap, (i,)
+            )
+            printouts.add(str(message))
+            messages.add(message)
+
+        eq_(len(printouts), occurrences)
+        eq_(len(messages), cap)