Raise NoSuchAnchor errors instead of KeyErrors.

Author: Julian

referencing/_core.py

@@ -368,7 +368,20 @@ def lookup(self, ref: URI) -> Resolved[D]:
 
             `exceptions.Unresolvable`
 
-                if the reference isn't resolvable
+                or a subclass thereof (see below) if the reference isn't
+                resolvable
+
+            `exceptions.NoSuchAnchor`
+
+                if the reference is to a URI where a resource exists but
+                contains a plain name fragment which does not exist within
+                the resource
+
+            `exceptions.PointerToNowhere`
+
+                if the reference is to a URI where a resource exists but
+                contains a JSON pointer to a location within the resource
+                that does not exist
         """
         if ref.startswith("#"):
             uri, fragment = self._base_uri, ref[1:]
@@ -393,7 +406,14 @@ def lookup(self, ref: URI) -> Resolved[D]:
             except LookupError:
                 registry = registry.crawl()
                 resolver = evolve(resolver, registry=registry)
-                anchor = registry.anchor(uri, fragment)
+                try:
+                    anchor = registry.anchor(uri, fragment)
+                except LookupError:
+                    raise exceptions.NoSuchAnchor(
+                        ref=ref,
+                        resource=resource,
+                        anchor=fragment,
+                    )
 
             return anchor.resolve(resolver=resolver)
 

referencing/exceptions.py

@@ -45,3 +45,18 @@ class PointerToNowhere(Unresolvable):
 
     def __str__(self):
         return f"{self.ref!r} does not exist within {self.resource.contents!r}"
+
+
+@frozen
+class NoSuchAnchor(Unresolvable):
+    """
+    An anchor does not exist within a particular resource.
+    """
+
+    resource: Any
+    anchor: str
+
+    def __str__(self):
+        return (
+            f"{self.anchor!r} does not exist within {self.resource.contents!r}"
+        )

referencing/tests/test_core.py

@@ -443,6 +443,21 @@ def test_lookup_non_existent_pointer_to_array_index(self):
             resource=resource,
         )
 
+    def test_lookup_non_existent_anchor(self):
+        root = ID_AND_CHILDREN.create_resource({"anchors": {}})
+        resolver = Registry().with_resource("urn:example", root).resolver()
+        resolved = resolver.lookup("urn:example")
+        assert resolved.contents == root.contents
+
+        ref = "urn:example#noSuchAnchor"
+        with pytest.raises(exceptions.Unresolvable) as e:
+            resolver.lookup(ref)
+        assert e.value == exceptions.NoSuchAnchor(
+            ref=ref,
+            resource=root,
+            anchor="noSuchAnchor",
+        )
+
     # FIXME: Ideally there'd be some way to represent the tests below in the
     #        referencing suite, but I can't think of ways to do so yet.