✨ HasTranspose

Signed-off-by: nstarman <nstarman@users.noreply.github.com>

Author: nstarman

src/array_api_typing/__init__.py

@@ -8,6 +8,7 @@
     "HasNDim",
     "HasShape",
     "HasSize",
+    "HasTranspose",
     "__version__",
     "__version_tuple__",
 )
@@ -20,5 +21,6 @@
     HasNDim,
     HasShape,
     HasSize,
+    HasTranspose,
 )
 from ._version import version as __version__, version_tuple as __version_tuple__

src/array_api_typing/_array.py

@@ -7,6 +7,7 @@
     "HasNDim",
     "HasShape",
     "HasSize",
+    "HasTranspose",
 )
 
 from types import ModuleType
@@ -157,6 +158,36 @@ def size(self) -> int | None:
         ...
 
 
+class HasTranspose(Protocol):
+    """Protocol for array classes that support the transpose operation."""
+
+    @property
+    def T(self) -> Self:  # noqa: N802
+        """Transpose of the array.
+
+        The array instance must be two-dimensional. If the array instance is not
+        two-dimensional, an error should be raised.
+
+        Returns:
+            Self: two-dimensional array whose first and last dimensions (axes)
+                are permuted in reverse order relative to original array. The
+                returned array must have the same data type as the original
+                array.
+
+        Notes:
+            Limiting the transpose to two-dimensional arrays (matrices) deviates
+            from the NumPy et al practice of reversing all axes for arrays
+            having more than two-dimensions. This is intentional, as reversing
+            all axes was found to be problematic (e.g., conflicting with the
+            mathematical definition of a transpose which is limited to matrices;
+            not operating on batches of matrices; et cetera). In order to
+            reverse all axes, one is recommended to use the functional
+            `PermuteDims` interface found in this specification.
+
+        """
+        ...
+
+
 class Array(
     # ------ Attributes -------
     HasDType[DTypeT_co],
@@ -165,6 +196,7 @@ class Array(
     HasNDim,
     HasShape,
     HasSize,
+    HasTranspose,
     # ------- Methods ---------
     HasArrayNamespace[NamespaceT_co],
     # -------------------------

tests/integration/test_numpy1p0.pyi

@@ -75,3 +75,7 @@ assert_type(x_i32.shape, tuple[int | None, ...])
 # Check Attribute `.size`
 assert_type(x_f32.size, int | None)
 assert_type(x_i32.size, int | None)
+
+# Check Attribute `.T`
+assert_type(x_f32.T, xpt.Array[dtype[Any]])
+assert_type(x_i32.T, xpt.Array[dtype[Any]])

tests/integration/test_numpy2p0.pyi

@@ -86,3 +86,8 @@ assert_type(x_b.shape, tuple[int | None, ...])
 assert_type(x_f32.size, int | None)
 assert_type(x_i32.size, int | None)
 assert_type(x_b.size, int | None)
+
+# Check Attribute `.T`
+assert_type(x_f32.T, xpt.Array[np.dtype[F32]])
+assert_type(x_i32.T, xpt.Array[np.dtype[I32]])
+assert_type(x_b.T, xpt.Array[np.dtype[B]])