pyrefly-numpy-stubs 1.3.0.dev3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) Meta Platforms, Inc. and affiliates.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,48 @@
1
+ Metadata-Version: 2.5
2
+ Name: pyrefly-numpy-stubs
3
+ Version: 1.3.0.dev3
4
+ Summary: NumPy type stubs with array-shape tracking, maintained by Pyrefly
5
+ Project-URL: homepage, https://pyrefly.org
6
+ Project-URL: documentation, https://pyrefly.org/en/docs/
7
+ License: MIT License
8
+
9
+ Copyright (c) Meta Platforms, Inc. and affiliates.
10
+
11
+ Permission is hereby granted, free of charge, to any person obtaining a copy
12
+ of this software and associated documentation files (the "Software"), to deal
13
+ in the Software without restriction, including without limitation the rights
14
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
15
+ copies of the Software, and to permit persons to whom the Software is
16
+ furnished to do so, subject to the following conditions:
17
+
18
+ The above copyright notice and this permission notice shall be included in all
19
+ copies or substantial portions of the Software.
20
+
21
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
27
+ SOFTWARE.
28
+ License-File: LICENSE
29
+ Keywords: numpy,stubs,typechecker,typechecking
30
+ Classifier: Development Status :: 4 - Beta
31
+ Classifier: License :: OSI Approved :: MIT License
32
+ Classifier: Programming Language :: Python
33
+ Classifier: Programming Language :: Python :: 3
34
+ Classifier: Typing :: Stubs Only
35
+ Requires-Python: >=3.12
36
+ Requires-Dist: pyrefly-shape-extensions==1.3.0.dev3
37
+ Description-Content-Type: text/markdown
38
+
39
+ # pyrefly-numpy-stubs
40
+
41
+ NumPy type stubs with array shape information for Pyrefly.
42
+
43
+ This package is a PEP 561 stub-only distribution. It installs the
44
+ `numpy-stubs` stub package so Pyrefly can discover shape-aware stubs for the
45
+ runtime `numpy` package without replacing or shadowing NumPy itself.
46
+
47
+ The package is versioned in lockstep with Pyrefly and depends on the matching
48
+ `pyrefly-shape-extensions` package.
@@ -0,0 +1,10 @@
1
+ # pyrefly-numpy-stubs
2
+
3
+ NumPy type stubs with array shape information for Pyrefly.
4
+
5
+ This package is a PEP 561 stub-only distribution. It installs the
6
+ `numpy-stubs` stub package so Pyrefly can discover shape-aware stubs for the
7
+ runtime `numpy` package without replacing or shadowing NumPy itself.
8
+
9
+ The package is versioned in lockstep with Pyrefly and depends on the matching
10
+ `pyrefly-shape-extensions` package.
@@ -0,0 +1,560 @@
1
+ # Copyright (c) Meta Platforms, Inc. and affiliates.
2
+ #
3
+ # This source code is licensed under the MIT license found in the
4
+ # LICENSE file in the root directory of this source tree.
5
+
6
+ from typing import Any, Literal, overload
7
+
8
+ import shape_extensions
9
+ from numpy._shapes import diag_extent, matmul_shape, reduce_shape
10
+ from shape_extensions import broadcast, Flag, Int, IntTuple, IntVar
11
+
12
+ from . import linalg as linalg, random as random
13
+
14
+ type _Shape = IntTuple
15
+ type _AnyShape = tuple[Any, ...]
16
+ type _Axis = int | tuple[int, ...] | None
17
+
18
+ class generic: ...
19
+ class bool_(generic): ...
20
+ class float32(generic): ...
21
+ class float64(generic): ...
22
+ class int32(generic): ...
23
+ class int64(generic): ...
24
+ class intp(generic): ...
25
+
26
+ class dtype[Scalar = Any]:
27
+ @overload
28
+ def __new__[ScalarT: generic](cls, dtype: type[ScalarT]) -> dtype[ScalarT]: ...
29
+ @overload
30
+ def __new__(cls, dtype: Any = ...) -> dtype: ...
31
+ def __init__(self, dtype: Any = ...) -> None: ...
32
+
33
+ # `ndarray` declares a `dtype` attribute, which shadows the class above throughout
34
+ # its body. Annotations inside the class reach the class through this alias.
35
+ _dtype = dtype
36
+
37
+ @shape_extensions.shaped_array(shape="Shape")
38
+ class ndarray[Shape: _Shape = _AnyShape, DType = Any]:
39
+ shape: Shape
40
+ dtype: DType
41
+ @overload
42
+ def __len__[N: IntVar](self: ndarray[[N]]) -> Int[N]: ...
43
+ @overload
44
+ def __len__[N: IntVar, M: IntVar](self: ndarray[[N, M]]) -> Int[N]: ...
45
+ # TODO(stroxler): This overload does not bind: paired integer-array indexing
46
+ # infers a gradual shape rather than `[I]`, and float indices are not
47
+ # rejected. `test_indexing.py` covers both cases at runtime only.
48
+ def __getitem__[
49
+ N: IntVar,
50
+ M: IntVar,
51
+ I: IntVar,
52
+ RowIndexScalar: (int32, int64, intp),
53
+ ColumnIndexScalar: (int32, int64, intp),
54
+ ](
55
+ self: ndarray[[N, M], DType],
56
+ key: tuple[
57
+ ndarray[[I], _dtype[RowIndexScalar]],
58
+ ndarray[[I], _dtype[ColumnIndexScalar]],
59
+ ],
60
+ ) -> ndarray[[I], DType]: ...
61
+ # Only 2-D transpose is modeled for the NumPy shape-stub MVP.
62
+ @property
63
+ def T[N: IntVar, P: IntVar](
64
+ self: ndarray[[N, P], DType],
65
+ ) -> ndarray[[P, N], DType]: ...
66
+ @overload
67
+ def __add__(self, other: int | float) -> ndarray[Shape, DType]: ...
68
+ @overload
69
+ def __add__[OtherShape: _Shape](
70
+ self, other: ndarray[OtherShape]
71
+ ) -> ndarray[broadcast(Shape, OtherShape), DType]: ...
72
+ @overload
73
+ def __radd__(self, other: int | float) -> ndarray[Shape, DType]: ...
74
+ @overload
75
+ def __radd__[OtherShape: _Shape](
76
+ self, other: ndarray[OtherShape]
77
+ ) -> ndarray[broadcast(Shape, OtherShape), DType]: ...
78
+ @overload
79
+ def __sub__(self, other: int | float) -> ndarray[Shape, DType]: ...
80
+ @overload
81
+ def __sub__[OtherShape: _Shape](
82
+ self, other: ndarray[OtherShape]
83
+ ) -> ndarray[broadcast(Shape, OtherShape), DType]: ...
84
+ @overload
85
+ def __rsub__(self, other: int | float) -> ndarray[Shape, DType]: ...
86
+ @overload
87
+ def __rsub__[OtherShape: _Shape](
88
+ self, other: ndarray[OtherShape]
89
+ ) -> ndarray[broadcast(Shape, OtherShape), DType]: ...
90
+ @overload
91
+ def __truediv__(self, other: int | float) -> ndarray[Shape, DType]: ...
92
+ @overload
93
+ def __truediv__[OtherShape: _Shape](
94
+ self, other: ndarray[OtherShape]
95
+ ) -> ndarray[broadcast(Shape, OtherShape), DType]: ...
96
+ @overload
97
+ def __rtruediv__(self, other: int | float) -> ndarray[Shape, DType]: ...
98
+ @overload
99
+ def __rtruediv__[OtherShape: _Shape](
100
+ self, other: ndarray[OtherShape]
101
+ ) -> ndarray[broadcast(Shape, OtherShape), DType]: ...
102
+ @overload
103
+ def __mul__(self, other: int | float) -> ndarray[Shape, DType]: ...
104
+ @overload
105
+ def __mul__[OtherShape: _Shape](
106
+ self, other: ndarray[OtherShape]
107
+ ) -> ndarray[broadcast(Shape, OtherShape), DType]: ...
108
+ @overload
109
+ def __rmul__(self, other: int | float) -> ndarray[Shape, DType]: ...
110
+ @overload
111
+ def __rmul__[OtherShape: _Shape](
112
+ self, other: ndarray[OtherShape]
113
+ ) -> ndarray[broadcast(Shape, OtherShape), DType]: ...
114
+ @overload
115
+ def __floordiv__(self, other: int | float) -> ndarray[Shape, DType]: ...
116
+ @overload
117
+ def __floordiv__[OtherShape: _Shape](
118
+ self, other: ndarray[OtherShape]
119
+ ) -> ndarray[broadcast(Shape, OtherShape), DType]: ...
120
+ @overload
121
+ def __rfloordiv__(self, other: int | float) -> ndarray[Shape, DType]: ...
122
+ @overload
123
+ def __rfloordiv__[OtherShape: _Shape](
124
+ self, other: ndarray[OtherShape]
125
+ ) -> ndarray[broadcast(Shape, OtherShape), DType]: ...
126
+ @overload
127
+ def __mod__(self, other: int | float) -> ndarray[Shape, DType]: ...
128
+ @overload
129
+ def __mod__[OtherShape: _Shape](
130
+ self, other: ndarray[OtherShape]
131
+ ) -> ndarray[broadcast(Shape, OtherShape), DType]: ...
132
+ @overload
133
+ def __rmod__(self, other: int | float) -> ndarray[Shape, DType]: ...
134
+ @overload
135
+ def __rmod__[OtherShape: _Shape](
136
+ self, other: ndarray[OtherShape]
137
+ ) -> ndarray[broadcast(Shape, OtherShape), DType]: ...
138
+ def __neg__(self) -> ndarray[Shape, DType]: ...
139
+ def __pos__(self) -> ndarray[Shape, DType]: ...
140
+ @overload
141
+ def __pow__(self, other: int | float) -> ndarray[Shape, DType]: ...
142
+ @overload
143
+ def __pow__[OtherShape: _Shape](
144
+ self, other: ndarray[OtherShape]
145
+ ) -> ndarray[broadcast(Shape, OtherShape), DType]: ...
146
+ @overload
147
+ def __rpow__(self, other: int | float) -> ndarray[Shape, DType]: ...
148
+ @overload
149
+ def __rpow__[OtherShape: _Shape](
150
+ self, other: ndarray[OtherShape]
151
+ ) -> ndarray[broadcast(Shape, OtherShape), DType]: ...
152
+ # TODO(stroxler): Share the DSL-backed `np.matmul` rule once operator methods can invoke it.
153
+ def __matmul__[N: IntVar, M: IntVar, P: IntVar](
154
+ self: ndarray[[N, M], DType],
155
+ other: ndarray[[M, P]],
156
+ ) -> ndarray[[N, P], DType]: ...
157
+ # TODO(stroxler): Share the DSL-backed free-function reduction rules with bound methods.
158
+ # These narrow method bridges currently cover the shapes used by the example corpus.
159
+ @overload
160
+ def mean[N: IntVar, M: IntVar](
161
+ self: ndarray[[N, M], DType],
162
+ axis: Literal[0],
163
+ *,
164
+ keepdims: Literal[False] = False,
165
+ ) -> ndarray[[M], DType]: ...
166
+ @overload
167
+ def mean[N: IntVar](
168
+ self: ndarray[[N], DType],
169
+ ) -> ndarray[[], DType]: ...
170
+ @overload
171
+ def sum[N: IntVar, M: IntVar](
172
+ self: ndarray[[N, M], DType],
173
+ axis: Literal[1],
174
+ *,
175
+ keepdims: Literal[True],
176
+ ) -> ndarray[[N, 1], DType]: ...
177
+ @overload
178
+ def sum[N: IntVar, M: IntVar, K: IntVar](
179
+ self: ndarray[[N, M, K], DType],
180
+ axis: Literal[1],
181
+ *,
182
+ keepdims: Literal[False] = False,
183
+ ) -> ndarray[[N, K], DType]: ...
184
+ def max[N: IntVar, M: IntVar](
185
+ self: ndarray[[N, M], DType],
186
+ axis: Literal[1],
187
+ *,
188
+ keepdims: Literal[True],
189
+ ) -> ndarray[[N, 1], DType]: ...
190
+
191
+ def abs[Shape: _Shape](x: ndarray[Shape]) -> ndarray[Shape]: ...
192
+ def exp[Shape: _Shape](x: ndarray[Shape]) -> ndarray[Shape]: ...
193
+ def log[Shape: _Shape](x: ndarray[Shape]) -> ndarray[Shape]: ...
194
+ def log2[Shape: _Shape](x: ndarray[Shape]) -> ndarray[Shape]: ...
195
+ def log10[Shape: _Shape](x: ndarray[Shape]) -> ndarray[Shape]: ...
196
+ def sqrt[Shape: _Shape](x: ndarray[Shape]) -> ndarray[Shape]: ...
197
+ def power[Shape: _Shape](x1: ndarray[Shape], x2: int | float, /) -> ndarray[Shape]: ...
198
+ def minimum[Shape1: _Shape, Shape2: _Shape](
199
+ x1: ndarray[Shape1, Any], x2: ndarray[Shape2, Any], /
200
+ ) -> ndarray[broadcast(Shape1, Shape2)]: ...
201
+ def maximum[Shape1: _Shape, Shape2: _Shape](
202
+ x1: ndarray[Shape1, Any], x2: ndarray[Shape2, Any], /
203
+ ) -> ndarray[broadcast(Shape1, Shape2)]: ...
204
+ def arctan2[Shape1: _Shape, Shape2: _Shape](
205
+ x1: ndarray[Shape1, Any], x2: ndarray[Shape2, Any], /
206
+ ) -> ndarray[broadcast(Shape1, Shape2)]: ...
207
+ def sin[Shape: _Shape](x: ndarray[Shape]) -> ndarray[Shape]: ...
208
+ def cos[Shape: _Shape](x: ndarray[Shape]) -> ndarray[Shape]: ...
209
+ def tan[Shape: _Shape](x: ndarray[Shape]) -> ndarray[Shape]: ...
210
+ def arcsin[Shape: _Shape](x: ndarray[Shape]) -> ndarray[Shape]: ...
211
+ def floor[Shape: _Shape](x: ndarray[Shape]) -> ndarray[Shape]: ...
212
+ def ceil[Shape: _Shape](x: ndarray[Shape]) -> ndarray[Shape]: ...
213
+ def round[Shape: _Shape](x: ndarray[Shape]) -> ndarray[Shape]: ...
214
+ def trunc[Shape: _Shape](x: ndarray[Shape]) -> ndarray[Shape]: ...
215
+ def clip[Shape: _Shape](
216
+ a: ndarray[Shape], a_min: int | float, a_max: int | float
217
+ ) -> ndarray[Shape]: ...
218
+ def negative[Shape: _Shape](x: ndarray[Shape]) -> ndarray[Shape]: ...
219
+ def fill_diagonal[N: IntVar, DType](
220
+ a: ndarray[[N, N], DType],
221
+ val: Any,
222
+ wrap: bool = False,
223
+ ) -> None: ...
224
+ @overload
225
+ def diag[N: IntVar, DType, K: Flag[int] = 0](
226
+ v: ndarray[[N], DType], k: K = 0
227
+ ) -> ndarray[[diag_extent(N, K), diag_extent(N, K)], DType]: ...
228
+
229
+ # TODO(stroxler): Model the shape arithmetic here; we can do better than `int`.
230
+ @overload
231
+ def diag[M: IntVar, N: IntVar, DType](
232
+ v: ndarray[[M, N], DType], k: int = 0
233
+ ) -> ndarray[[int], DType]: ...
234
+
235
+ # Trailing fallback for ranks the precise overloads do not model, so their dtype survives
236
+ # instead of degrading to `Any`. The parameter shape is a type variable rather than
237
+ # `_AnyShape`: a gradual parameter shape would also match known-rank arguments whose dtype is
238
+ # gradual, and that ambiguity collapses their precise result to a gradual shape.
239
+ # The result is spelled `IntTuple`, the shape bound itself, rather than `_AnyShape`:
240
+ # an unbounded tuple is not a valid shaped-array carrier. Both infer the same shape.
241
+ @overload
242
+ def diag[S: _Shape, DType](
243
+ v: ndarray[S, DType], k: int = 0
244
+ ) -> ndarray[IntTuple, DType]: ...
245
+ def arange[N: IntVar](stop: Int[N], /) -> ndarray[[N], dtype[intp]]: ...
246
+ @overload
247
+ def expand_dims[N: IntVar, M: IntVar, DType](
248
+ a: ndarray[[N, M], DType],
249
+ axis: Literal[0, -3],
250
+ ) -> ndarray[[1, N, M], DType]: ...
251
+ @overload
252
+ def expand_dims[N: IntVar, M: IntVar, DType](
253
+ a: ndarray[[N, M], DType],
254
+ axis: Literal[1, -2],
255
+ ) -> ndarray[[N, 1, M], DType]: ...
256
+ @overload
257
+ def expand_dims[N: IntVar, M: IntVar, DType](
258
+ a: ndarray[[N, M], DType],
259
+ axis: Literal[2, -1],
260
+ ) -> ndarray[[N, M, 1], DType]: ...
261
+
262
+ # These stubs track reduction shapes but leave reduction dtype gradual.
263
+ def sum[
264
+ Shape: _Shape,
265
+ DType,
266
+ Axis: Flag[_Axis],
267
+ KeepDims: Flag[bool],
268
+ ](
269
+ a: ndarray[Shape, DType], axis: Axis = None, *, keepdims: KeepDims = False
270
+ ) -> ndarray[reduce_shape(Shape, Axis, KeepDims), Any]: ...
271
+ def mean[
272
+ Shape: _Shape,
273
+ DType,
274
+ Axis: Flag[_Axis],
275
+ KeepDims: Flag[bool],
276
+ ](
277
+ a: ndarray[Shape, DType], axis: Axis = None, *, keepdims: KeepDims = False
278
+ ) -> ndarray[reduce_shape(Shape, Axis, KeepDims), Any]: ...
279
+ def min[
280
+ Shape: _Shape,
281
+ DType,
282
+ Axis: Flag[_Axis],
283
+ KeepDims: Flag[bool],
284
+ ](
285
+ a: ndarray[Shape, DType], axis: Axis = None, *, keepdims: KeepDims = False
286
+ ) -> ndarray[reduce_shape(Shape, Axis, KeepDims), Any]: ...
287
+ def max[
288
+ Shape: _Shape,
289
+ DType,
290
+ Axis: Flag[_Axis],
291
+ KeepDims: Flag[bool],
292
+ ](
293
+ a: ndarray[Shape, DType], axis: Axis = None, *, keepdims: KeepDims = False
294
+ ) -> ndarray[reduce_shape(Shape, Axis, KeepDims), Any]: ...
295
+ @overload
296
+ def argmin[N: IntVar, M: IntVar](
297
+ a: ndarray[[N, M]],
298
+ axis: Literal[0, -2],
299
+ *,
300
+ keepdims: Literal[False] = False,
301
+ ) -> ndarray[[M], dtype[intp]]: ...
302
+ @overload
303
+ def argmin[N: IntVar, M: IntVar](
304
+ a: ndarray[[N, M]],
305
+ axis: Literal[1, -1],
306
+ *,
307
+ keepdims: Literal[False] = False,
308
+ ) -> ndarray[[N], dtype[intp]]: ...
309
+
310
+ # NumPy uses the typed DSL for this rule; Torch still uses the legacy shaped-array
311
+ # mechanism. This MVP models only two-dimensional inputs. The result dtype stays
312
+ # gradual because dtype promotion is not modeled, while `ndarray.__matmul__`
313
+ # carries the left operand's dtype.
314
+ def matmul[LeftShape: _Shape, RightShape: _Shape](
315
+ a: ndarray[LeftShape], b: ndarray[RightShape], /
316
+ ) -> ndarray[matmul_shape(LeftShape, RightShape), Any]: ...
317
+
318
+ # TODO(stroxler): Replace these finite tuple-shape constructor overloads with a
319
+ # generic `Shape: tuple[int, ...]` overload once carrier shapes flow through
320
+ # downstream shaped-array operations without degrading to unknown.
321
+ @overload
322
+ def zeros[N: IntVar, ScalarT: generic](
323
+ shape: Int[N], dtype: type[ScalarT], order: str = ...
324
+ ) -> ndarray[[N], dtype[ScalarT]]: ...
325
+ @overload
326
+ def zeros[N: IntVar, ScalarT: generic](
327
+ shape: IntTuple[N], dtype: type[ScalarT], order: str = ...
328
+ ) -> ndarray[[N], dtype[ScalarT]]: ...
329
+ @overload
330
+ def zeros[N: IntVar, M: IntVar, ScalarT: generic](
331
+ shape: IntTuple[N, M], dtype: type[ScalarT], order: str = ...
332
+ ) -> ndarray[[N, M], dtype[ScalarT]]: ...
333
+ @overload
334
+ def zeros[N: IntVar, ScalarT: generic](
335
+ shape: Int[N], dtype: dtype[ScalarT], order: str = ...
336
+ ) -> ndarray[[N], dtype[ScalarT]]: ...
337
+ @overload
338
+ def zeros[N: IntVar, ScalarT: generic](
339
+ shape: IntTuple[N], dtype: dtype[ScalarT], order: str = ...
340
+ ) -> ndarray[[N], dtype[ScalarT]]: ...
341
+ @overload
342
+ def zeros[N: IntVar, M: IntVar, ScalarT: generic](
343
+ shape: IntTuple[N, M], dtype: dtype[ScalarT], order: str = ...
344
+ ) -> ndarray[[N, M], dtype[ScalarT]]: ...
345
+ @overload
346
+ def zeros[N: IntVar](
347
+ shape: Int[N], dtype: None = ..., order: str = ...
348
+ ) -> ndarray[[N], dtype[float64]]: ...
349
+ @overload
350
+ def zeros[N: IntVar](
351
+ shape: IntTuple[N], dtype: None = ..., order: str = ...
352
+ ) -> ndarray[[N], dtype[float64]]: ...
353
+ @overload
354
+ def zeros[N: IntVar, M: IntVar](
355
+ shape: IntTuple[N, M], dtype: None = ..., order: str = ...
356
+ ) -> ndarray[[N, M], dtype[float64]]: ...
357
+ @overload
358
+ def zeros[N: IntVar](shape: Int[N], dtype: Any, order: str = ...) -> ndarray[[N]]: ...
359
+ @overload
360
+ def zeros[N: IntVar](
361
+ shape: IntTuple[N], dtype: Any, order: str = ...
362
+ ) -> ndarray[[N]]: ...
363
+ @overload
364
+ def zeros[N: IntVar, M: IntVar](
365
+ shape: IntTuple[N, M], dtype: Any, order: str = ...
366
+ ) -> ndarray[[N, M]]: ...
367
+ @overload
368
+ def ones[N: IntVar, ScalarT: generic](
369
+ shape: Int[N], dtype: type[ScalarT], order: str = ...
370
+ ) -> ndarray[[N], dtype[ScalarT]]: ...
371
+ @overload
372
+ def ones[N: IntVar, ScalarT: generic](
373
+ shape: IntTuple[N], dtype: type[ScalarT], order: str = ...
374
+ ) -> ndarray[[N], dtype[ScalarT]]: ...
375
+ @overload
376
+ def ones[N: IntVar, M: IntVar, ScalarT: generic](
377
+ shape: IntTuple[N, M], dtype: type[ScalarT], order: str = ...
378
+ ) -> ndarray[[N, M], dtype[ScalarT]]: ...
379
+ @overload
380
+ def ones[N: IntVar, ScalarT: generic](
381
+ shape: Int[N], dtype: dtype[ScalarT], order: str = ...
382
+ ) -> ndarray[[N], dtype[ScalarT]]: ...
383
+ @overload
384
+ def ones[N: IntVar, ScalarT: generic](
385
+ shape: IntTuple[N], dtype: dtype[ScalarT], order: str = ...
386
+ ) -> ndarray[[N], dtype[ScalarT]]: ...
387
+ @overload
388
+ def ones[N: IntVar, M: IntVar, ScalarT: generic](
389
+ shape: IntTuple[N, M], dtype: dtype[ScalarT], order: str = ...
390
+ ) -> ndarray[[N, M], dtype[ScalarT]]: ...
391
+ @overload
392
+ def ones[N: IntVar](
393
+ shape: Int[N], dtype: None = ..., order: str = ...
394
+ ) -> ndarray[[N], dtype[float64]]: ...
395
+ @overload
396
+ def ones[N: IntVar](
397
+ shape: IntTuple[N], dtype: None = ..., order: str = ...
398
+ ) -> ndarray[[N], dtype[float64]]: ...
399
+ @overload
400
+ def ones[N: IntVar, M: IntVar](
401
+ shape: IntTuple[N, M], dtype: None = ..., order: str = ...
402
+ ) -> ndarray[[N, M], dtype[float64]]: ...
403
+ @overload
404
+ def ones[N: IntVar](shape: Int[N], dtype: Any, order: str = ...) -> ndarray[[N]]: ...
405
+ @overload
406
+ def ones[N: IntVar](
407
+ shape: IntTuple[N], dtype: Any, order: str = ...
408
+ ) -> ndarray[[N]]: ...
409
+ @overload
410
+ def ones[N: IntVar, M: IntVar](
411
+ shape: IntTuple[N, M], dtype: Any, order: str = ...
412
+ ) -> ndarray[[N, M]]: ...
413
+ @overload
414
+ def full[N: IntVar, ScalarT: generic](
415
+ shape: Int[N],
416
+ fill_value: Any,
417
+ dtype: type[ScalarT],
418
+ order: str = ...,
419
+ ) -> ndarray[[N], dtype[ScalarT]]: ...
420
+ @overload
421
+ def full[N: IntVar, ScalarT: generic](
422
+ shape: IntTuple[N],
423
+ fill_value: Any,
424
+ dtype: type[ScalarT],
425
+ order: str = ...,
426
+ ) -> ndarray[[N], dtype[ScalarT]]: ...
427
+ @overload
428
+ def full[N: IntVar, M: IntVar, ScalarT: generic](
429
+ shape: IntTuple[N, M],
430
+ fill_value: Any,
431
+ dtype: type[ScalarT],
432
+ order: str = ...,
433
+ ) -> ndarray[[N, M], dtype[ScalarT]]: ...
434
+ @overload
435
+ def full[N: IntVar, ScalarT: generic](
436
+ shape: Int[N],
437
+ fill_value: Any,
438
+ dtype: dtype[ScalarT],
439
+ order: str = ...,
440
+ ) -> ndarray[[N], dtype[ScalarT]]: ...
441
+ @overload
442
+ def full[N: IntVar, ScalarT: generic](
443
+ shape: IntTuple[N],
444
+ fill_value: Any,
445
+ dtype: dtype[ScalarT],
446
+ order: str = ...,
447
+ ) -> ndarray[[N], dtype[ScalarT]]: ...
448
+ @overload
449
+ def full[N: IntVar, M: IntVar, ScalarT: generic](
450
+ shape: IntTuple[N, M],
451
+ fill_value: Any,
452
+ dtype: dtype[ScalarT],
453
+ order: str = ...,
454
+ ) -> ndarray[[N, M], dtype[ScalarT]]: ...
455
+ @overload
456
+ def full[N: IntVar](
457
+ shape: Int[N], fill_value: Any, dtype: Any = ..., order: str = ...
458
+ ) -> ndarray[[N]]: ...
459
+ @overload
460
+ def full[N: IntVar](
461
+ shape: IntTuple[N], fill_value: Any, dtype: Any = ..., order: str = ...
462
+ ) -> ndarray[[N]]: ...
463
+ @overload
464
+ def full[N: IntVar, M: IntVar](
465
+ shape: IntTuple[N, M],
466
+ fill_value: Any,
467
+ dtype: Any = ...,
468
+ order: str = ...,
469
+ ) -> ndarray[[N, M]]: ...
470
+ @overload
471
+ def empty[N: IntVar, ScalarT: generic](
472
+ shape: Int[N], dtype: type[ScalarT], order: str = ...
473
+ ) -> ndarray[[N], dtype[ScalarT]]: ...
474
+ @overload
475
+ def empty[N: IntVar, ScalarT: generic](
476
+ shape: IntTuple[N], dtype: type[ScalarT], order: str = ...
477
+ ) -> ndarray[[N], dtype[ScalarT]]: ...
478
+ @overload
479
+ def empty[N: IntVar, M: IntVar, ScalarT: generic](
480
+ shape: IntTuple[N, M], dtype: type[ScalarT], order: str = ...
481
+ ) -> ndarray[[N, M], dtype[ScalarT]]: ...
482
+ @overload
483
+ def empty[N: IntVar, ScalarT: generic](
484
+ shape: Int[N], dtype: dtype[ScalarT], order: str = ...
485
+ ) -> ndarray[[N], dtype[ScalarT]]: ...
486
+ @overload
487
+ def empty[N: IntVar, ScalarT: generic](
488
+ shape: IntTuple[N], dtype: dtype[ScalarT], order: str = ...
489
+ ) -> ndarray[[N], dtype[ScalarT]]: ...
490
+ @overload
491
+ def empty[N: IntVar, M: IntVar, ScalarT: generic](
492
+ shape: IntTuple[N, M], dtype: dtype[ScalarT], order: str = ...
493
+ ) -> ndarray[[N, M], dtype[ScalarT]]: ...
494
+ @overload
495
+ def empty[N: IntVar](
496
+ shape: Int[N], dtype: None = ..., order: str = ...
497
+ ) -> ndarray[[N], dtype[float64]]: ...
498
+ @overload
499
+ def empty[N: IntVar](
500
+ shape: IntTuple[N], dtype: None = ..., order: str = ...
501
+ ) -> ndarray[[N], dtype[float64]]: ...
502
+ @overload
503
+ def empty[N: IntVar, M: IntVar](
504
+ shape: IntTuple[N, M], dtype: None = ..., order: str = ...
505
+ ) -> ndarray[[N, M], dtype[float64]]: ...
506
+ @overload
507
+ def empty[N: IntVar](shape: Int[N], dtype: Any, order: str = ...) -> ndarray[[N]]: ...
508
+ @overload
509
+ def empty[N: IntVar](
510
+ shape: IntTuple[N], dtype: Any, order: str = ...
511
+ ) -> ndarray[[N]]: ...
512
+ @overload
513
+ def empty[N: IntVar, M: IntVar](
514
+ shape: IntTuple[N, M], dtype: Any, order: str = ...
515
+ ) -> ndarray[[N, M]]: ...
516
+ @overload
517
+ def eye[N: IntVar, ScalarT: generic](
518
+ N: Int[N], M: None = ..., k: int = ..., *, dtype: type[ScalarT], order: str = ...
519
+ ) -> ndarray[[N, N], dtype[ScalarT]]: ...
520
+ @overload
521
+ def eye[N: IntVar, ScalarT: generic](
522
+ N: Int[N], M: None, k: int, dtype: type[ScalarT], order: str = ...
523
+ ) -> ndarray[[N, N], dtype[ScalarT]]: ...
524
+ @overload
525
+ def eye[N: IntVar, ScalarT: generic](
526
+ N: Int[N],
527
+ M: None = ...,
528
+ k: int = ...,
529
+ *,
530
+ dtype: dtype[ScalarT],
531
+ order: str = ...,
532
+ ) -> ndarray[[N, N], dtype[ScalarT]]: ...
533
+ @overload
534
+ def eye[N: IntVar, ScalarT: generic](
535
+ N: Int[N], M: None, k: int, dtype: dtype[ScalarT], order: str = ...
536
+ ) -> ndarray[[N, N], dtype[ScalarT]]: ...
537
+ @overload
538
+ def eye[N: IntVar](
539
+ N: Int[N], M: None = ..., k: int = ..., dtype: None = ..., order: str = ...
540
+ ) -> ndarray[[N, N], dtype[float64]]: ...
541
+ @overload
542
+ def eye[N: IntVar](
543
+ N: Int[N], M: None = ..., k: int = ..., dtype: Any = ..., order: str = ...
544
+ ) -> ndarray[[N, N]]: ...
545
+ @overload
546
+ def identity[N: IntVar, ScalarT: generic](
547
+ n: Int[N], dtype: type[ScalarT], *, like: Any = ...
548
+ ) -> ndarray[[N, N], dtype[ScalarT]]: ...
549
+ @overload
550
+ def identity[N: IntVar, ScalarT: generic](
551
+ n: Int[N], dtype: dtype[ScalarT], *, like: Any = ...
552
+ ) -> ndarray[[N, N], dtype[ScalarT]]: ...
553
+ @overload
554
+ def identity[N: IntVar](
555
+ n: Int[N], dtype: None = ..., *, like: Any = ...
556
+ ) -> ndarray[[N, N], dtype[float64]]: ...
557
+ @overload
558
+ def identity[N: IntVar](
559
+ n: Int[N], dtype: Any, *, like: Any = ...
560
+ ) -> ndarray[[N, N]]: ...
@@ -0,0 +1,64 @@
1
+ # Copyright (c) Meta Platforms, Inc. and affiliates.
2
+ #
3
+ # This source code is licensed under the MIT license found in the
4
+ # LICENSE file in the root directory of this source tree.
5
+
6
+ import shape_extensions.dsl as dsl
7
+ from shape_extensions import Int, IntTuple, type_shape_dsl_function
8
+
9
+ @type_shape_dsl_function
10
+ def int_min(a: Int, b: Int) -> Int:
11
+ if a == b:
12
+ return a
13
+ if dsl.is_concrete_int(a) and dsl.is_concrete_int(b):
14
+ if a < b:
15
+ return a
16
+ return b
17
+ return dsl.Int.gradual()
18
+
19
+ @type_shape_dsl_function
20
+ def diag_extent(n: Int, k: int) -> Int:
21
+ # Non-literal Flag arguments become gradual before the DSL body is evaluated.
22
+ if k < 0:
23
+ return n - k
24
+ return n + k
25
+
26
+ @type_shape_dsl_function
27
+ def matmul_shape(left: IntTuple, right: IntTuple) -> IntTuple:
28
+ if len(left) != 2 or len(right) != 2:
29
+ return dsl.Invalid("matmul expects 2-D arrays")
30
+ left_inner = left[1]
31
+ right_inner = right[0]
32
+ if (
33
+ dsl.is_concrete_int(left_inner)
34
+ and dsl.is_concrete_int(right_inner)
35
+ and left_inner != right_inner
36
+ ):
37
+ return dsl.Invalid("matmul inner dimensions must match")
38
+ return dsl.IntTuple((left[0], right[1]))
39
+
40
+ @type_shape_dsl_function
41
+ def reduce_shape(
42
+ shape: IntTuple,
43
+ axis: int | tuple[int, ...] | None,
44
+ keepdims: bool,
45
+ ) -> IntTuple:
46
+ if axis is None:
47
+ axes = range(len(shape))
48
+ elif dsl.is_int_value(axis):
49
+ axes = (axis,)
50
+ else:
51
+ axes = axis
52
+ # The DSL does not support unary negation of a Flag integer.
53
+ if any(item < 0 - len(shape) or item >= len(shape) for item in axes):
54
+ return dsl.Invalid("axis out of bounds")
55
+ normalized = tuple(item + len(shape) if item < 0 else item for item in axes)
56
+ if any(normalized.count(item) > 1 for item in normalized):
57
+ return dsl.Invalid("duplicate axis")
58
+ if keepdims:
59
+ return dsl.IntTuple(
60
+ (1 if index in normalized else shape[index] for index in range(len(shape)))
61
+ )
62
+ return dsl.IntTuple(
63
+ (shape[index] for index in range(len(shape)) if index not in normalized)
64
+ )
@@ -0,0 +1,43 @@
1
+ # Copyright (c) Meta Platforms, Inc. and affiliates.
2
+ #
3
+ # This source code is licensed under the MIT license found in the
4
+ # LICENSE file in the root directory of this source tree.
5
+
6
+ from typing import Literal, overload
7
+
8
+ from numpy._shapes import int_min
9
+ from shape_extensions import IntVar
10
+
11
+ from .. import ndarray
12
+
13
+ # MVP shape surface only; NumPy dtype promotion is intentionally not modeled.
14
+ @overload
15
+ def solve[N: IntVar, DType](
16
+ a: ndarray[[N, N], DType],
17
+ b: ndarray[[N]],
18
+ ) -> ndarray[[N], DType]: ...
19
+ @overload
20
+ def solve[N: IntVar, K: IntVar, DType](
21
+ a: ndarray[[N, N], DType],
22
+ b: ndarray[[N, K]],
23
+ ) -> ndarray[[N, K], DType]: ...
24
+ def norm[N: IntVar, M: IntVar, DType](
25
+ x: ndarray[[N, M, 3], DType],
26
+ axis: Literal[-1],
27
+ keepdims: Literal[True],
28
+ ) -> ndarray[[N, M, 1], DType]: ...
29
+ def eigh[N: IntVar, DType](
30
+ a: ndarray[[N, N], DType],
31
+ ) -> tuple[ndarray[[N], DType], ndarray[[N, N], DType]]: ...
32
+ def svd[M: IntVar, N: IntVar, DType](
33
+ a: ndarray[[M, N], DType],
34
+ # NumPy defaults to full SVD; this MVP accepts only the reduced form needed
35
+ # by PCA-style demos.
36
+ full_matrices: Literal[False],
37
+ compute_uv: Literal[True] = True,
38
+ hermitian: Literal[False] = False,
39
+ ) -> tuple[
40
+ ndarray[[M, int_min(M, N)], DType],
41
+ ndarray[[int_min(M, N)], DType],
42
+ ndarray[[int_min(M, N), N], DType],
43
+ ]: ...
@@ -0,0 +1 @@
1
+ partial
@@ -0,0 +1,17 @@
1
+ # Copyright (c) Meta Platforms, Inc. and affiliates.
2
+ #
3
+ # This source code is licensed under the MIT license found in the
4
+ # LICENSE file in the root directory of this source tree.
5
+
6
+ from typing import overload
7
+
8
+ from shape_extensions import Int, IntVar
9
+
10
+ from .. import dtype, float64, ndarray
11
+
12
+ @overload
13
+ def randn[N: IntVar](d0: Int[N], /) -> ndarray[[N], dtype[float64]]: ...
14
+ @overload
15
+ def randn[N: IntVar, M: IntVar](
16
+ d0: Int[N], d1: Int[M], /
17
+ ) -> ndarray[[N, M], dtype[float64]]: ...
@@ -0,0 +1,32 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "pyrefly-numpy-stubs"
7
+ description = "NumPy type stubs with array-shape tracking, maintained by Pyrefly"
8
+ readme = "README.md"
9
+ requires-python = ">=3.12"
10
+ license = { file = "LICENSE" }
11
+ version = "1.3.0.dev3"
12
+ keywords = ["typechecker", "typechecking", "stubs", "numpy"]
13
+ classifiers = [
14
+ "Development Status :: 4 - Beta",
15
+ "License :: OSI Approved :: MIT License",
16
+ "Programming Language :: Python",
17
+ "Programming Language :: Python :: 3",
18
+ "Typing :: Stubs Only",
19
+ ]
20
+ dependencies = [
21
+ "pyrefly-shape-extensions==1.3.0.dev3",
22
+ ]
23
+
24
+ [project.urls]
25
+ homepage = "https://pyrefly.org"
26
+ documentation = "https://pyrefly.org/en/docs/"
27
+
28
+ [tool.hatch.build.targets.wheel]
29
+ only-include = ["numpy-stubs"]
30
+
31
+ [tool.hatch.build.targets.sdist]
32
+ include = ["numpy-stubs/", "README.md", "LICENSE"]