✨ HasMatrixTranspose

Signed-off-by: nstarman <[email protected]>

Author: nstarman

src/array_api_typing/__init__.py

@@ -5,6 +5,7 @@
     "HasArrayNamespace",
     "HasDType",
     "HasDevice",
+    "HasMatrixTranspose",
     "__version__",
     "__version_tuple__",
 )
@@ -14,5 +15,6 @@
     HasArrayNamespace,
     HasDevice,
     HasDType,
+    HasMatrixTranspose,
 )
 from ._version import version as __version__, version_tuple as __version_tuple__

src/array_api_typing/_array.py

@@ -3,10 +3,11 @@
     "HasArrayNamespace",
     "HasDType",
     "HasDevice",
+    "HasMatrixTranspose",
 )
 
 from types import ModuleType
-from typing import Literal, Protocol
+from typing import Literal, Protocol, Self
 from typing_extensions import TypeVar
 
 NamespaceT_co = TypeVar("NamespaceT_co", covariant=True, default=ModuleType)
@@ -78,6 +79,27 @@ def device(self) -> object:  # TODO: more specific type
         ...
 
 
+class HasMatrixTranspose(Protocol):
+    """Protocol for array classes that have a matrix transpose attribute."""
+
+    @property
+    def mT(self) -> Self:  # noqa: N802
+        """Transpose of a matrix (or a stack of matrices).
+
+        If an array instance has fewer than two dimensions, an error should be
+        raised.
+
+        Returns:
+            Self: array whose last two dimensions (axes) are permuted in reverse
+                order relative to original array (i.e., for an array instance
+                having shape `(..., M, N)`, the returned array must have shape
+                `(..., N, M))`.  The returned array must have the same data type
+                as the original array.
+
+        """
+        ...
+
+
 class Array(
     # ------ Attributes -------
     HasDType[DTypeT_co],

tests/integration/test_numpy1p0.pyi

@@ -46,6 +46,13 @@ _: xpt.HasDevice = nparr
 _: xpt.HasDevice = nparr_i32
 _: xpt.HasDevice = nparr_f32
 
+# =========================================================
+# `xpt.HasMatrixTranspose`
+
+_: xpt.HasMatrixTranspose = nparr
+_: xpt.HasMatrixTranspose = nparr_i32
+_: xpt.HasMatrixTranspose = nparr_f32
+
 # =========================================================
 # `xpt.Array`
 

tests/integration/test_numpy2p0.pyi

@@ -53,6 +53,14 @@ _: xpt.HasDevice = nparr_i32
 _: xpt.HasDevice = nparr_f32
 _: xpt.HasDevice = nparr_b
 
+# =========================================================
+# `xpt.HasMatrixTranspose`
+
+_: xpt.HasMatrixTranspose = nparr
+_: xpt.HasMatrixTranspose = nparr_i32
+_: xpt.HasMatrixTranspose = nparr_f32
+_: xpt.HasMatrixTranspose = nparr_b
+
 # =========================================================
 # `xpt.Array`