Skip to content

Instantly share code, notes, and snippets.

@jorenham
Last active July 9, 2026 09:17
Show Gist options
  • Select an option

  • Save jorenham/9d55eb8ed68d85007d0aa8b0fb1b8813 to your computer and use it in GitHub Desktop.

Select an option

Save jorenham/9d55eb8ed68d85007d0aa8b0fb1b8813 to your computer and use it in GitHub Desktop.
NumPy 2.5.1 stub audit - 2nd pass

part 1: https://gist.github.com/jorenham/f91ff9ae7453e4fafabaf4c490545404


NumPy stub audit — second pass

  • Stubs: numpy main @ 3b1e425eb3 (first-pass fixes merged)
  • Runtime: 2.6.0.dev0 built from source at the same commit range (all commits since the first-pass build are stubs/build-system only)
  • Checkers: basedpyright 1.39.8 (pyright 1.1.410)
  • Scope: new issues only; everything from the first pass is excluded
  • Ordered by severity × impact. Backport = worth targeting maintenance/2.5.x.

1. np.average with promoting weights keeps the input dtype

The ScalarT: np.inexact / ArrayT: NDArray[np.inexact] overloads bind the result solely from a while accepting weights: _ArrayLikeNumber_co, but runtime computes result_type(a.dtype, weights.dtype).

def f(a: npt.NDArray[np.float32], w: npt.NDArray[np.float64]) -> None:
    reveal_type(np.average(a, weights=w))           # floating[_32Bit]
    reveal_type(np.average(a, weights=[1.0, 2.0]))  # floating[_32Bit]
>>> type(np.average(np.ones(4, np.float32), weights=np.ones(4)))
<class 'numpy.float64'>
>>> type(np.average(np.ones(4, np.float32), weights=[1.0, 1.0, 1.0, 1.0]))
<class 'numpy.float64'>

Same for returned=True (tuple[floating[_32Bit], ...]) and complex64 (complexfloating[_32Bit, _32Bit] vs runtime complex128).

  • Stub: numpy/lib/_function_base_impl.pyi#L217-L287 (the list probe hits L235-L242)
  • Fix: only bind ScalarT/ArrayT when weights: _ArrayLike[ScalarT] | None; send other weights dtypes to the promotion overloads.
  • Backport: yes — very popular call, silently wrong dtype for any non-matching weights (including plain lists).

2. np.bincount with weights returns float64, stub says intp

DONE: numpy/numpy#31911

Runtime always casts weights to double and returns a float64 array; the stub is a single non-overloaded def returning _Array1D[intp].

def f(x: npt.NDArray[np.int64], w: npt.NDArray[np.float64]) -> None:
    reveal_type(np.bincount(x, weights=w))  # ndarray[tuple[int], dtype[signedinteger[_32Bit | _64Bit]]]
>>> np.bincount(np.array([0, 1, 1, 2]), weights=np.array([.5, 1, 1.5, 2])).dtype
dtype('float64')
>>> np.bincount(np.array([0, 1, 1, 2]), weights=np.array([1, 2, 3, 4])).dtype
dtype('float64')  # even int weights
  • Stub: numpy/_core/multiarray.pyi#L810
  • Fix: two overloads — weights: None = None -> _Array1D[np.intp]; weights: ArrayLike -> _Array1D[np.float64].
  • Backport: yes — weighted bincount (group-sums, weighted histograms) is a common idiom and the revealed dtype is flatly wrong.

3. nditer yields tuple[NDArray, ...] for single-operand iteration

nditer.__next__ and nditer.value are typed as tuple[NDArray[Incomplete], ...] unconditionally; a single-operand nditer yields 0-d ndarrays. The docs-headline pattern for x in np.nditer(a): x[...] produces false positives on every element operation ("__setitem__" method not defined on type "tuple[...]").

def f(a: np.ndarray) -> None:
    for x in np.nditer(a):
        reveal_type(x)  # tuple[ndarray[tuple[Any, ...], dtype[Any]], ...]
    it = np.nditer(a, flags=["multi_index"])
    reveal_type(it.value)  # tuple[ndarray[tuple[Any, ...], dtype[Any]], ...]
>>> el = next(iter(np.nditer(np.arange(6.))))
>>> type(el), el.shape
(<class 'numpy.ndarray'>, ())

