Description

This was previously alluded to in #15926 #15929 and #15930, but let's centralise the discussion.
The problem can be illustrated by this single line:

the reason why it doesn't work with numpy dev is that some numpy functions which returned lists in numpy 1.x now return tuples (xref numpy/numpy#25570), which breaks the current design of astropy.utils.masked.function_helpers.dispatch_function; functions decorated with it return either:

1. a tuple (result, mask, out)
2. just result (the output of a numpy function)
   In the second case, when result is a tuple, we miss the intended early return.
   This currently causes 16 failures in tests (some indirectly).

Here are all functions from the second category:

• array_equiv
• outer
• broadcast_arrays
• masked_nanfunc.<locals>.nanfunc
• piecewise
• choose
• interp
• sort_complex
• place
• block
• copyto
• put
• full_like
• array_equal
• percentile
• array_str
• nan_to_num
• median
• apply_over_axes
• lexsort
• quantile
• count_nonzero
• array2string
• putmask
• where
• concatenate

I think there are a couple avenues to fix this design problem:

• change the return value of all these functions so that they all join the first category (so the early return logic in __array_wrap__ could be dropped entirely
• extend @dispatch_function to make the distinction between the two categories more explicit and inspectable.

Expected behavior

No response

How to Reproduce

No response

Versions

import platform; print(platform.platform())
import sys; print("Python", sys.version)
import astropy; print("astropy", astropy.__version__)
import numpy; print("Numpy", numpy.__version__)
import erfa; print("pyerfa", erfa.__version__)
#import scipy; print("Scipy", scipy.__version__)
#import matplotlib; print("Matplotlib", matplotlib.__version__)

macOS-14.2.1-arm64-arm-64bit
Python 3.12.1 (main, Dec 11 2023, 18:41:50) [Clang 15.0.0 (clang-1500.0.40.1)]
astropy 6.1.dev369+g81acf686e7.d20240125
Numpy 2.0.0.dev0+git20240124.0a4b2b8
pyerfa 2.0.1.2.dev11+gc498084