Deprecate FormatChecker.cls_checks.

It exposes fragile global state.

Closes: #519.

3 files changed, 36 insertions, 3 deletions

diff --git a/jsonschema/_format.py b/jsonschema/_format.py
index e9d91b6..ad8343b 100644
--- a/jsonschema/_format.py
+++ b/jsonschema/_format.py
@@ -6,6 +6,7 @@ import datetime
 import ipaddress
 import re
 import typing
+import warnings
 
 from jsonschema.exceptions import FormatError
 
@@ -85,6 +86,21 @@ class FormatChecker:
     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)
             return func
@@ -205,7 +221,7 @@ def _checks_drafts(
 
         # 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)
diff --git a/jsonschema/tests/test_deprecations.py b/jsonschema/tests/test_deprecations.py
index fcf7902..afa2658 100644
--- a/jsonschema/tests/test_deprecations.py
+++ b/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 TestDeprecations(TestCase):
         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 "),
+        )
diff --git a/jsonschema/tests/test_format.py b/jsonschema/tests/test_format.py
index f622265..5dd06cf 100644
--- a/jsonschema/tests/test_format.py
+++ b/jsonschema/tests/test_format.py
@@ -29,7 +29,8 @@ class TestFormatChecker(TestCase):
     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, ())),