docs: add note that iteration is defined for 1-D arrays

PR-URL: #821 Co-authored-by: Athan Reines <[email protected]> Reviewed-by: Athan Reines <[email protected]>
data-apis · Oct 31, 2024 · c28d3c5 · c28d3c5
1 parent 1765933
commit c28d3c5
Show file tree

Hide file tree

Showing 4 changed files with 20 additions and 0 deletions.
diff --git a/src/array_api_stubs/_2021_12/array_object.py b/src/array_api_stubs/_2021_12/array_object.py
@@ -465,6 +465,8 @@ def __getitem__(
         """
         Returns ``self[key]``.
 
+        See :ref:`indexing` for details on supported indexing semantics.
+
         Parameters
         ----------
         self: array
@@ -914,6 +916,8 @@ def __setitem__(
         """
         Sets ``self[key]`` to ``value``.
 
+        See :ref:`indexing` for details on supported indexing semantics.
+
         Parameters
         ----------
         self: array

diff --git a/src/array_api_stubs/_2022_12/array_object.py b/src/array_api_stubs/_2022_12/array_object.py
@@ -489,6 +489,8 @@ def __getitem__(
         """
         Returns ``self[key]``.
 
+        See :ref:`indexing` for details on supported indexing semantics.
+
         Parameters
         ----------
         self: array
@@ -937,6 +939,8 @@ def __setitem__(
         """
         Sets ``self[key]`` to ``value``.
 
+        See :ref:`indexing` for details on supported indexing semantics.
+
         Parameters
         ----------
         self: array

diff --git a/src/array_api_stubs/_2023_12/array_object.py b/src/array_api_stubs/_2023_12/array_object.py
@@ -616,6 +616,8 @@ def __getitem__(
         """
         Returns ``self[key]``.
 
+        See :ref:`indexing` for details on supported indexing semantics.
+
         Parameters
         ----------
         self: array
@@ -1085,6 +1087,8 @@ def __setitem__(
         """
         Sets ``self[key]`` to ``value``.
 
+        See :ref:`indexing` for details on supported indexing semantics.
+
         Parameters
         ----------
         self: array

diff --git a/src/array_api_stubs/_draft/array_object.py b/src/array_api_stubs/_draft/array_object.py
@@ -616,6 +616,8 @@ def __getitem__(
         """
         Returns ``self[key]``.
 
+        See :ref:`indexing` for details on supported indexing semantics.
+
         Parameters
         ----------
         self: array
@@ -627,6 +629,10 @@ def __getitem__(
         -------
         out: array
             an array containing the accessed value(s). The returned array must have the same data type as ``self``.
+
+        .. note::
+           When ``__getitem__`` is defined on an object, Python will automatically define iteration (i.e., the behavior from ``iter(x)``) as  ``x[0]``, ``x[1]``, ..., ``x[N-1]``. This can also be implemented directly by defining ``__iter__``. Therefore, for a one-dimensional array ``x``, iteration should produce a sequence of zero-dimensional arrays ``x[0]``, ``x[1]``, ..., ``x[N-1]``, where ``N`` is the number of elements in the array. Iteration behavior for arrays having zero dimensions or more than one dimension is unspecified and thus implementation-defined.
+
         """
 
     def __gt__(self: array, other: Union[int, float, array], /) -> array:
@@ -1085,6 +1091,8 @@ def __setitem__(
         """
         Sets ``self[key]`` to ``value``.
 
+        See :ref:`indexing` for details on supported indexing semantics.
+
         Parameters
         ----------
         self: array