Enable the type annotation linter.

Specifically because Sphinx doesn't render return types
without them present.

Author: Julian

docs/api.rst

@@ -13,6 +13,14 @@ API Reference
    :undoc-members:
 
 
+.. autoclass:: referencing._core.Retrieved
+   :members:
+   :undoc-members:
+
+
+.. autoclass:: referencing._core.T
+
+
 .. autoclass:: referencing._core.Resolver
    :members:
    :undoc-members:

docs/spelling-wordlist.txt

@@ -9,6 +9,7 @@ discoverability
 filesystem
 instantiable
 instantiation
+iterable
 metaschemas
 referenceable
 resolvers

pyproject.toml

@@ -70,8 +70,15 @@ exclude = [
 [tool.ruff]
 line-length = 79
 target-version = "py38"
-select = ["B", "D", "E", "F", "Q", "UP", "W"]
+select = ["ANN", "B", "D", "E", "F", "Q", "UP", "W"]
 ignore = [
+  # Wat, type annotations for self and cls, why is this a thing?
+  "ANN101",
+  "ANN102",
+  # Private annotations are fine to leave out.
+  "ANN202",
+  # I don't know how to more properly annotate "pass along all arguments".
+  "ANN401",
   # raise SomeException(...) is fine.
   "B904",
   # It's fine to not have docstrings for magic methods.
@@ -97,9 +104,9 @@ extend-exclude = ["suite"]
 docstring-quotes = "double"
 
 [tool.ruff.per-file-ignores]
-"docs/*" = ["D"]
-"referencing/tests/*" = ["D"]
-"noxfile.py" = ["D"]
+"docs/*" = ["ANN", "D"]
+"referencing/tests/*" = ["ANN", "D"]
+"noxfile.py" = ["ANN", "D"]
 
 [tool.ruff.pyupgrade]
 # We support 3.8 + 3.9

referencing/_core.py

@@ -58,7 +58,7 @@ class Specification(Generic[D]):
     #: nor internal identifiers.
     OPAQUE: ClassVar[Specification[Any]]
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<Specification name={self.name!r}>"
 
     def anchors_in(self, contents: D):
@@ -257,7 +257,10 @@ def __len__(self) -> int:
         """
         return len(self._resources)
 
-    def __rmatmul__(self, new: Resource[D] | Iterable[Resource[D]]):
+    def __rmatmul__(
+        self,
+        new: Resource[D] | Iterable[Resource[D]],
+    ) -> Registry[D]:
         """
         Create a new registry with resource(s) added using their internal IDs.
 
@@ -311,7 +314,7 @@ def __repr__(self) -> str:
             summary = f"{pluralized}"
         return f"<Registry ({size} {summary})>"
 
-    def get_or_retrieve(self, uri: URI) -> Retrieved:
+    def get_or_retrieve(self, uri: URI) -> Retrieved[D, Resource[D]]:
         """
         Get a resource from the registry, crawling or retrieving if necessary.
 
@@ -498,6 +501,7 @@ def resolver_with_root(self, resource: Resource[D]) -> Resolver[D]:
         )
 
 
+#: An anchor or resource.
 T = TypeVar("T", AnchorType[Any], Resource[Any])
 
 

referencing/exceptions.py

@@ -93,7 +93,7 @@ class PointerToNowhere(Unresolvable):
 
     resource: Resource[Any]
 
-    def __str__(self):
+    def __str__(self) -> str:
         msg = f"{self.ref!r} does not exist within {self.resource.contents!r}"
         if self.ref == "/":
             msg += (
@@ -113,7 +113,7 @@ class NoSuchAnchor(Unresolvable):
     resource: Resource[Any]
     anchor: str
 
-    def __str__(self):
+    def __str__(self) -> str:
         return (
             f"{self.anchor!r} does not exist within {self.resource.contents!r}"
         )
@@ -130,7 +130,7 @@ class InvalidAnchor(Unresolvable):
     resource: Resource[Any]
     anchor: str
 
-    def __str__(self):
+    def __str__(self) -> str:
         return (
             f"'#{self.anchor}' is not a valid anchor, neither as a "
             "plain name anchor nor as a JSON Pointer. You may have intended "

referencing/jsonschema.py

@@ -586,7 +586,7 @@ class DynamicAnchor:
     name: str
     resource: Resource[Schema]
 
-    def resolve(self, resolver: _Resolver[Schema]):
+    def resolve(self, resolver: _Resolver[Schema]) -> _Resolved[Schema]:
         """
         Resolve this anchor dynamically.
         """