- Stubs: numpy main @
3b1e425eb3(first-pass fixes merged) - Runtime:
2.6.0.dev0built 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.
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/ArrayTwhenweights: _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).
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.
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'sopoverloads to a genericnditer.) - Backport: yes — the canonical iteration pattern from the nditer docs type-errors today.
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 = Nonesonames=-only calls resolve there (its_RecArray[record]return matches runtime). - Backport: yes — hard false positive on the canonical recarray constructors.
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 tondarray.astype - Fix: add
astypeoverloads onMaskedArrayreturningMaskedArray[_ShapeT_co, dtype[ScalarT]]; optionally__divmod__/__rdivmod__too. - Backport: yes — dtype conversion of a masked array is everyday usage; purely additive stub.
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.averageits own overloads inextras.pyiwithMaskedArrayreturns for the axis/keepdims cases. - Backport: yes — flagship ma function; also inherits bug 1 as long as it aliases
np.average.
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.
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: float16Runtime:
>>> 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,ArrayToverloads L5127-L5148,outermirrors L5350-L5503; instances L6193-L6197 - Fix (one PR for the class): move the
~f64overloads ahead of theFloatT/floatpairs (any pair containingfloat64then resolves tofloat64whilecopysign(f32, 2.0)still falls through); restrict the weak slot in theArrayToverloads to scalarfloatand route_NestedSequence[float]toNDArray[float64](keeplongdouble × seq -> longdouble, verifiedgat runtime); addbool, bool -> np.float16beforefloat, float. - Backport: n/a — not in any release; fix on main before 2.6.
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
polyvaloverloads) - Fix: add scalar-
xoverloads returning the scalar type (e.g.x: _FloatLike_co -> np.floating), keeping array-xoverloads as-is. - Backport: yes —
np.polyval(p, scalar)is common in legacy code; assigning the result tofloatis a false reject today.
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.
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.
- Stub: numpy/lib/_histograms_impl.pyi#L243-L273
- Fix:
tuple[...]→list[_Array1D[...]]in the second element of all four overloads. - Backport: yes — provably wrong container type; mechanical fix.
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]], ...](matchingnonzero, which the ma stubs already get right). - Backport: yes — one-line; wrong class (the 1-arg form is the rarer one, hence this rank).
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 thefull=Trueoverloads - Fix:
type _5Tup[T] = tuple[T, NDArray[float64], np.int32, NDArray[float64], np.float64]. - Backport: yes — one-line alias fix.
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.pyiandpolyutils.pyi - Fix:
Sequence[npt.NDArray[np.inexact] | np.int32 | np.floating](runtime is literally[resid, rank, sv, rcond]), orlist[Any]. - Backport: yes — one-line alias fix, same PR family as 14.
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.
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_11base (L313) - Fix:
Never-returning@overloadfornpt.NDArray[np.bool] | Sequence[bool]in the two subclasses, before the inherited fallback. - Backport: no — accepts-but-raises on rare input.
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, noToverride;.copy()/__deepcopy__really do return the singleton — verified correct) - Fix: override
T(and similar view methods) onMaskedConstantto returnMaskedArray[tuple[()], dtype[float64]]. - Backport: no — niche corner.
np.sum/np.prodof unsigned sub-intpints revealnp.int_— runtime givesuint64(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.uintpwould fix it.np.apply_along_axis(np.mean, 0, a)pyright false positive (overload-vs-Concatenatelimitation) — carried over from the first-pass appendix; also reproduces fornp.ma.apply_along_axis. Non-overloaded callables and lambdas are fine.np.negative(True)(scalar form) revealsnp.int_but raises — the scalarintoverloads acceptingbuiltins.boolis the accepted bool-in-int simplification; folded into finding 17 only for the array case.
- Scalar arithmetic under NEP 50 (
float32 + float→ float32,int8 + int→ int8,int8 / int→ float64,i8 + True,f4 ** 2),abs/.real/.imagon complex,round/np.roundon 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/modftuples,divmodon arrays _ufunc_21_fhomogeneous 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, matmulsum/ptp/count_nonzero(returnsnp.int64at runtime — stubintpcorrect),argmax/searchsorted/lexsort/flatnonzero→intp,unravel_index/ravel_multi_index,take_along_axis,isclose/allclose/array_equal,isinpercentile/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/frompyfuncnp.pad,packbits/unpackbits,datetime_as_string,fromiter,indices(incl. sparse),append,trim_zeros,roll,repeat,vander,block,split/array_split,unstack,atleast_*,require,finfo/iinfoattributes,astype(function and method), scalar constructors from strings, array-API aliases (concat,permute_dims,pow,matrix_transpose),sort/argsort/partitionwith the newdescending=kwarg,busdaycalendarattributes,ndenumerate/ndindex- np.ma: construction, reductions,
filled/compressed/properties/__getitem__/arithmetic/comparisons,masked_wherefamily,fix_invalid,getmask/getdata,concatenate, 3-argwhere,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, themaskedsingleton basics - numpy.polynomial: all convenience classes (construction, call, arithmetic, roots/deriv/integ/linspace/convert/fit incl.
cov=True), npoly module functions,np.poly1dand 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 (exceptpartition/rpartition) and numpy.char equivalents across str_/bytes_/StringDType, loadtxt/savetxt/genfromtxt/fromregex/save/load/savez