✨ HasShape

Author: nstarman

src/array_api_typing/__init__.py

@@ -7,6 +7,7 @@
     "HasDevice",
     "HasMatrixTranspose",
     "HasNDim",
+    "HasShape",
     "__version__",
     "__version_tuple__",
 )
@@ -18,5 +19,6 @@
     HasDType,
     HasMatrixTranspose,
     HasNDim,
+    HasShape,
 )
 from ._version import version as __version__, version_tuple as __version_tuple__

src/array_api_typing/_array.py

@@ -5,6 +5,7 @@
     "HasDevice",
     "HasMatrixTranspose",
     "HasNDim",
+    "HasShape",
 )
 
 from types import ModuleType
@@ -115,12 +116,34 @@ def ndim(self) -> int:
         ...
 
 
+class HasShape(Protocol):
+    """Protocol for array classes that have a shape attribute."""
+
+    @property
+    def shape(self) -> tuple[int | None, ...]:
+        """Shape of the array.
+
+        Returns:
+            tuple[int | None, ...]: array dimensions. An array dimension must be None
+                if and only if a dimension is unknown.
+
+        Notes:
+            For array libraries having graph-based computational models, array
+            dimensions may be unknown due to data-dependent operations (e.g.,
+            boolean indexing; `A[:, B > 0]`) and thus cannot be statically
+            resolved without knowing array contents.
+
+        """
+        ...
+
+
 class Array(
     # ------ Attributes -------
     HasDType[DTypeT_co],
     HasDevice,
     HasMatrixTranspose,
     HasNDim,
+    HasShape,
     # ------- Methods ---------
     HasArrayNamespace[NamespaceT_co],
     # -------------------------

tests/integration/test_numpy1p0.pyi

@@ -67,3 +67,7 @@ _: xpt.Array[dtype[Any]] = x_i32.mT
 # Check Attribute `.ndim`
 _: int = x_f32.ndim
 _: int = x_i32.ndim
+
+# Check Attribute `.shape`
+_: tuple[int | None, ...] = x_f32.shape
+_: tuple[int | None, ...] = x_i32.shape

tests/integration/test_numpy2p0.pyi

@@ -76,3 +76,8 @@ _: xpt.Array[np.dtype[B]] = x_b.mT
 _: int = x_f32.ndim
 _: int = x_i32.ndim
 _: int = x_b.ndim
+
+# Check Attribute `.shape`
+_: tuple[int | None, ...] = x_f32.shape
+_: tuple[int | None, ...] = x_i32.shape
+_: tuple[int | None, ...] = x_b.shape