Do more silly things to pepper over type checking nonsense.

See python/typing#689 and PEP 661 which look related.

But really I still want my plugin that lets me separate between public
API types and private API types.

Author: Julian

docs/api.rst

@@ -39,6 +39,12 @@ Plainly then, you may rely on their methods and attributes not changing in backw
    :members:
    :undoc-members:
 
+.. class:: referencing._core._Unset
+
+   A sentinel object used internally to satisfy the type checker.
+
+   Neither accessing nor explicitly passing this object anywhere is public API, and it is only documented here at all to get Sphinx to not complain.
+
 
 Submodules
 ----------

docs/changes.rst

@@ -2,6 +2,11 @@
 Changelog
 =========
 
+v0.31.1
+-------
+
+* No user facing changes.
+
 v0.31.0
 -------
 

referencing/_core.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Iterable, Iterator, Sequence
+from enum import Enum
 from typing import Any, Callable, ClassVar, Generic, Protocol, TypeVar
 from urllib.parse import unquote, urldefrag, urljoin
 
@@ -15,6 +16,17 @@
 EMPTY_PREVIOUS_RESOLVERS: List[URI] = List()
 
 
+class _Unset(Enum):
+    """
+    What sillyness...
+    """
+
+    SENTINEL = 1
+
+
+_UNSET = _Unset.SENTINEL
+
+
 class _MaybeInSubresource(Protocol[D]):
     def __call__(
         self,
@@ -101,7 +113,7 @@ class Resource(Generic[D]):
     def from_contents(
         cls,
         contents: D,
-        default_specification: Specification[D] = None,  # type: ignore[reportGeneralTypeIssues]
+        default_specification: Specification[D] | _Unset = _UNSET,
     ) -> Resource[D]:
         """
         Attempt to discern which specification applies to the given contents.
@@ -125,7 +137,7 @@ def from_contents(
                     default=default_specification,
                 )
 
-        if specification is None:  # type: ignore[reportUnnecessaryComparison]
+        if specification is _UNSET:
             raise exceptions.CannotDetermineSpecification(contents)
         return cls(contents=contents, specification=specification)  # type: ignore[reportUnknownArgumentType]
 

referencing/jsonschema.py

@@ -9,6 +9,8 @@
 
 from referencing import Anchor, Registry, Resource, Specification, exceptions
 from referencing._attrs import frozen
+from referencing._core import _UNSET  # type: ignore[reportPrivateUsage]
+from referencing._core import _Unset  # type: ignore[reportPrivateUsage]
 from referencing._core import Resolved as _Resolved, Resolver as _Resolver
 from referencing.typing import URI, Anchor as AnchorType, Mapping
 
@@ -559,7 +561,7 @@ def maybe_in_subresource(
 
 def specification_with(
     dialect_id: URI,
-    default: Specification[Any] = None,  # type: ignore[reportGeneralTypeIssues]
+    default: Specification[Any] | _Unset = _UNSET,
 ) -> Specification[Any]:
     """
     Retrieve the `Specification` with the given dialect identifier.
@@ -573,7 +575,7 @@ def specification_with(
     resource = _SPECIFICATIONS.get(dialect_id.rstrip("#"))
     if resource is not None:
         return resource.contents
-    if default is None:  # type: ignore[reportUnnecessaryComparison]
+    if default is _UNSET:
         raise UnknownDialect(dialect_id)
     return default