Specify the argument name for retrieval callbacks via a protocol.

Author: Julian

referencing/_core.py

@@ -19,7 +19,7 @@
 
 from referencing import exceptions
 from referencing._attrs import frozen
-from referencing.typing import URI, Anchor as AnchorType, D, Mapping
+from referencing.typing import URI, Anchor as AnchorType, D, Mapping, Retrieve
 
 EMPTY_RESOURCES: PMap[URI, Resource[Any]] = pmap({}, pre_size=64)
 EMPTY_ANCHORS = cast(PMap[Tuple[URI, str], AnchorType[Any]], EMPTY_RESOURCES)
@@ -253,7 +253,7 @@ class Registry(Mapping[URI, Resource[D]]):
         default=EMPTY_ANCHORS,
     )
     _uncrawled: PSet[URI] = field(default=EMPTY_UNCRAWLED)
-    _retrieve: Callable[[URI], Resource[D]] = field(default=_fail_to_retrieve)
+    _retrieve: Retrieve[D] = field(default=_fail_to_retrieve)
 
     def __getitem__(self, uri: URI) -> Resource[D]:
         """
@@ -427,8 +427,8 @@ def combine(self, *registries: Registry[D]) -> Registry[D]:
             anchors = anchors.update(registry._anchors)  # type: ignore[reportUnknownMemberType]  # noqa: E501
             uncrawled = uncrawled.update(registry._uncrawled)
 
-            if registry._retrieve != _fail_to_retrieve:
-                if registry._retrieve != retrieve != _fail_to_retrieve:
+            if registry._retrieve is not _fail_to_retrieve:
+                if registry._retrieve is not retrieve is not _fail_to_retrieve:
                     raise ValueError(
                         "Cannot combine registries with conflicting retrieval "
                         "functions.",

referencing/typing.py

@@ -14,7 +14,7 @@
 
 
 if TYPE_CHECKING:
-    from referencing._core import Resolved, Resolver
+    from referencing._core import Resolved, Resolver, Resource
 
 #: A URI which identifies a `Resource`.
 URI = str
@@ -23,6 +23,23 @@
 D = TypeVar("D")
 
 
+class Retrieve(Protocol[D]):
+    """
+    A retrieval callable, usable within a `Registry` for resource retrieval.
+
+    Does not make assumptions about where the resource might be coming from.
+    """
+
+    def __call__(self, uri: URI) -> Resource[D]:
+        """
+        Retrieve the resource with the given URI.
+
+        Raise `referencing.exceptions.NoSuchResource` if you wish to indicate
+        the retriever cannot lookup the given URI.
+        """
+        ...
+
+
 class Anchor(Protocol[D]):
     """
     An anchor within a `Resource`.