Deprecate jsonschema.RefResolver from both places it is importable.

Internal uses of it will be removed, replaced with referencing's
resolution APIs, though RefResolver will continue to function during
its deprecation period.

7 files changed, 53 insertions, 26 deletions

diff --git a/jsonschema/__init__.py b/jsonschema/__init__.py
index 6628fc7..8f6b0a4 100644
--- a/jsonschema/__init__.py
+++ b/jsonschema/__init__.py
@@ -27,7 +27,6 @@ from jsonschema.validators import (
     Draft7Validator,
     Draft201909Validator,
     Draft202012Validator,
-    RefResolver,
     validate,
 )
 
@@ -48,6 +47,14 @@ def __getattr__(name):
             import importlib_metadata as metadata
 
         return metadata.version("jsonschema")
+    elif name == "RefResolver":
+        from jsonschema.validators import _RefResolver
+        warnings.warn(
+            _RefResolver._DEPRECATION_MESSAGE,
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return _RefResolver
 
     format_checkers = {
         "draft3_format_checker": Draft3Validator,
diff --git a/jsonschema/cli.py b/jsonschema/cli.py
index 1292b1a..d6b9ad9 100644
--- a/jsonschema/cli.py
+++ b/jsonschema/cli.py
@@ -23,7 +23,7 @@ except ImportError:
 import attr
 
 from jsonschema.exceptions import SchemaError
-from jsonschema.validators import RefResolver, validator_for
+from jsonschema.validators import _RefResolver, validator_for
 
 warnings.warn(
     (
@@ -277,7 +277,7 @@ def run(arguments, stdout=sys.stdout, stderr=sys.stderr, stdin=sys.stdin):
                 raise _CannotLoadFile()
         instances = ["<stdin>"]
 
-    resolver = RefResolver(
+    resolver = _RefResolver(
         base_uri=arguments["base_uri"],
         referrer=schema,
     ) if arguments["base_uri"] is not None else None
diff --git a/jsonschema/protocols.py b/jsonschema/protocols.py
index 5f52166..c9c71dc 100644
--- a/jsonschema/protocols.py
+++ b/jsonschema/protocols.py
@@ -108,7 +108,7 @@ class Validator(Protocol):
     def __init__(
         self,
         schema: Mapping | bool,
-        resolver: jsonschema.validators.RefResolver | None = None,
+        resolver: jsonschema.validators._RefResolver | None = None,
         format_checker: jsonschema.FormatChecker | None = None,
     ) -> None:
         ...
diff --git a/jsonschema/tests/_suite.py b/jsonschema/tests/_suite.py
index c598e22..d425e40 100644
--- a/jsonschema/tests/_suite.py
+++ b/jsonschema/tests/_suite.py
@@ -19,7 +19,7 @@ from attrs import field, frozen
 if TYPE_CHECKING:
     import pyperf
 
-from jsonschema.validators import _VALIDATORS
+from jsonschema.validators import _VALIDATORS, _RefResolver
 import jsonschema
 
 _DELIMITERS = re.compile(r"[\W\- ]+")
@@ -218,7 +218,7 @@ class _Test:
 
     def validate(self, Validator, **kwargs):
         Validator.check_schema(self.schema)
-        resolver = jsonschema.RefResolver.from_schema(
+        resolver = _RefResolver.from_schema(
             schema=self.schema,
             store=self._remotes,
             id_of=Validator.ID_OF,
diff --git a/jsonschema/tests/test_deprecations.py b/jsonschema/tests/test_deprecations.py
index 3e8a9cc..898a792 100644
--- a/jsonschema/tests/test_deprecations.py
+++ b/jsonschema/tests/test_deprecations.py
@@ -77,7 +77,7 @@ class TestDeprecations(TestCase):
         As of v4.0.0, RefResolver.in_scope is deprecated.
         """
 
-        resolver = validators.RefResolver.from_schema({})
+        resolver = validators._RefResolver.from_schema({})
         with self.assertWarns(DeprecationWarning) as w:
             with resolver.in_scope("foo"):
                 pass
diff --git a/jsonschema/tests/test_validators.py b/jsonschema/tests/test_validators.py
index 0bc60de..6e37f7b 100644
--- a/jsonschema/tests/test_validators.py
+++ b/jsonschema/tests/test_validators.py
@@ -1189,7 +1189,7 @@ class TestValidationErrorDetails(TestCase):
         ref, schema = "someRef", {"additionalProperties": {"type": "integer"}}
         validator = validators.Draft7Validator(
             {"$ref": ref},
-            resolver=validators.RefResolver("", {}, store={ref: schema}),
+            resolver=validators._RefResolver("", {}, store={ref: schema}),
         )
         error, = validator.iter_errors({"foo": "notAnInteger"})
 
@@ -1542,12 +1542,12 @@ class ValidatorTestMixin(MetaSchemaTestsMixin, object):
     def test_it_creates_a_ref_resolver_if_not_provided(self):
         self.assertIsInstance(
             self.Validator({}).resolver,
-            validators.RefResolver,
+            validators._RefResolver,
         )
 
     def test_it_delegates_to_a_ref_resolver(self):
         ref, schema = "someCoolRef", {"type": "integer"}
-        resolver = validators.RefResolver("", {}, store={ref: schema})
+        resolver = validators._RefResolver("", {}, store={ref: schema})
         validator = self.Validator({"$ref": ref}, resolver=resolver)
 
         with self.assertRaises(exceptions.ValidationError):
@@ -1555,7 +1555,7 @@ class ValidatorTestMixin(MetaSchemaTestsMixin, object):
 
     def test_evolve(self):
         ref, schema = "someCoolRef", {"type": "integer"}
-        resolver = validators.RefResolver("", {}, store={ref: schema})
+        resolver = validators._RefResolver("", {}, store={ref: schema})
 
         validator = self.Validator(schema, resolver=resolver)
         new = validator.evolve(schema={"type": "string"})
@@ -1784,14 +1784,14 @@ class AntiDraft6LeakMixin:
 
     @unittest.skip(bug(523))
     def test_True_is_not_a_schema_even_if_you_forget_to_check(self):
-        resolver = validators.RefResolver("", {})
+        resolver = validators._RefResolver("", {})
         with self.assertRaises(Exception) as e:
             self.Validator(True, resolver=resolver).validate(12)
         self.assertNotIsInstance(e.exception, exceptions.ValidationError)
 
     @unittest.skip(bug(523))
     def test_False_is_not_a_schema_even_if_you_forget_to_check(self):
-        resolver = validators.RefResolver("", {})
+        resolver = validators._RefResolver("", {})
         with self.assertRaises(Exception) as e:
             self.Validator(False, resolver=resolver).validate(12)
         self.assertNotIsInstance(e.exception, exceptions.ValidationError)
@@ -1867,7 +1867,7 @@ class TestLatestValidator(TestCase):
     def test_ref_resolvers_may_have_boolean_schemas_stored(self):
         ref = "someCoolRef"
         schema = {"$ref": ref}
-        resolver = validators.RefResolver("", {}, store={ref: False})
+        resolver = validators._RefResolver("", {}, store={ref: False})
         validator = validators._LATEST_VERSION(schema, resolver=resolver)
 
         with self.assertRaises(exceptions.ValidationError):
@@ -2123,7 +2123,7 @@ class TestRefResolver(TestCase):
     def setUp(self):
         self.referrer = {}
         self.store = {self.stored_uri: self.stored_schema}
-        self.resolver = validators.RefResolver(
+        self.resolver = validators._RefResolver(
             self.base_uri, self.referrer, self.store,
         )
 
@@ -2143,7 +2143,7 @@ class TestRefResolver(TestCase):
 
     def test_it_resolves_local_refs_with_id(self):
         schema = {"id": "http://bar/schema#", "a": {"foo": "bar"}}
-        resolver = validators.RefResolver.from_schema(
+        resolver = validators._RefResolver.from_schema(
             schema,
             id_of=lambda schema: schema.get("id", ""),
         )
@@ -2206,7 +2206,7 @@ class TestRefResolver(TestCase):
 
     def test_it_can_construct_a_base_uri_from_a_schema(self):
         schema = {"id": "foo"}
-        resolver = validators.RefResolver.from_schema(
+        resolver = validators._RefResolver.from_schema(
             schema,
             id_of=lambda schema: schema.get("id", ""),
         )
@@ -2223,7 +2223,7 @@ class TestRefResolver(TestCase):
 
     def test_it_can_construct_a_base_uri_from_a_schema_without_id(self):
         schema = {}
-        resolver = validators.RefResolver.from_schema(schema)
+        resolver = validators._RefResolver.from_schema(schema)
         self.assertEqual(resolver.base_uri, "")
         self.assertEqual(resolver.resolution_scope, "")
         with resolver.resolving("") as resolved:
@@ -2238,7 +2238,7 @@ class TestRefResolver(TestCase):
 
         schema = {"foo": "bar"}
         ref = "foo://bar"
-        resolver = validators.RefResolver("", {}, handlers={"foo": handler})
+        resolver = validators._RefResolver("", {}, handlers={"foo": handler})
         with resolver.resolving(ref) as resolved:
             self.assertEqual(resolved, schema)
 
@@ -2252,7 +2252,7 @@ class TestRefResolver(TestCase):
                 self.fail("Response must not have been cached!")
 
         ref = "foo://bar"
-        resolver = validators.RefResolver(
+        resolver = validators._RefResolver(
             "", {}, cache_remote=True, handlers={"foo": handler},
         )
         with resolver.resolving(ref):
@@ -2270,7 +2270,7 @@ class TestRefResolver(TestCase):
                 self.fail("Handler called twice!")
 
         ref = "foo://bar"
-        resolver = validators.RefResolver(
+        resolver = validators._RefResolver(
             "", {}, cache_remote=False, handlers={"foo": handler},
         )
         with resolver.resolving(ref):
@@ -2283,14 +2283,14 @@ class TestRefResolver(TestCase):
             raise error
 
         ref = "foo://bar"
-        resolver = validators.RefResolver("", {}, handlers={"foo": handler})
+        resolver = validators._RefResolver("", {}, handlers={"foo": handler})
         with self.assertRaises(exceptions.RefResolutionError) as err:
             with resolver.resolving(ref):
                 self.fail("Shouldn't get this far!")  # pragma: no cover
         self.assertEqual(err.exception, exceptions.RefResolutionError(error))
 
     def test_helpful_error_message_on_failed_pop_scope(self):
-        resolver = validators.RefResolver("", {})
+        resolver = validators._RefResolver("", {})
         resolver.pop_scope()
         with self.assertRaises(exceptions.RefResolutionError) as exc:
             resolver.pop_scope()
diff --git a/jsonschema/validators.py b/jsonschema/validators.py
index a976959..83864bc 100644
--- a/jsonschema/validators.py
+++ b/jsonschema/validators.py
@@ -61,6 +61,13 @@ def __getattr__(name):
             stacklevel=2,
         )
         return _META_SCHEMAS
+    elif name == "RefResolver":
+        warnings.warn(
+            _RefResolver._DEPRECATION_MESSAGE,
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return _RefResolver
     raise AttributeError(f"module {__name__} has no attribute {name}")
 
 
@@ -209,7 +216,7 @@ def create(
 
         def __attrs_post_init__(self):
             if self.resolver is None:
-                self.resolver = RefResolver.from_schema(
+                self.resolver = _RefResolver.from_schema(
                     self.schema,
                     id_of=id_of,
                 )
@@ -684,7 +691,7 @@ Draft202012Validator = create(
 _LATEST_VERSION = Draft202012Validator
 
 
-class RefResolver:
+class _RefResolver:
     """
     Resolve JSON References.
 
@@ -726,8 +733,21 @@ class RefResolver:
         cache_remote (bool):
 
             Whether remote refs should be cached after first resolution
+
+    .. deprecated:: v4.18.0
+
+        `RefResolver` has been deprecated in favor of `referencing`.
     """
 
+    _DEPRECATION_MESSAGE = (
+        "jsonschema.RefResolver is deprecated as of v4.18.0, in favor of the "
+        "https://github.com/python-jsonschema/referencing library, which "
+        "provides more compliant referencing behavior as well as more "
+        "flexible APIs for customization. A future release will remove "
+        "RefResolver. Please file a feature request (on referencing) if you "
+        "are missing an API for the kind of customization you need."
+    )
+
     def __init__(
         self,
         base_uri,
@@ -774,7 +794,7 @@ class RefResolver:
 
         Returns:
 
-            `RefResolver`
+            `_RefResolver`
         """
 
         return cls(base_uri=id_of(schema), referrer=schema, *args, **kwargs)  # noqa: B026, E501