Multi-operand nditer does return a tuple (verified).

  • Stub: numpy/_core/multiarray.pyi#L1821 (__next__), L1878 (value)
  • Fix (simple): -> NDArray[Incomplete] | tuple[NDArray[Incomplete], ...] for both. (Precise would key the ctor's op overloads to a generic nditer.)
  • Backport: yes — the canonical iteration pattern from the nditer docs type-errors today.

4. np.rec.fromarrays / np.rec.fromrecords reject names= without formats

DONE: numpy/numpy#31914

Overload 1 pins formats/names/titles to None; overload 2 makes formats required. names=-only — with formats auto-inferred — is the docstring usage of both.

def f(x: np.ndarray) -> None:
    np.rec.fromarrays([x, x], names="a,b")
    # error: Argument of type "Literal['a,b']" cannot be assigned to parameter "names" of type "None"
    np.rec.fromrecords([(1, 2.0)], names="a,b")
    # error: same
>>> r = np.rec.fromarrays([np.array([1., 2.]), np.array([3, 4])], names="a,b")
>>> type(r), r.dtype
(<class 'numpy.rec.recarray'>, dtype((numpy.record, [('a', '<f8'), ('b', '<i8')])))
  • Stub: numpy/_core/records.pyi#L133-L154 (fromarrays), L157-L178 (fromrecords)
  • Fix: in the second overload of each, default formats: DTypeLike | None = None so names=-only calls resolve there (its _RecArray[record] return matches runtime).
  • Backport: yes — hard false positive on the canonical recarray constructors.

5. MaskedArray.astype (not overridden) drops to ndarray

DONE: numpy/numpy#31918

MaskedArray doesn't override astype, so the result is typed as plain ndarray and every subsequent masked-API access is a false-positive error. Runtime returns MaskedArray (subok=True default).

def f(m: np.ma.MaskedArray[Any, np.dtype[np.float64]]) -> None:
    x = m.astype(np.int32)
    reveal_type(x)  # ndarray[Any, dtype[signedinteger[_32Bit]]]
    x.mask          # error: Cannot access attribute "mask" for class "ndarray[Any, _dtype]"
>>> m = np.ma.MaskedArray([[1., 2.], [3., 4.]], mask=[[True, False], [False, False]])
>>> x = m.astype(np.int32)
>>> type(x), x.mask.tolist()
(<class 'numpy.ma.MaskedArray'>, [[True, False], [False, False]])

divmod(m, 2) has the same problem via inherited __divmod__ (reveals tuple[ndarray, ndarray], runtime two MaskedArrays).

  • Stub: absent from numpy/ma/core.pyi#L1045 (class MaskedArray); falls through to ndarray.astype
  • Fix: add astype overloads on MaskedArray returning MaskedArray[_ShapeT_co, dtype[ScalarT]]; optionally __divmod__/__rdivmod__ too.
  • Backport: yes — dtype conversion of a masked array is everyday usage; purely additive stub.

6. np.ma.average is a re-export of np.average — result typed as ndarray

ma/extras.pyi imports average from numpy.lib._function_base_impl instead of stubbing the distinct masked-aware function; axis reductions return MaskedArray at runtime.

def f(m: np.ma.MaskedArray[Any, np.dtype[np.float64]]) -> None:
    y = np.ma.average(m, axis=0)
    reveal_type(y)  # ndarray[tuple[Any, ...], dtype[float64]]
    y.mask          # error: Cannot access attribute "mask" for class "NDArray[float64]"
    reveal_type(np.ma.average(m, axis=0, returned=True))  # tuple[ndarray[...], ndarray[...]]
>>> y = np.ma.average(m, axis=0)
>>> type(y), y.mask.tolist()
(<class 'numpy.ma.MaskedArray'>, [False, False])
>>> tuple(type(v).__name__ for v in np.ma.average(m, axis=0, returned=True))
('MaskedArray', 'ndarray')
  • Stub: numpy/ma/extras.pyi#L33
  • Fix: give ma.average its own overloads in extras.pyi with MaskedArray returns for the axis/keepdims cases.
  • Backport: yes — flagship ma function; also inherits bug 1 as long as it aliases np.average.

7. np.strings.partition/rpartition return a 3-tuple of arrays, stub says single array

DONE: numpy/numpy#31912

Unlike np.char.partition (one array with a trailing size-3 axis — its stub is correct, verified), numpy.strings.partition returns (before, sep, after). All 8 overloads of partition/rpartition are affected; unpacking — the only way to use the result — misleads (ndarray[str_] unpack gives str_ elements, not arrays).

def f(s: np.ndarray[tuple[int], np.dtype[np.str_]]) -> None:
    reveal_type(np.strings.partition(s, " "))  # ndarray[tuple[Any, ...], dtype[str_]]
>>> r = np.strings.partition(np.array(["a b", "c d"]), " ")
>>> type(r), len(r), type(r[0])
(<class 'tuple'>, 3, <class 'numpy.ndarray'>)

Secondary: the T_co overload accepts partition(stringdtype_arr, " "), which raises _UFuncNoLoopError at runtime (StringDType requires a StringDType separator).

  • Stub: numpy/_core/strings.pyi#L403-L420
  • Fix: wrap each return in a 3-tuple, e.g. -> tuple[NDArray[np.str_], NDArray[np.str_], NDArray[np.str_]].
  • Backport: yes — wrong container type; every use site is affected.

8. nditer rejects nested op_flags=[["readwrite"]] for a single operand

DONE: numpy/numpy#31915

The single-operand __init__ overload types op_flags: Sequence[_NDIterFlagsOp] | None, but runtime accepts (and the docs use) the nested list-of-lists form for one operand too.

def f(a: np.ndarray) -> None:
    with np.nditer(a, op_flags=[["readwrite"]]) as it:  # error: No overloads for "__init__" match
        ...
>>> np.nditer(np.arange(6.), op_flags=[["readwrite"]])  # works
  • Stub: numpy/_core/multiarray.pyi#L1792
  • Fix: op_flags: Sequence[_NDIterFlagsOp] | Sequence[Sequence[_NDIterFlagsOp]] | None = None.
  • Backport: yes — the nested form is what the nditer docs use even for one operand; pairs with bug 3.

9. _ufunc_21_f (new copysign/heaviside/logaddexp[2]/nextafter stubs): weak-scalar overloads capture strong operands

DONE: numpy/numpy#31924

Introduced by #31903 (main only, unreleased). Three related holes, all from float-typed "weak scalar" slots matching things that are not weak python floats:

(a) np.float64 <: builtins.float, so a strong float64 operand binds the other operand's narrower dtype:

def f(f16: np.float16, f32: np.float32, f64: np.float64, a32: npt.NDArray[np.float32]) -> None:
    reveal_type(np.copysign(f32, f64))   # floating[_32Bit]  — runtime: float64
    reveal_type(np.copysign(f64, f16))   # floating[_16Bit]  — runtime: float64
    reveal_type(np.logaddexp(a32, f64))  # NDArray[floating[_32Bit]]  — runtime: float64

(b) float lists are strong (float64 array) but match _NestedSequence[float] in the ArrayT slot:

    reveal_type(np.copysign(a32, [1.0, 2.0]))         # NDArray[floating[_32Bit]]  — runtime: float64
    reveal_type(np.logaddexp.outer(a32, [1.0, 2.0]))  # NDArray[floating[_32Bit]]  — runtime: float64

(c) python bools hit the float, float -> float64 overload but promote like np.bool:

    reveal_type(np.copysign(True, True))  # float64  — runtime: float16

Runtime:

>>> type(np.copysign(np.float32(1), np.float64(1)))
<class 'numpy.float64'>
>>> np.logaddexp(np.ones(2, np.float32), np.float64(1)).dtype
dtype('float64')
>>> np.copysign(np.ones(2, np.float32), [1.0, 2.0]).dtype
dtype('float64')
>>> type(np.copysign(True, True))
<class 'numpy.float16'>
>>> np.copysign(np.ones(2, np.float32), 2.0).dtype   # bare python float stays weak — stub correct here
dtype('float32')
  • Stub: numpy/_core/umath.pyi#L4990 (class _ufunc_21_f); scalar overloads L4995-L5049, ArrayT overloads L5127-L5148, outer mirrors L5350-L5503; instances L6193-L6197
  • Fix (one PR for the class): move the ~f64 overloads ahead of the FloatT/float pairs (any pair containing float64 then resolves to float64 while copysign(f32, 2.0) still falls through); restrict the weak slot in the ArrayT overloads to scalar float and route _NestedSequence[float] to NDArray[float64] (keep longdouble × seq -> longdouble, verified g at runtime); add bool, bool -> np.float16 before float, float.
  • Backport: n/a — not in any release; fix on main before 2.6.

10. np.polyval with scalar x returns a scalar, stub always returns NDArray

reveal_type(np.polyval([3.0, 0.0, 1.0], 5.0))  # ndarray[tuple[Any, ...], dtype[floating[Any]]]
>>> type(np.polyval([3.0, 0.0, 1.0], 5.0))
<class 'numpy.float64'>

numpy.polynomial.polynomial.polyval handles scalar x correctly (verified).

  • Stub: numpy/lib/_polynomial_impl.pyi#L296-L324 (all polyval overloads)
  • Fix: add scalar-x overloads returning the scalar type (e.g. x: _FloatLike_co -> np.floating), keeping array-x overloads as-is.
  • Backport: yes — np.polyval(p, scalar) is common in legacy code; assigning the result to float is a false reject today.

11. np.sort_complex rejects all builtin sequences, including its docstring example

DONE: numpy/numpy#31917

Every overload takes _ArrayLike[<np scalar>]; there is no builtin-sequence overload.

np.sort_complex([5, 3, 6, 2, 1])
# error: No overloads for "sort_complex" match the provided arguments
# error: Argument of type "list[int]" cannot be assigned to parameter "a" of type "_ArrayLike[longdouble]"
>>> np.sort_complex([5, 3, 6, 2, 1])
array([1.+0.j, 2.+0.j, 3.+0.j, 5.+0.j, 6.+0.j])

(list[float] and list[complex] likewise work at runtime → complex128.)

  • Stub: numpy/lib/_function_base_impl.pyi#L944-L958
  • Fix: add def sort_complex(a: _SeqND[complex]) -> NDArray[np.complex128]: ... (the alias already exists in the file).
  • Backport: yes — hard false positive on the documented usage; trivially additive.

12. np.histogramdd returns edges as a list, stub says tuple

DONE: numpy/numpy#31916

def f(s: npt.NDArray[np.float64]) -> None:
    reveal_type(np.histogramdd(s)[1])  # tuple[ndarray[tuple[int], dtype[float64]], ...]
>>> type(np.histogramdd(np.random.rand(10, 2))[1])
<class 'list'>

All four overloads claim tuple; the docstring documents "edges : list". e: list[...] = np.histogramdd(s)[1] is a false-positive error and isinstance(edges, tuple) narrowing lies.

13. np.ma.where(cond) (1-arg form) claims tuple[MaskedArray[intp], ...], returns plain ndarrays

DONE: numpy/numpy#31919

Runtime path is filled(condition, 0).nonzero() — plain ndarray[intp], not MaskedArray.

def f(m: np.ma.MaskedArray[Any, np.dtype[np.float64]]) -> None:
    reveal_type(np.ma.where(m > 1))  # tuple[MaskedArray[tuple[Any, ...], dtype[signedinteger[_32Bit | _64Bit]]], ...]
>>> w = np.ma.where(m > 1)
>>> type(w[0])
<class 'numpy.ndarray'>
  • Stub: numpy/ma/core.pyi#L3960
  • Fix: -> tuple[np.ndarray[tuple[int], np.dtype[np.intp]], ...] (matching nonzero, which the ma stubs already get right).
  • Backport: yes — one-line; wrong class (the 1-arg form is the rarer one, hence this rank).

14. np.polyfit(..., full=True): rank and rcond typed as arrays, are scalars

coef, resids, rank, sv, rcond = np.polyfit(x, y, 2, full=True)
reveal_type(rank)   # ndarray[tuple[Any, ...], dtype[signedinteger[_32Bit]]]
reveal_type(rcond)  # ndarray[tuple[Any, ...], dtype[float64]]
>>> [type(v).__name__ for v in np.polyfit([0., 1., 2., 3.], [1., 2., 3., 5.], 2, full=True)]
['ndarray', 'ndarray', 'int32', 'ndarray', 'float64']
  • Stub: numpy/lib/_polynomial_impl.pyi#L42 (type _5Tup[T] = tuple[T, NDArray[float64], NDArray[int32], NDArray[float64], NDArray[float64]]), used by the full=True overloads
  • Fix: type _5Tup[T] = tuple[T, NDArray[float64], np.int32, NDArray[float64], np.float64].
  • Backport: yes — one-line alias fix.

15. Polynomial.fit(..., full=True) diagnostics element type excludes its ndarray members

p, extra = Polynomial.fit(x, y, 2, full=True)
reveal_type(extra)     # Sequence[inexact[Any, Any] | signedinteger[_32Bit]]
reveal_type(extra[0])  # inexact[Any, Any] | signedinteger[_32Bit]
>>> p, extra = Polynomial.fit([0., 1., 2., 3.], [1., 2., 3., 5.], 2, full=True)
>>> [type(v).__name__ for v in extra]
['ndarray', 'int32', 'ndarray', 'float64']

extra[0] (residuals) and extra[2] (singular values) are ndarrays. Same runtime shape for numpy.polynomial.polynomial.polyfit(full=True).

  • Stub: numpy/polynomial/_polytypes.pyi#L81 (type _FullFitResult = Sequence[np.inexact | np.int32]); consumers in _polybase.pyi and polyutils.pyi
  • Fix: Sequence[npt.NDArray[np.inexact] | np.int32 | np.floating] (runtime is literally [resid, rank, sv, rcond]), or list[Any].
  • Backport: yes — one-line alias fix, same PR family as 14.

16. np.ma.count_masked() with axis=None returns a scalar, stub says NDArray[intp]

DONE: numpy/numpy#31920

def f(m: np.ma.MaskedArray[Any, np.dtype[np.float64]]) -> None:
    reveal_type(np.ma.count_masked(m))  # ndarray[tuple[Any, ...], dtype[signedinteger[_32Bit | _64Bit]]]
>>> type(np.ma.count_masked(m))
<class 'numpy.int64'>
  • Stub: numpy/ma/extras.pyi#L295
  • Fix: overloads — axis: None = None -> np.intp; axis: SupportsIndex -> NDArray[np.intp].
  • Backport: yes — direct companion of the first-pass ma.count() fix.

17. np.negative/np.positive/np.sign accept bool arrays but always raise

SKIP: prepending a -> Never overload is unsound

The operators are handled (-b → error), and every other specialized unary ufunc gets bool right per-loop (square/reciprocal/conjugate → int8, floor/ceil/trunc → bool, spacing/cbrt/fabs/rint → float16 — all verified). These three have no bool loop and leak through the untyped _ufunc_11 base fallback.

def f(b: npt.NDArray[np.bool]) -> None:
    -b               # error: Operator "-" not supported — correct
    np.negative(b)   # Any — accepted
    np.positive(b)   # Any — accepted
    np.sign(b)       # Any — accepted
>>> np.negative(np.array([True]))
TypeError: The numpy boolean negative, the `-` operator, is not supported, ...

np.subtract(b, b) has the same hole (dtype[Any], raises; b - b is correctly NoReturn), but subtract is still the legacy _UFunc_Nin2_Nout1 (numpy/init.pyi#L7654) and is presumably subsumed by the specialization work.

  • Stub: _ufunc_11_ifcmo (positive/negative), _ufunc_11_ifcmo_ifco (sign); fallback in the _ufunc_11 base (L313)
  • Fix: Never-returning @overload for npt.NDArray[np.bool] | Sequence[bool] in the two subclasses, before the inherited fallback.
  • Backport: no — accepts-but-raises on rare input.

18. np.ma.masked.T reveals MaskedConstant, runtime returns a 0-d MaskedArray

Inherited ndarray.T -> Self; runtime views of the constant don't stay MaskedConstant.

reveal_type(np.ma.masked.T)  # MaskedConstant
>>> type(np.ma.masked.T), isinstance(np.ma.masked.T, np.ma.core.MaskedConstant)
(<class 'numpy.ma.MaskedArray'>, False)
  • Stub: numpy/ma/core.pyi#L2833-L2853 (class MaskedConstant, no T override; .copy()/__deepcopy__ really do return the singleton — verified correct)
  • Fix: override T (and similar view methods) on MaskedConstant to return MaskedArray[tuple[()], dtype[float64]].
  • Backport: no — niche corner.

Appendix: observations, not counted

  • np.sum/np.prod of unsigned sub-intp ints reveal np.int_ — runtime gives uint64 (np.sum(np.ones(2, np.uint8)).dtype == uint64). This is the shape the #31876 fix chose (bool | integer -> np.int_); noting it in case the signed/unsigned split wasn't a deliberate simplification. Splitting _DualArrayLike[dtype[np.bool | np.signedinteger], int] -> np.int_ / _ArrayLike[np.unsignedinteger] -> np.uintp would fix it.
  • np.apply_along_axis(np.mean, 0, a) pyright false positive (overload-vs-Concatenate limitation) — carried over from the first-pass appendix; also reproduces for np.ma.apply_along_axis. Non-overloaded callables and lambdas are fine.
  • np.negative(True) (scalar form) reveals np.int_ but raises — the scalar int overloads accepting builtins.bool is the accepted bool-in-int simplification; folded into finding 17 only for the array case.

Checked clean (verified, no mismatch)

  • Scalar arithmetic under NEP 50 (float32 + float → float32, int8 + int → int8, int8 / int → float64, i8 + True, f4 ** 2), abs/.real/.imag on complex, round/np.round on scalars and arrays
  • The recently specialized unary ufuncs on every dtype incl. bool per-loop (floor/ceil/trunc/invert/square/reciprocal/conjugate/sign/spacing/cbrt/fabs/rint/bitwise_count/ldexp/logical_*/comparisons/predicates), frexp/modf tuples, divmod on arrays
  • _ufunc_21_f homogeneous pairs, integer/bool promotions to float64, dtype=/out=, .reduce/.accumulate/.reduceat/.outer/.at; einsum, tensordot, kron, convolve, correlate, clip, where, choose, compress, dot/vdot/inner/outer, matmul
  • sum/ptp/count_nonzero (returns np.int64 at runtime — stub intp correct), argmax/searchsorted/lexsort/flatnonzero → intp, unravel_index/ravel_multi_index, take_along_axis, isclose/allclose/array_equal, isin
  • percentile/quantile/median (int→float64, q scalar/array, method, weights), cov/corrcoef, interp (period, complex), gradient, diff, trapezoid, unwrap, meshgrid (0–4 args, sparse, indexing), select, angle, sinc, i0, digitize, histogram/histogram2d/histogram_bin_edges, insert/delete/place/extract/copyto, rot90/flip, real_if_close, nan_to_num, geomspace/logspace, vectorize/frompyfunc
  • np.pad, packbits/unpackbits, datetime_as_string, fromiter, indices (incl. sparse), append, trim_zeros, roll, repeat, vander, block, split/array_split, unstack, atleast_*, require, finfo/iinfo attributes, astype (function and method), scalar constructors from strings, array-API aliases (concat, permute_dims, pow, matrix_transpose), sort/argsort/partition with the new descending= kwarg, busdaycalendar attributes, ndenumerate/ndindex
  • np.ma: construction, reductions, filled/compressed/properties/__getitem__/arithmetic/comparisons, masked_where family, fix_invalid, getmask/getdata, concatenate, 3-arg where, dot, median, compress_rows/cols, unique, allequal/allclose, polyfit, corrcoef/cov, mr_, sort, nonzero, set-ops, stack/*stack, diag, ediff1d, append, mask_or/make_mask, the masked singleton basics
  • numpy.polynomial: all convenience classes (construction, call, arithmetic, roots/deriv/integ/linspace/convert/fit incl. cov=True), npoly module functions, np.poly1d and friends
  • numpy.testing assert functions (incl. context-manager assert_raises, masked arrays, nested tuples), np.rec.array/format_parser/recarray attribute access, memmap, flatiter, broadcast, ctypeslib, numpy.dtypes classes, np.exceptions, numpy.strings (except partition/rpartition) and numpy.char equivalents across str_/bytes_/StringDType, loadtxt/savetxt/genfromtxt/fromregex/save/load/savez
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment