pyrefly-shape-extensions 1.3.0.dev4__py3-none-any.whl → 1.4.0.dev1__py3-none-any.whl
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.
- {pyrefly_shape_extensions-1.3.0.dev4.dist-info → pyrefly_shape_extensions-1.4.0.dev1.dist-info}/METADATA +8 -3
- pyrefly_shape_extensions-1.4.0.dev1.dist-info/RECORD +8 -0
- {pyrefly_shape_extensions-1.3.0.dev4.dist-info → pyrefly_shape_extensions-1.4.0.dev1.dist-info}/WHEEL +1 -1
- shape_extensions/__init__.py +116 -89
- shape_extensions/dsl.py +20 -0
- pyrefly_shape_extensions-1.3.0.dev4.dist-info/RECORD +0 -8
- {pyrefly_shape_extensions-1.3.0.dev4.dist-info → pyrefly_shape_extensions-1.4.0.dev1.dist-info}/licenses/LICENSE +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: pyrefly-shape-extensions
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.4.0.dev1
|
|
4
4
|
Summary: Shape typing primitives and DSL for Pyrefly tensor shape tracking
|
|
5
5
|
Project-URL: homepage, https://pyrefly.org
|
|
6
6
|
Project-URL: documentation, https://pyrefly.org/en/docs/
|
|
@@ -31,7 +31,7 @@ Classifier: Development Status :: 4 - Beta
|
|
|
31
31
|
Classifier: License :: OSI Approved :: MIT License
|
|
32
32
|
Classifier: Programming Language :: Python
|
|
33
33
|
Classifier: Programming Language :: Python :: 3
|
|
34
|
-
Requires-Python: >=3.
|
|
34
|
+
Requires-Python: >=3.10
|
|
35
35
|
Description-Content-Type: text/markdown
|
|
36
36
|
|
|
37
37
|
# pyrefly-shape-extensions
|
|
@@ -41,7 +41,12 @@ Runtime helpers for Pyrefly tensor shape annotations.
|
|
|
41
41
|
This package provides the lightweight `shape_extensions` module used by
|
|
42
42
|
Pyrefly's tensor shape stubs. It defines runtime no-op versions of the shape
|
|
43
43
|
typing primitives so annotations such as `Tensor[B, T]`, `IntVar("B")`, and
|
|
44
|
-
`assert_shape(x, (2, 3))` can be evaluated by Python while Pyrefly uses the
|
|
44
|
+
`assert_shape(x.shape, (2, 3))` can be evaluated by Python while Pyrefly uses the
|
|
45
45
|
corresponding stubs for static shape checking.
|
|
46
46
|
|
|
47
|
+
`RegularNestedList[Shape, Domain]` represents regular (non-jagged) nested list
|
|
48
|
+
literals; for example, `[[1, 2], [3, 4]]` binds `Shape` to `[2, 2]`. Unsupported
|
|
49
|
+
containers and irregular literals use ordinary typing and any fallback overload
|
|
50
|
+
supplied by the consumer.
|
|
51
|
+
|
|
47
52
|
The package is versioned in lockstep with Pyrefly.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
shape_extensions/__init__.py,sha256=Nh_lNmpY9MBSx30N_avb6kfdzyWWC58F-d1iViBGGJA,13266
|
|
2
|
+
shape_extensions/dsl.py,sha256=R9-o0zfj7HCbsOhu0AmAeQ5JBrlfhv7mriDx2lbpntQ,3151
|
|
3
|
+
shape_extensions/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
|
|
4
|
+
shape_extensions/torchscript.py,sha256=Jk8Mv3dEEPGdkH6EIaHOzc11VvGwvq-o1eDELwWpUE8,12914
|
|
5
|
+
pyrefly_shape_extensions-1.4.0.dev1.dist-info/METADATA,sha256=UYr9k_Z_gzS0UFEKCair3Bpp-hMXDplUUeJFgZVTiTs,2590
|
|
6
|
+
pyrefly_shape_extensions-1.4.0.dev1.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
|
|
7
|
+
pyrefly_shape_extensions-1.4.0.dev1.dist-info/licenses/LICENSE,sha256=2m03A-0Ry-Qr0hLHJZV8mNojy_8ZmMBfpLPZdtGljpM,1088
|
|
8
|
+
pyrefly_shape_extensions-1.4.0.dev1.dist-info/RECORD,,
|
shape_extensions/__init__.py
CHANGED
|
@@ -7,9 +7,8 @@
|
|
|
7
7
|
|
|
8
8
|
"""Library-agnostic shape typing primitives.
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
don't crash when evaluated by Python.
|
|
10
|
+
These definitions provide static shape information to Pyrefly while remaining
|
|
11
|
+
safe to evaluate in runtime annotations.
|
|
13
12
|
"""
|
|
14
13
|
|
|
15
14
|
import typing
|
|
@@ -25,13 +24,12 @@ __all__ = [
|
|
|
25
24
|
"Index",
|
|
26
25
|
"MapIntTuples",
|
|
27
26
|
"ProxyMethod",
|
|
27
|
+
"RegularNestedList",
|
|
28
28
|
"SymbolicArithExpr",
|
|
29
|
-
"TypeVarTuple",
|
|
30
29
|
"assert_shape",
|
|
31
30
|
"broadcast",
|
|
32
31
|
"defines_assert_shape",
|
|
33
32
|
"gufunc_broadcast",
|
|
34
|
-
"shaped_array",
|
|
35
33
|
"index_shape",
|
|
36
34
|
"type_shape_dsl_function",
|
|
37
35
|
]
|
|
@@ -89,12 +87,25 @@ def _patch_torch_if_available() -> None:
|
|
|
89
87
|
_patch_torch_if_available()
|
|
90
88
|
|
|
91
89
|
|
|
90
|
+
def _patch_jax_if_available() -> None:
|
|
91
|
+
try:
|
|
92
|
+
import jax # @manual
|
|
93
|
+
except ImportError:
|
|
94
|
+
return
|
|
95
|
+
|
|
96
|
+
if hasattr(jax, "Array") and not hasattr(jax.Array, "__class_getitem__"):
|
|
97
|
+
jax.Array.__class_getitem__ = classmethod(_return_class)
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
_patch_jax_if_available()
|
|
101
|
+
|
|
102
|
+
|
|
92
103
|
class IntTuple:
|
|
93
104
|
"""Tuple-valued shape annotation surface.
|
|
94
105
|
|
|
95
|
-
In type positions, Pyrefly treats `IntTuple` as
|
|
96
|
-
`tuple[int, ...]`. At runtime, calling it coerces any
|
|
97
|
-
tuple.
|
|
106
|
+
In type positions, Pyrefly treats `IntTuple` as a whole shape whose runtime
|
|
107
|
+
representation is `tuple[int, ...]`. At runtime, calling it coerces any
|
|
108
|
+
iterable to a plain tuple.
|
|
98
109
|
"""
|
|
99
110
|
|
|
100
111
|
def __new__(cls, iterable=()):
|
|
@@ -112,33 +123,36 @@ class IntTuples:
|
|
|
112
123
|
|
|
113
124
|
|
|
114
125
|
class Elements:
|
|
115
|
-
"""Inverse of ``tuple[Unpack[S]]``: extracts the
|
|
126
|
+
"""Inverse of ``tuple[Unpack[S]]``: extracts the dimensions from an ``IntTuple``.
|
|
116
127
|
|
|
117
128
|
In the Python typing spec, ``tuple[Unpack[Ts]]`` wraps a ``TypeVarTuple`` into a
|
|
118
|
-
concrete tuple type. ``Elements[S]`` is the conceptual inverse: given
|
|
119
|
-
|
|
129
|
+
concrete tuple type. ``Elements[S]`` is the conceptual inverse: given an ``IntTuple``
|
|
130
|
+
shape ``S``, ``*Elements[S]`` splices its dimensions into a shape position,
|
|
120
131
|
e.g. ``Array[[*Elements[S], OUT], DType]``.
|
|
121
132
|
|
|
122
133
|
This fills a gap in the current typing spec — there is no standard mechanism to
|
|
123
|
-
decompose a variadic
|
|
134
|
+
decompose a variadic shape without a ``TypeVarTuple``. Pyrefly uses the ``.pyi``
|
|
124
135
|
stub for type inference; this class exists so annotations evaluate without crashing
|
|
125
136
|
at runtime.
|
|
126
137
|
"""
|
|
127
138
|
|
|
128
|
-
def __init__(self,
|
|
129
|
-
self.
|
|
139
|
+
def __init__(self, shape):
|
|
140
|
+
self.shape = shape
|
|
130
141
|
|
|
131
|
-
def __class_getitem__(cls,
|
|
132
|
-
return cls(
|
|
142
|
+
def __class_getitem__(cls, shape):
|
|
143
|
+
return cls(shape)
|
|
133
144
|
|
|
134
145
|
def __iter__(self):
|
|
135
146
|
yield self
|
|
136
147
|
|
|
137
148
|
def __repr__(self):
|
|
138
|
-
return f"Elements[{self.
|
|
149
|
+
return f"Elements[{self.shape!r}]"
|
|
139
150
|
|
|
140
151
|
|
|
141
|
-
|
|
152
|
+
_T = typing.TypeVar("_T")
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
class Int(typing.Generic[_T]):
|
|
142
156
|
"""Symbolic integer type for dimension values.
|
|
143
157
|
|
|
144
158
|
At runtime this is a no-op generic class. The type checker uses the
|
|
@@ -148,7 +162,7 @@ class Int[T]:
|
|
|
148
162
|
pass
|
|
149
163
|
|
|
150
164
|
|
|
151
|
-
class Flag[
|
|
165
|
+
class Flag(typing.Generic[_T]):
|
|
152
166
|
"""Marker for a literal-preserving value that controls type-level evaluation."""
|
|
153
167
|
|
|
154
168
|
pass
|
|
@@ -160,12 +174,47 @@ class Index:
|
|
|
160
174
|
pass
|
|
161
175
|
|
|
162
176
|
|
|
163
|
-
class ProxyMethod[
|
|
177
|
+
class ProxyMethod(typing.Generic[_T]):
|
|
164
178
|
"""Type-checker marker for method forwarding annotations."""
|
|
165
179
|
|
|
166
180
|
pass
|
|
167
181
|
|
|
168
182
|
|
|
183
|
+
# `TypeVar` defaults require Python 3.13 at runtime, so omit them on Python 3.12.
|
|
184
|
+
if typing.TYPE_CHECKING:
|
|
185
|
+
_RegularNestedShape = typing.TypeVar(
|
|
186
|
+
"_RegularNestedShape", bound=IntTuple, default=IntTuple, covariant=True
|
|
187
|
+
)
|
|
188
|
+
_Domain = typing.TypeVar(
|
|
189
|
+
"_Domain", default=bool | int | float | complex, covariant=True
|
|
190
|
+
)
|
|
191
|
+
else:
|
|
192
|
+
_RegularNestedShape = typing.TypeVar(
|
|
193
|
+
"_RegularNestedShape", bound=IntTuple, covariant=True
|
|
194
|
+
)
|
|
195
|
+
_Domain = typing.TypeVar("_Domain", covariant=True)
|
|
196
|
+
|
|
197
|
+
|
|
198
|
+
class RegularNestedList(typing.Generic[_RegularNestedShape, _Domain]):
|
|
199
|
+
"""A regular nested list literal whose scalar leaves belong to ``Domain``.
|
|
200
|
+
|
|
201
|
+
Here, regular means the opposite of jagged or irregular: every sibling list
|
|
202
|
+
has the same shape.
|
|
203
|
+
|
|
204
|
+
Use this as a contextual parameter type for constructor-style APIs that
|
|
205
|
+
accept nested Python lists and need to infer a shape type argument. It is a
|
|
206
|
+
static marker, not the runtime type of an existing list value.
|
|
207
|
+
|
|
208
|
+
A literal such as ``[[1, 2], [3, 4]]`` binds ``Shape`` to
|
|
209
|
+
``IntTuple[2, 2]``, while ``[[1, 2], [3]]`` is jagged and therefore not
|
|
210
|
+
regular. Existing containers, starred literals, and statically jagged
|
|
211
|
+
literals use ordinary typing instead of this marker.
|
|
212
|
+
"""
|
|
213
|
+
|
|
214
|
+
def __class_getitem__(cls, params):
|
|
215
|
+
return cls
|
|
216
|
+
|
|
217
|
+
|
|
169
218
|
@dataclass(frozen=True)
|
|
170
219
|
class SymbolicArithExpr:
|
|
171
220
|
"""Runtime representation of symbolic dimension arithmetic."""
|
|
@@ -243,53 +292,63 @@ def defines_assert_shape(fn: typing.Callable) -> typing.Callable:
|
|
|
243
292
|
"""
|
|
244
293
|
Decorator that marks a function as an assert_shape helper.
|
|
245
294
|
|
|
246
|
-
Used in order to allow custom assert_shape functions if necessary
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
the `assert_shape` function of this library.
|
|
295
|
+
Used in order to allow custom assert_shape functions if necessary. A default
|
|
296
|
+
version that works for tuple-like shapes is defined in the `assert_shape`
|
|
297
|
+
function of this library.
|
|
250
298
|
"""
|
|
251
299
|
return fn
|
|
252
300
|
|
|
253
301
|
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
"""
|
|
257
|
-
At runtime, assert that x has the expected runtime shape, assuming that `x` is
|
|
258
|
-
some type like `torch.Tensor` or `np.ndarray` that has a tuple-valued
|
|
259
|
-
field `shape` indicating the shape.
|
|
302
|
+
def _check_runtime_shape(actual, shape):
|
|
303
|
+
"""Compare `actual` against `shape`, raising on a mismatch.
|
|
260
304
|
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
TODO(stroxler): for now, symbolic dimensions are skipped at runtime,
|
|
265
|
-
so in the case of a symbolic `shape` the runtime validation is only checking
|
|
266
|
-
the rank for those axes. But the static analysis will fully validate.
|
|
305
|
+
Split out from `assert_shape` so the runtime comparison reads on its own.
|
|
306
|
+
Kept private because the test harness counts calls to `assert_shape`, and a
|
|
307
|
+
public helper reachable from it would be counted twice.
|
|
267
308
|
"""
|
|
268
309
|
|
|
269
|
-
|
|
310
|
+
# Preserve legacy calls that pass an array object rather than its shape.
|
|
311
|
+
if not isinstance(actual, tuple) and hasattr(actual, "shape"):
|
|
312
|
+
actual_tuple = tuple(actual.shape)
|
|
313
|
+
else:
|
|
314
|
+
actual_tuple = tuple(actual)
|
|
270
315
|
expected = tuple(shape)
|
|
271
316
|
if any(isinstance(dim, SymbolicArithExpr) for dim in expected):
|
|
272
|
-
if len(
|
|
317
|
+
if len(actual_tuple) != len(expected):
|
|
273
318
|
raise AssertionError(
|
|
274
|
-
f"expected rank {len(expected)} for shape {expected}, got shape {
|
|
319
|
+
f"expected rank {len(expected)} for shape {expected}, got shape {actual_tuple}"
|
|
275
320
|
)
|
|
276
|
-
elif
|
|
277
|
-
raise AssertionError(f"expected shape {expected}, got {
|
|
278
|
-
return
|
|
321
|
+
elif actual_tuple != expected:
|
|
322
|
+
raise AssertionError(f"expected shape {expected}, got {actual_tuple}")
|
|
323
|
+
return actual
|
|
279
324
|
|
|
280
325
|
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
) -> typing.Callable[[type], type]:
|
|
284
|
-
"""Mark a class as carrying a shape parameter.
|
|
285
|
-
|
|
286
|
-
``builtin_indexing=False`` lets its annotated ``__getitem__`` determine the result.
|
|
326
|
+
@defines_assert_shape
|
|
327
|
+
def assert_shape(actual, shape, *, runtime=None):
|
|
287
328
|
"""
|
|
329
|
+
At runtime, assert that a tuple-like shape has the expected value.
|
|
288
330
|
|
|
289
|
-
|
|
290
|
-
|
|
331
|
+
Pyrefly will validate that the statically modeled shape matches, similar to
|
|
332
|
+
`assert_type`.
|
|
291
333
|
|
|
292
|
-
|
|
334
|
+
`shape` is the shape Pyrefly infers, and normally the library produces it too,
|
|
335
|
+
so one argument pins both behaviors. `runtime` is for the cases where the two
|
|
336
|
+
disagree: pass it the shape the library actually produces, and the runtime
|
|
337
|
+
check uses it instead of `shape`. Two things need it:
|
|
338
|
+
|
|
339
|
+
- An expression Pyrefly infers gradually: spell `shape` as `IntTuple` when it
|
|
340
|
+
has no shape at all, or as a tuple such as `(int,)` when the rank is known
|
|
341
|
+
and only a dimension is not.
|
|
342
|
+
- A known bug, where Pyrefly infers a shape the library does not produce.
|
|
343
|
+
Writing that wrong shape as `shape` documents it and makes the test fail
|
|
344
|
+
once it is fixed, rather than leaving the discrepancy unrecorded.
|
|
345
|
+
|
|
346
|
+
TODO(stroxler): for now, symbolic dimensions are skipped at runtime,
|
|
347
|
+
so in the case of a symbolic `shape` the runtime validation is only checking
|
|
348
|
+
the rank for those axes. But the static analysis will fully validate.
|
|
349
|
+
"""
|
|
350
|
+
|
|
351
|
+
return _check_runtime_shape(actual, shape if runtime is None else runtime)
|
|
293
352
|
|
|
294
353
|
|
|
295
354
|
def index_shape(_shape: IntTuple, _index: typing.Any) -> IntTuple:
|
|
@@ -319,7 +378,10 @@ class MapIntTuples:
|
|
|
319
378
|
return tuple
|
|
320
379
|
|
|
321
380
|
|
|
322
|
-
|
|
381
|
+
_F = typing.TypeVar("_F", bound=typing.Callable)
|
|
382
|
+
|
|
383
|
+
|
|
384
|
+
def type_shape_dsl_function(fn: _F) -> _F:
|
|
323
385
|
"""Runtime no-op for a user-defined type-level shape DSL function."""
|
|
324
386
|
|
|
325
387
|
return fn
|
|
@@ -394,40 +456,5 @@ class IntVar:
|
|
|
394
456
|
def __typing_subst__(self, arg):
|
|
395
457
|
return arg
|
|
396
458
|
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
"""TypeVarTuple with support for integer shape dimensions.
|
|
400
|
-
|
|
401
|
-
Like typing.TypeVarTuple but for use in tensor shape annotations.
|
|
402
|
-
Setting __class__ = typing.TypeVarTuple and providing
|
|
403
|
-
__typing_is_unpacked_typevartuple__ makes Generic[*Ns] work.
|
|
404
|
-
|
|
405
|
-
In pyrefly, shape_extensions.TypeVarTuple is treated identically to
|
|
406
|
-
typing.TypeVarTuple.
|
|
407
|
-
|
|
408
|
-
__iter__ yields self so that *Ns unpacking works in subscripts
|
|
409
|
-
like Generic[*Ns] or Tensor[*Ns, 3]. Python's star-unpacking
|
|
410
|
-
calls __iter__ on the object.
|
|
411
|
-
"""
|
|
412
|
-
|
|
413
|
-
__class__ = typing.TypeVarTuple
|
|
414
|
-
|
|
415
|
-
def __init__(self, name: str):
|
|
416
|
-
self.__name__ = name
|
|
417
|
-
self.name = name
|
|
418
|
-
|
|
419
|
-
def __repr__(self):
|
|
420
|
-
return f"*{self.name}"
|
|
421
|
-
|
|
422
|
-
def __hash__(self):
|
|
423
|
-
return hash(self.name)
|
|
424
|
-
|
|
425
|
-
def __eq__(self, other):
|
|
426
|
-
return self is other
|
|
427
|
-
|
|
428
|
-
def __iter__(self):
|
|
429
|
-
yield self
|
|
430
|
-
|
|
431
|
-
@property
|
|
432
|
-
def __typing_is_unpacked_typevartuple__(self):
|
|
433
|
-
return True
|
|
459
|
+
def has_default(self):
|
|
460
|
+
return False
|
shape_extensions/dsl.py
CHANGED
|
@@ -84,6 +84,26 @@ def einsum(spec: str, shapes: _IntTuplesSchema, /) -> _IntTupleSchema:
|
|
|
84
84
|
...
|
|
85
85
|
|
|
86
86
|
|
|
87
|
+
def einops_einsum(spec: str, shapes: _IntTuplesSchema, /) -> _IntTupleSchema:
|
|
88
|
+
"""Compute the output shape described by a named-axis einops equation."""
|
|
89
|
+
...
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def rearrange(spec: str, shape: _IntTupleSchema, /) -> _IntTupleSchema:
|
|
93
|
+
"""Compute the output shape described by an einops rearrange pattern."""
|
|
94
|
+
...
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def reduce(spec: str, shape: _IntTupleSchema, /) -> _IntTupleSchema:
|
|
98
|
+
"""Compute the output shape described by an einops reduction pattern."""
|
|
99
|
+
...
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def repeat(spec: str, shape: _IntTupleSchema, /) -> _IntTupleSchema:
|
|
103
|
+
"""Compute the output shape described by an einops repeat pattern."""
|
|
104
|
+
...
|
|
105
|
+
|
|
106
|
+
|
|
87
107
|
def _gufunc_broadcast(spec: str, shapes: _IntTuplesSchema, /) -> _IntTupleSchema:
|
|
88
108
|
"""Compute a gufunc result shape inside a type-level shape DSL function."""
|
|
89
109
|
return _IntTupleSchema()
|
|
@@ -1,8 +0,0 @@
|
|
|
1
|
-
shape_extensions/__init__.py,sha256=o5Zz7u8lTllnbRASAlU4Gt4AsyNHka8qBCT5OWd8lKA,11708
|
|
2
|
-
shape_extensions/dsl.py,sha256=PXgCuUivw57iBEx4fI1nvgYtBrwRY1S3dkpsMXRTrk8,2517
|
|
3
|
-
shape_extensions/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
|
|
4
|
-
shape_extensions/torchscript.py,sha256=Jk8Mv3dEEPGdkH6EIaHOzc11VvGwvq-o1eDELwWpUE8,12914
|
|
5
|
-
pyrefly_shape_extensions-1.3.0.dev4.dist-info/METADATA,sha256=lE3h7rcYkPmMFXjg7HZQ6OJZGQTQOz-pZBQenCsqVWM,2317
|
|
6
|
-
pyrefly_shape_extensions-1.3.0.dev4.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
|
|
7
|
-
pyrefly_shape_extensions-1.3.0.dev4.dist-info/licenses/LICENSE,sha256=2m03A-0Ry-Qr0hLHJZV8mNojy_8ZmMBfpLPZdtGljpM,1088
|
|
8
|
-
pyrefly_shape_extensions-1.3.0.dev4.dist-info/RECORD,,
|
|
File without changes
|