feat: type-check-only dtype protocol

Co-authored-by: NeilGirdhar
Signed-off-by: Nathaniel Starkman <[email protected]>

Author: nstarman

pyproject.toml

@@ -133,9 +133,11 @@ version_tuple = {version_tuple!r}
       "D107",   # Missing docstring in __init__
       "D203",   # 1 blank line required before class docstring
       "D213",   # Multi-line docstring summary should start at the second line
+      "D401",  # First line of docstring should be in imperative mood
       "FBT",    # flake8-boolean-trap
       "FIX",    # flake8-fixme
       "ISC001", # Conflicts with formatter
+      "PLW1641", # Object does not implement `__hash__` method
     ]
 
     [tool.ruff.lint.per-file-ignores]

src/array_api_typing/_misc.py

@@ -0,0 +1,21 @@
+__all__ = ("DType",)
+
+from typing import Protocol, type_check_only
+
+
+@type_check_only
+class DType(Protocol):
+    """Protocol for classes that represent a data type.
+
+    This `typing.Protocol` is `typing.type_check_only` and cannot be used at
+    runtime.  This limitation is intentional since the array API structurally
+    defines a ``dtype`` object as anything with an ``__eq__`` method that
+    compares to another ``dtype`` object. This broad definition means that most
+    Python objects will satisfy this protocol and can be erroneously considered
+    a ``dtype``.
+
+    """
+
+    def __eq__(self, other: object, /) -> bool:
+        """Computes the truth value of ``self == other`` in order to test for data type object equality."""  # noqa: E501
+        ...