Deprecate FormatChecker.cls_checks.

It exposes fragile global state.

Closes: #519.

Author: Julian

CHANGELOG.rst

@@ -1,3 +1,9 @@
+v4.14.0
+=======
+
+* ``FormatChecker.cls_checks`` is deprecated. Use ``FormatChecker.checks`` on
+  an instance of ``FormatChecker`` instead.
+
 v4.13.0
 =======
 

jsonschema/_format.py

@@ -6,6 +6,7 @@
 import ipaddress
 import re
 import typing
+import warnings
 
 from jsonschema.exceptions import FormatError
 
@@ -84,6 +85,21 @@ def _checks(func: _F) -> _F:
     @classmethod
     def cls_checks(
         cls, format: str, raises: _RaisesType = (),
+    ) -> typing.Callable[[_F], _F]:
+        warnings.warn(
+            (
+                "FormatChecker.cls_checks is deprecated. Call "
+                "FormatChecker.checks on a specific FormatChecker instance "
+                "instead."
+            ),
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return cls._cls_checks(format=format, raises=raises)
+
+    @classmethod
+    def _cls_checks(
+        cls, format: str, raises: _RaisesType = (),
     ) -> typing.Callable[[_F], _F]:
         def _checks(func: _F) -> _F:
             cls.checkers[format] = (func, raises)
@@ -205,7 +221,7 @@ def wrap(func: _F) -> _F:
 
         # Oy. This is bad global state, but relied upon for now, until
         # deprecation. See #519 and test_format_checkers_come_with_defaults
-        FormatChecker.cls_checks(
+        FormatChecker._cls_checks(
             draft202012 or draft201909 or draft7 or draft6 or draft4 or draft3,
             raises,
         )(func)

jsonschema/tests/test_deprecations.py

@@ -1,6 +1,6 @@
 from unittest import TestCase
 
-from jsonschema import validators
+from jsonschema import FormatChecker, validators
 
 
 class TestDeprecations(TestCase):
@@ -146,3 +146,19 @@ class Subclass(validators.Draft202012Validator):
         with self.assertWarns(DeprecationWarning) as w:
             class AnotherSubclass(validators.create(meta_schema={})):
                 pass
+
+    def test_FormatChecker_cls_checks(self):
+        """
+        As of v4.14.0, FormatChecker.cls_checks is deprecated without
+        replacement.
+        """
+
+        self.addCleanup(FormatChecker.checkers.pop, "boom", None)
+
+        with self.assertWarns(DeprecationWarning) as w:
+            FormatChecker.cls_checks("boom")
+
+        self.assertEqual(w.filename, __file__)
+        self.assertTrue(
+            str(w.warning).startswith("FormatChecker.cls_checks "),
+        )

jsonschema/tests/test_format.py

@@ -29,7 +29,8 @@ def test_it_raises_a_key_error_for_unknown_formats(self):
     def test_it_can_register_cls_checkers(self):
         original = dict(FormatChecker.checkers)
         self.addCleanup(FormatChecker.checkers.pop, "boom")
-        FormatChecker.cls_checks("boom")(boom)
+        with self.assertWarns(DeprecationWarning):
+            FormatChecker.cls_checks("boom")(boom)
         self.assertEqual(
             FormatChecker.checkers,
             dict(original, boom=(boom, ())),