Deprecate jsonschema.validators.validators and .meta_schemas.

Besides having confusing names, these expose mutable global state in
a way that makes maintenance hard.

Today, jsonschema.validators.validator_for(schema) can be used
to look up an appropriate Validator given an arbitrary schema.

4 files changed, 72 insertions, 26 deletions

diff --git a/jsonschema/tests/_suite.py b/jsonschema/tests/_suite.py
index 8d36490..870304d 100644
--- a/jsonschema/tests/_suite.py
+++ b/jsonschema/tests/_suite.py
@@ -13,7 +13,7 @@ import unittest
 
 import attr
 
-from jsonschema.validators import validators
+from jsonschema.validators import _VALIDATORS
 import jsonschema
 
 
@@ -51,10 +51,10 @@ class Suite(object):
         }
 
     def benchmark(self, runner):  # pragma: no cover
-        for name in validators:
+        for name, Validator in _VALIDATORS.items():
             self.version(name=name).benchmark(
                 runner=runner,
-                Validator=validators[name],
+                Validator=Validator,
             )
 
     def version(self, name):
diff --git a/jsonschema/tests/test_deprecations.py b/jsonschema/tests/test_deprecations.py
index c1f4c21..e7163b9 100644
--- a/jsonschema/tests/test_deprecations.py
+++ b/jsonschema/tests/test_deprecations.py
@@ -1,6 +1,6 @@
 from unittest import TestCase
 
-from jsonschema.validators import Draft7Validator, RefResolver
+from jsonschema import validators
 
 
 class TestDeprecations(TestCase):
@@ -33,12 +33,44 @@ class TestDeprecations(TestCase):
             ),
         )
 
+    def test_validators_validators(self):
+        """
+        As of v4.0.0, accessing jsonschema.validators.validators is
+        deprecated.
+        """
+
+        with self.assertWarns(DeprecationWarning) as w:
+            value = validators.validators
+        self.assertEqual(value, validators._VALIDATORS)
+
+        self.assertTrue(
+            str(w.warning).startswith(
+                "Accessing jsonschema.validators.validators is deprecated",
+            ),
+        )
+
+    def test_validators_meta_schemas(self):
+        """
+        As of v4.0.0, accessing jsonschema.validators.meta_schemas is
+        deprecated.
+        """
+
+        with self.assertWarns(DeprecationWarning) as w:
+            value = validators.meta_schemas
+        self.assertEqual(value, validators._META_SCHEMAS)
+
+        self.assertTrue(
+            str(w.warning).startswith(
+                "Accessing jsonschema.validators.meta_schemas is deprecated",
+            ),
+        )
+
     def test_RefResolver_in_scope(self):
         """
         As of v4.0.0, RefResolver.in_scope is deprecated.
         """
 
-        resolver = RefResolver.from_schema({})
+        resolver = validators.RefResolver.from_schema({})
         with self.assertWarns(DeprecationWarning) as w:
             with resolver.in_scope("foo"):
                 pass
@@ -55,7 +87,7 @@ class TestDeprecations(TestCase):
         different schema) is deprecated.
         """
 
-        validator = Draft7Validator({})
+        validator = validators.Draft7Validator({})
         with self.assertWarns(DeprecationWarning) as w:
             result = validator.is_valid("foo", {"type": "number"})
 
@@ -72,7 +104,7 @@ class TestDeprecations(TestCase):
         different schema) is deprecated.
         """
 
-        validator = Draft7Validator({})
+        validator = validators.Draft7Validator({})
         with self.assertWarns(DeprecationWarning) as w:
             error, = validator.iter_errors("foo", {"type": "number"})
 
diff --git a/jsonschema/tests/test_validators.py b/jsonschema/tests/test_validators.py
index 4ea1b16..5fabff9 100644
--- a/jsonschema/tests/test_validators.py
+++ b/jsonschema/tests/test_validators.py
@@ -27,8 +27,8 @@ class TestCreateAndExtend(SynchronousTestCase):
     def setUp(self):
         self.addCleanup(
             self.assertEqual,
-            validators.meta_schemas,
-            dict(validators.meta_schemas),
+            validators._META_SCHEMAS,
+            dict(validators._META_SCHEMAS),
         )
 
         self.meta_schema = {"$id": "some://meta/schema"}
@@ -99,7 +99,7 @@ class TestCreateAndExtend(SynchronousTestCase):
             meta_schema={"$id": "something"},
             version="my version",
         )
-        self.addCleanup(validators.meta_schemas.pop, "something")
+        self.addCleanup(validators._META_SCHEMAS.pop, "something")
         self.assertEqual(Validator.__name__, "MyVersionValidator")
         self.assertEqual(Validator.__qualname__, "MyVersionValidator")
 
@@ -108,7 +108,7 @@ class TestCreateAndExtend(SynchronousTestCase):
             meta_schema={"$id": "something"},
             version="my version",
         )
-        self.addCleanup(validators.meta_schemas.pop, "something")
+        self.addCleanup(validators._META_SCHEMAS.pop, "something")
         self.assertEqual(
             repr(Validator({})),
             "MyVersionValidator(schema={}, format_checker=None)",
@@ -119,7 +119,7 @@ class TestCreateAndExtend(SynchronousTestCase):
             meta_schema={"$id": "something"},
             version="my version",
         )
