feat: HasMatrixTranspose

Author: nstarman

src/array_api_typing/_array.py

@@ -7,7 +7,7 @@
 
 from pathlib import Path
 from types import ModuleType
-from typing import Literal, Never, Protocol, TypeAlias
+from typing import Literal, Never, Protocol, Self, TypeAlias
 from typing_extensions import TypeVar
 
 import optype as op
@@ -71,11 +71,33 @@ 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.
+
+        """
+        ...
+
+
 @docstring_setter(**_array_docstrings)
 class Array(
     # ------ Attributes -------
     HasDType[DType_co],
     HasDevice,
+    HasMatrixTranspose,
     # ------ Methods -------
     HasArrayNamespace[NS_co],
     op.CanPosSelf,