Give JSON pointer failed lookups slightly more specific errors.

Author: Julian

referencing/_core.py

@@ -8,8 +8,8 @@
 from pyrsistent import m, pmap, s
 from pyrsistent.typing import PMap, PSet
 
+from referencing import exceptions
 from referencing._attrs import frozen
-from referencing.exceptions import CannotDetermineSpecification, Unresolvable
 from referencing.typing import URI, D, Mapping
 
 
@@ -89,7 +89,7 @@ def from_contents(
                 )
 
         if specification is None:
-            raise CannotDetermineSpecification(contents)
+            raise exceptions.CannotDetermineSpecification(contents)
         return cls(contents=contents, specification=specification)  # type: ignore[reportUnknownArgumentType]  # noqa: E501
 
     @classmethod
@@ -122,14 +122,23 @@ def subresources(self) -> Iterable[Resource[D]]:
     def pointer(self, pointer: str, resolver: Resolver[D]) -> Resolved[D]:
         """
         Resolve the given JSON pointer.
+
+        Raises:
+
+            `exceptions.PointerToNowhere`
+
+                if the pointer points to a location not present in the document
         """
         contents = self.contents
         for segment in unquote(pointer[1:]).split("/"):
             if isinstance(contents, Sequence):
                 segment = int(segment)
             else:
                 segment = segment.replace("~1", "/").replace("~0", "~")
-            contents = contents[segment]  # type: ignore[reportUnknownArgumentType]  # noqa: E501
+            try:
+                contents = contents[segment]  # type: ignore[reportUnknownArgumentType]  # noqa: E501
+            except LookupError:
+                raise exceptions.PointerToNowhere(ref=pointer, resource=self)
         return Resolved(contents=contents, resolver=resolver)  # type: ignore[reportUnknownArgumentType]  # noqa: E501
 
 
@@ -295,21 +304,21 @@ def lookup(self, ref: URI) -> Resolved[D]:
 
         Raises:
 
-            `Unresolvable`
+            `exceptions.Unresolvable`
 
                 if the reference isn't resolvable
         """
         uri, fragment = urldefrag(urljoin(self._base_uri, ref))
         resolver, registry = self, self._registry
         resource = registry.get(uri)
-        try:
-            if resource is None:
-                registry = registry.crawl()
+        if resource is None:
+            registry = registry.crawl()
+            try:
                 resource = registry[uri]
-                resolver = evolve(resolver, registry=registry)
-            if fragment.startswith("/"):
-                return resource.pointer(pointer=fragment, resolver=resolver)
-        except KeyError:
-            raise Unresolvable(ref=ref) from None
+            except KeyError:
+                raise exceptions.Unresolvable(ref=ref) from None
+            resolver = evolve(resolver, registry=registry)
+        if fragment.startswith("/"):
+            return resource.pointer(pointer=fragment, resolver=resolver)
 
         return Resolved(contents=resource.contents, resolver=resolver)

referencing/exceptions.py

@@ -21,7 +21,7 @@ class CannotDetermineSpecification(Exception):
     contents: Any
 
 
-@frozen
+@attrs.frozen
 class Unresolvable(Exception):
     """
     A reference was unresolvable.
@@ -33,3 +33,12 @@ def __eq__(self, other: Any) -> bool:
         if self.__class__ is not other.__class__:
             return NotImplemented
         return attrs.astuple(self) == attrs.astuple(other)
+
+
+@frozen
+class PointerToNowhere(Unresolvable):
+    """
+    A JSON Pointer leads to a part of a document that does not exist.
+    """
+
+    resource: Any

referencing/tests/test_core.py

@@ -347,7 +347,21 @@ def test_lookup_non_existent_pointer(self):
         ref = "http://example.com/1#/foo/bar"
         with pytest.raises(exceptions.Unresolvable) as e:
             resolver.lookup(ref)
-        assert e.value == exceptions.Unresolvable(ref=ref)
+        assert e.value == exceptions.PointerToNowhere(
+            ref="/foo/bar",
+            resource=resource,
+        )
+
+    def test_lookup_non_existent_pointer_to_array_index(self):
+        resource = Resource.opaque([1, 2, 4, 8])
+        resolver = Registry({"http://example.com/1": resource}).resolver()
+        ref = "http://example.com/1#/10"
+        with pytest.raises(exceptions.Unresolvable) as e:
+            resolver.lookup(ref)
+        assert e.value == exceptions.PointerToNowhere(
+            ref="/10",
+            resource=resource,
+        )
 
 
 class TestSpecification: