Should meshgrid return a list or a tuple of coordinate arrays? #938

Activity

1. kgryte commented on May 15, 2025

   

   kgryte

   on May 15, 2025

   Last edited by kgryte

   Contributor

   More actions

   @ev-br The spec likely reflects pre-NumPy v2.0. See https://numpy.org/doc/1.26/reference/generated/numpy.meshgrid.html and https://github.com/numpy/numpy/blob/v1.26.0/numpy/lib/function_base.py#L5163.
2. ev-br commented on May 15, 2025

   

   ev-br

   on May 15, 2025

   MemberAuthor

   More actions

   So it might be worth revisiting this in the spec then.
3. ev-br commented on Jun 23, 2025

   

   ev-br

   on Jun 23, 2025

   Last edited by ev-br

   MemberAuthor

   More actions

   Assuming that List[array] is the correct annotation for functions which return lists of arrays, the only functions which return a list of arrays are meshgrid and broadcast_arrays, cf #934.

   Two other instances in the search below are stack and concat which accept sequences.

   The current spec requirement, List[arrays], comes from NumPy 1.x. Given that NumPy 2.x deliberately changed return type to tuple[arrays], it seems reasonable to change the spec for 2025.12, too.
   Alternatively, allow a union of a list and a tuple, with a recommendation along the lines of should return a tuple but may return a list.

   $ git grep -n "List\[arr" src/array_api_stubs/_draft/
   src/array_api_stubs/_draft/creation_functions.py:454:def meshgrid(*arrays: array, indexing: Literal["xy", "ij"] = "xy") -> List[array]:
   src/array_api_stubs/_draft/creation_functions.py:467:    out: List[array]
   src/array_api_stubs/_draft/manipulation_functions.py:22:def broadcast_arrays(*arrays: array) -> List[array]:
   src/array_api_stubs/_draft/manipulation_functions.py:33:    out: List[array]
   src/array_api_stubs/_draft/manipulation_functions.py:60:    arrays: Union[Tuple[array, ...], List[array]], /, *, axis: Optional[int] = 0
   src/array_api_stubs/_draft/manipulation_functions.py:67:    arrays: Union[Tuple[array, ...], List[array]]
   src/array_api_stubs/_draft/manipulation_functions.py:302:def stack(arrays: Union[Tuple[array, ...], List[array]], /, *, axis: int = 0) -> array:
   src/array_api_stubs/_draft/manipulation_functions.py:308:    arrays: Union[Tuple[array, ...], List[array]]
   
4. ev-br commented on Sep 18, 2025

   

   ev-br

   on Sep 18, 2025

   MemberAuthor

   More actions

   @jakevdp while not exactly the master list , the functions which return List[array] in the Array API spec but have been changed in NumPy 2.0 to return tuples are meshgrid and broadcast_arrays, #938 (comment)
5. kgryte commented on Nov 13, 2025

   

   kgryte

   on Nov 13, 2025

   Contributor

   More actions

   Currently, in the specification, the list is as follows:

   • meshgrid
   • broadcast_arrays
   • info.devices

   In the following APIs, we return tuples:

   • unique_all
   • unique_counts
   • unique_inverse
   • nonzero
   • unstack
   • linalg.svg
   • linalg.slogdet
   • linalg.qr
   • linalg.eigh
   • array.shape
   • array.dlpack_device
6. kgryte commented on Nov 13, 2025

   

   kgryte

   on Nov 13, 2025

   Contributor

   More actions

   I've opened #981.
7. kgryte

   closed this as completedin #981on Jan 5, 2026
8. kgryte

   added this to the v2025 milestone on Jan 5, 2026
9. pull

   added a commit that references this issue on Jan 5, 2026

   feat!: return tuples rather than lists

   ...

   eeaa9fa