-        self.addCleanup(validators.meta_schemas.pop, "something")
+        self.addCleanup(validators._META_SCHEMAS.pop, "something")
         self.assertEqual(
             repr(Validator({"a": list(range(1000))})), (
                 "MyVersionValidator(schema={'a': [0, 1, 2, 3, 4, 5, ...]}, "
@@ -139,13 +139,13 @@ class TestCreateAndExtend(SynchronousTestCase):
             meta_schema={"$id": "something"},
             version="foo-bar",
         )
-        self.addCleanup(validators.meta_schemas.pop, "something")
+        self.addCleanup(validators._META_SCHEMAS.pop, "something")
         self.assertEqual(Validator.__qualname__, "FooBarValidator")
 
     def test_if_a_version_is_not_provided_it_is_not_registered(self):
-        original = dict(validators.meta_schemas)
+        original = dict(validators._META_SCHEMAS)
         validators.create(meta_schema={"id": "id"})
-        self.assertEqual(validators.meta_schemas, original)
+        self.assertEqual(validators._META_SCHEMAS, original)
 
     def test_validates_registers_meta_schema_id(self):
         meta_schema_key = "meta schema id"
@@ -156,9 +156,9 @@ class TestCreateAndExtend(SynchronousTestCase):
             version="my version",
             id_of=lambda s: s.get("id", ""),
         )
-        self.addCleanup(validators.meta_schemas.pop, meta_schema_key)
+        self.addCleanup(validators._META_SCHEMAS.pop, meta_schema_key)
 
-        self.assertIn(meta_schema_key, validators.meta_schemas)
+        self.assertIn(meta_schema_key, validators._META_SCHEMAS)
 
     def test_validates_registers_meta_schema_draft6_id(self):
         meta_schema_key = "meta schema $id"
@@ -168,9 +168,9 @@ class TestCreateAndExtend(SynchronousTestCase):
             meta_schema=my_meta_schema,
             version="my version",
         )
-        self.addCleanup(validators.meta_schemas.pop, meta_schema_key)
+        self.addCleanup(validators._META_SCHEMAS.pop, meta_schema_key)
 
-        self.assertIn(meta_schema_key, validators.meta_schemas)
+        self.assertIn(meta_schema_key, validators._META_SCHEMAS)
 
     def test_create_default_types(self):
         Validator = validators.create(meta_schema={}, validators=())
diff --git a/jsonschema/validators.py b/jsonschema/validators.py
index 7a5424e..c35e7ef 100644
--- a/jsonschema/validators.py
+++ b/jsonschema/validators.py
@@ -22,8 +22,8 @@ from jsonschema import (
     exceptions,
 )
 
-validators = {}
-meta_schemas = _utils.URIDict()
+_VALIDATORS = {}
+_META_SCHEMAS = _utils.URIDict()
 _VOCABULARIES = _utils.URIDict()
 
 
@@ -36,6 +36,20 @@ def __getattr__(name):
         )
         from jsonschema.exceptions import ErrorTree
         return ErrorTree
+    elif name == "validators":
+        warnings.warn(
+            "Accessing jsonschema.validators.validators is deprecated. "
+            "Use jsonschema.validators.validator_for with a given schema.",
+            DeprecationWarning,
+        )
+        return _VALIDATORS
+    elif name == "meta_schemas":
+        warnings.warn(
+            "Accessing jsonschema.validators.meta_schemas is deprecated. "
+            "Use jsonschema.validators.validator_for with a given schema.",
+            DeprecationWarning,
+        )
+        return _META_SCHEMAS
     raise AttributeError(f"module {__name__} has no attribute {name}")
 
 
@@ -60,9 +74,9 @@ def validates(version):
     """
 
     def _validates(cls):
-        validators[version] = cls
+        _VALIDATORS[version] = cls
         meta_schema_id = cls.ID_OF(cls.META_SCHEMA)
-        meta_schemas[meta_schema_id] = cls
+        _META_SCHEMAS[meta_schema_id] = cls
 
         for vocabulary in cls.VOCABULARY_SCHEMAS:
             vocabulary_id = cls.ID_OF(vocabulary)
@@ -80,7 +94,7 @@ def _id_of(schema):
 
 def _store_schema_list():
     return [
-        (id, validator.META_SCHEMA) for id, validator in meta_schemas.items()
+        (id, validator.META_SCHEMA) for id, validator in _META_SCHEMAS.items()
     ] + [
         (id, schema) for id, schema in _VOCABULARIES.items()
     ]
@@ -982,7 +996,7 @@ def validator_for(schema, default=_LATEST_VERSION):
     """
     if schema is True or schema is False or "$schema" not in schema:
         return default
-    if schema["$schema"] not in meta_schemas:
+    if schema["$schema"] not in _META_SCHEMAS:
         warn(
             (
                 "The metaschema specified by $schema was not found. "
@@ -992,4 +1006,4 @@ def validator_for(schema, default=_LATEST_VERSION):
             DeprecationWarning,
             stacklevel=2,
         )
-    return meta_schemas.get(schema["$schema"], _LATEST_VERSION)
+    return _META_SCHEMAS.get(schema["$schema"], _LATEST_VERSION)