pyrefly-shape-extensions 1.1.1__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.
@@ -0,0 +1,47 @@
1
+ Metadata-Version: 2.4
2
+ Name: pyrefly-shape-extensions
3
+ Version: 1.1.1
4
+ Summary: Shape typing primitives and DSL for Pyrefly tensor shape tracking
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: pyrefly,shapes,tensor,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
+ Requires-Python: >=3.12
35
+ Description-Content-Type: text/markdown
36
+
37
+ # pyrefly-shape-extensions
38
+
39
+ Runtime helpers for Pyrefly tensor shape annotations.
40
+
41
+ This package provides the lightweight `shape_extensions` module used by
42
+ Pyrefly's tensor shape stubs. It defines runtime no-op versions of the shape
43
+ typing primitives so annotations such as `Tensor[B, T]`, `TypeVar("B")`, and
44
+ `assert_shape(x, (2, 3))` can be evaluated by Python while Pyrefly uses the
45
+ corresponding stubs for static shape checking.
46
+
47
+ The package is versioned in lockstep with Pyrefly.
@@ -0,0 +1,7 @@
1
+ shape_extensions/__init__.py,sha256=ix_eo2Y6Sz22V0GwivSEujubHABzyw4mxKKMdca0Ll8,8319
2
+ shape_extensions/dsl.py,sha256=QEGndUSJKvROYDzxVwZN4tFtuS1VBgNupibnV2muGTQ,1775
3
+ shape_extensions/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
4
+ pyrefly_shape_extensions-1.1.1.dist-info/METADATA,sha256=3VwNN4To1KFl_znTp7A3TkITkFGX2_DTsRT2DCq--XE,2313
5
+ pyrefly_shape_extensions-1.1.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
6
+ pyrefly_shape_extensions-1.1.1.dist-info/licenses/LICENSE,sha256=2m03A-0Ry-Qr0hLHJZV8mNojy_8ZmMBfpLPZdtGljpM,1088
7
+ pyrefly_shape_extensions-1.1.1.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.30.1
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -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,300 @@
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
+ # pyre-ignore-all-errors
7
+
8
+ """Library-agnostic shape typing primitives.
9
+
10
+ The .pyi stub provides full type information to pyrefly. This .py file
11
+ provides minimal runtime classes so that annotations using these types
12
+ don't crash when evaluated by Python.
13
+ """
14
+
15
+ import typing
16
+ from dataclasses import dataclass
17
+
18
+
19
+ def _patch_torch_if_available() -> None:
20
+ try:
21
+ import torch # @manual
22
+ import torch.nn as nn # @manual
23
+ except ImportError:
24
+ return
25
+
26
+ # Make torch types subscriptable at runtime so that annotations like
27
+ # Tensor[B, T, N] or nn.Linear[In, Out] evaluate as no-ops instead of
28
+ # crashing with "type is not subscriptable".
29
+ subscriptable_classes = [
30
+ torch.Tensor,
31
+ nn.Embedding,
32
+ nn.Linear,
33
+ nn.ModuleList,
34
+ # Convolution modules
35
+ nn.Conv1d,
36
+ nn.Conv2d,
37
+ nn.Conv3d,
38
+ nn.ConvTranspose1d,
39
+ nn.ConvTranspose2d,
40
+ nn.ConvTranspose3d,
41
+ # Pooling modules
42
+ nn.MaxPool1d,
43
+ nn.MaxPool2d,
44
+ nn.MaxPool3d,
45
+ nn.AvgPool1d,
46
+ nn.AvgPool2d,
47
+ nn.AvgPool3d,
48
+ nn.AdaptiveAvgPool1d,
49
+ nn.AdaptiveAvgPool2d,
50
+ nn.AdaptiveAvgPool3d,
51
+ nn.AdaptiveMaxPool1d,
52
+ nn.AdaptiveMaxPool2d,
53
+ nn.AdaptiveMaxPool3d,
54
+ ]
55
+ for cls in subscriptable_classes:
56
+ if not hasattr(cls, "__class_getitem__"):
57
+ cls.__class_getitem__ = classmethod(lambda cls, params: cls)
58
+
59
+
60
+ _patch_torch_if_available()
61
+
62
+
63
+ class Dim[T]:
64
+ """Symbolic integer type for dimension values.
65
+
66
+ At runtime this is a no-op generic class. The type checker uses the
67
+ .pyi stub for shape inference.
68
+ """
69
+
70
+ pass
71
+
72
+
73
+ @dataclass(frozen=True)
74
+ class SymbolicArithExpr:
75
+ """Runtime representation of symbolic dimension arithmetic."""
76
+
77
+ op: str
78
+ args: tuple[typing.Any, ...]
79
+
80
+ def __str__(self):
81
+ if self.op == "var":
82
+ return str(self.args[0])
83
+ if self.op == "-" and len(self.args) == 2 and self.args[0] == 0:
84
+ return f"-{_format_symbolic_arg(self.args[1])}"
85
+ if len(self.args) == 2:
86
+ return (
87
+ f"{_format_symbolic_arg(self.args[0])} "
88
+ f"{self.op} {_format_symbolic_arg(self.args[1])}"
89
+ )
90
+ return repr(self)
91
+
92
+ def __add__(self, other):
93
+ return SymbolicArithExpr("+", (self, other))
94
+
95
+ def __radd__(self, other):
96
+ return SymbolicArithExpr("+", (other, self))
97
+
98
+ def __sub__(self, other):
99
+ return SymbolicArithExpr("-", (self, other))
100
+
101
+ def __rsub__(self, other):
102
+ return SymbolicArithExpr("-", (other, self))
103
+
104
+ def __mul__(self, other):
105
+ return SymbolicArithExpr("*", (self, other))
106
+
107
+ def __rmul__(self, other):
108
+ return SymbolicArithExpr("*", (other, self))
109
+
110
+ def __floordiv__(self, other):
111
+ return SymbolicArithExpr("//", (self, other))
112
+
113
+ def __rfloordiv__(self, other):
114
+ return SymbolicArithExpr("//", (other, self))
115
+
116
+ def __pow__(self, other):
117
+ return SymbolicArithExpr("**", (self, other))
118
+
119
+ def __rpow__(self, other):
120
+ return SymbolicArithExpr("**", (other, self))
121
+
122
+ def __neg__(self):
123
+ return SymbolicArithExpr("-", (0, self))
124
+
125
+
126
+ def _format_symbolic_arg(value):
127
+ if (
128
+ isinstance(value, SymbolicArithExpr)
129
+ and value.op != "var"
130
+ and not (value.op == "-" and len(value.args) == 2 and value.args[0] == 0)
131
+ ):
132
+ return f"({value})"
133
+ return str(value)
134
+
135
+
136
+ class D:
137
+ """Wrap a shape type variable so Python can evaluate dimension arithmetic."""
138
+
139
+ def __new__(cls, value):
140
+ return SymbolicArithExpr("var", (value,))
141
+
142
+ def __class_getitem__(cls, value):
143
+ return cls(value)
144
+
145
+
146
+ def defines_assert_shape(fn: typing.Callable) -> typing.Callable:
147
+ """
148
+ Decorator that marks a function as an assert_shape helper.
149
+
150
+ Used in order to allow custom assert_shape functions if necessary for
151
+ different shape libraries; a default version that works for libraries
152
+ like torch and numpy where `.shape` is a tuple field is defined in
153
+ the `assert_shape` function of this library.
154
+ """
155
+ return fn
156
+
157
+
158
+ @defines_assert_shape
159
+ def assert_shape(x, shape):
160
+ """
161
+ At runtime, assert that x has the expected runtime shape, assuming that `x` is
162
+ some type like `torch.Tensor` or `np.ndarray` that has a tuple-valued
163
+ field `shape` indicating the shape.
164
+
165
+ Pyrefly will validate that the shape modeled in Pyrefly's shaped array
166
+ static analysis matches (similar to `assert_type`).
167
+
168
+ TODO(stroxler): for now, symbolic dimensions are skipped at runtime,
169
+ so in the case of a symbolic `shape` the runtime validation is only checking
170
+ the rank for those axes. But the static analysis will fully validate.
171
+ """
172
+
173
+ actual = tuple(x.shape)
174
+ expected = tuple(shape)
175
+ if any(isinstance(dim, SymbolicArithExpr) for dim in expected):
176
+ if len(actual) != len(expected):
177
+ raise AssertionError(
178
+ f"expected rank {len(expected)} for shape {expected}, got shape {actual}"
179
+ )
180
+ elif actual != expected:
181
+ raise AssertionError(f"expected shape {expected}, got {actual}")
182
+ return x
183
+
184
+
185
+ def shaped_array(*, shape: str) -> typing.Callable[[type], type]:
186
+ """Decorator that marks a class as carrying a shape TypeVarTuple."""
187
+
188
+ def decorator(cls: type) -> type:
189
+ return cls
190
+
191
+ return decorator
192
+
193
+
194
+ class TypeVar:
195
+ """TypeVar with arithmetic support for tensor shape dimensions.
196
+
197
+ Like typing.TypeVar but arithmetic operations (N + 1, N * 2, etc.)
198
+ return self instead of raising TypeError. Setting
199
+ __class__ = typing.TypeVar makes isinstance(x, typing.TypeVar)
200
+ return True, so Generic[N] and TypedDict + Generic[N] both work.
201
+
202
+ In pyrefly, shape_extensions.TypeVar is treated identically to
203
+ typing.TypeVar.
204
+ """
205
+
206
+ __class__ = typing.TypeVar
207
+
208
+ def __init__(self, name: str):
209
+ self.__name__ = name
210
+ self.name = name
211
+
212
+ def __repr__(self):
213
+ return self.name
214
+
215
+ def __hash__(self):
216
+ return hash(self.name)
217
+
218
+ def __eq__(self, other):
219
+ return self is other
220
+
221
+ def __add__(self, other):
222
+ return self
223
+
224
+ def __radd__(self, other):
225
+ return self
226
+
227
+ def __sub__(self, other):
228
+ return self
229
+
230
+ def __rsub__(self, other):
231
+ return self
232
+
233
+ def __mul__(self, other):
234
+ return self
235
+
236
+ def __rmul__(self, other):
237
+ return self
238
+
239
+ def __floordiv__(self, other):
240
+ return self
241
+
242
+ def __typing_subst__(self, arg):
243
+ return arg
244
+
245
+
246
+ class TypeVarTuple:
247
+ """TypeVarTuple with support for integer shape dimensions.
248
+
249
+ Like typing.TypeVarTuple but for use in tensor shape annotations.
250
+ Setting __class__ = typing.TypeVarTuple and providing
251
+ __typing_is_unpacked_typevartuple__ makes Generic[*Ns] work.
252
+
253
+ In pyrefly, shape_extensions.TypeVarTuple is treated identically to
254
+ typing.TypeVarTuple.
255
+
256
+ __iter__ yields self so that *Ns unpacking works in subscripts
257
+ like Generic[*Ns] or Tensor[*Ns, 3]. Python's star-unpacking
258
+ calls __iter__ on the object.
259
+ """
260
+
261
+ __class__ = typing.TypeVarTuple
262
+
263
+ def __init__(self, name: str):
264
+ self.__name__ = name
265
+ self.name = name
266
+
267
+ def __repr__(self):
268
+ return f"*{self.name}"
269
+
270
+ def __hash__(self):
271
+ return hash(self.name)
272
+
273
+ def __eq__(self, other):
274
+ return self is other
275
+
276
+ def __iter__(self):
277
+ yield self
278
+
279
+ @property
280
+ def __typing_is_unpacked_typevartuple__(self):
281
+ return True
282
+
283
+
284
+ def uses_shape_dsl(
285
+ ir_fn: typing.Callable,
286
+ *,
287
+ capture_init: list[str] | None = None,
288
+ ) -> typing.Callable[[typing.Callable], typing.Callable]:
289
+ """Decorator that associates a shape DSL function with an API function.
290
+
291
+ At runtime this is a no-op: the decorator arguments are ignored and the
292
+ decorated function is returned unchanged. Pyrefly uses this decorator
293
+ at type-checking time to route bound arguments through the shape DSL
294
+ for return-type refinement.
295
+ """
296
+
297
+ def decorator(fn: typing.Callable) -> typing.Callable:
298
+ return fn
299
+
300
+ return decorator
@@ -0,0 +1,74 @@
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
+ # pyre-ignore-all-errors
7
+
8
+ """DSL internals for shape typing.
9
+
10
+ Only used inside DSL definition files (e.g. torch/_shapes.pyi), not in
11
+ normal stubs or user code.
12
+ """
13
+
14
+ import typing
15
+
16
+
17
+ def shape_dsl_function(fn: typing.Callable) -> typing.Callable:
18
+ """Marks a function as a shape DSL function.
19
+
20
+ At runtime this is a no-op: the decorated function is returned unchanged.
21
+ Pyrefly uses this decorator at type-checking time to convert the function
22
+ body to DSL IR via convert_fndef.
23
+ """
24
+ return fn
25
+
26
+
27
+ # DSL builtins: these exist so that DSL definition files can import them
28
+ # and avoid unbound-name errors. The DSL compiler recognizes these names
29
+ # as builtins regardless of the Python-level definitions here.
30
+
31
+
32
+ class ShapedArray:
33
+ """A shaped-array value in the DSL, constructed via ShapedArray(shape=[...])."""
34
+
35
+ shape: list[int]
36
+
37
+ def __init__(self, *, shape: list[int]) -> None:
38
+ self.shape = shape
39
+
40
+
41
+ class symint:
42
+ """A symbolic integer dimension in the DSL."""
43
+
44
+ ...
45
+
46
+
47
+ class Error(Exception):
48
+ """DSL error raised via `raise Error("message")`."""
49
+
50
+ ...
51
+
52
+
53
+ class _Unknown:
54
+ """Sentinel returned from DSL functions to fall back to the declared return type."""
55
+
56
+ ...
57
+
58
+
59
+ Unknown: _Unknown = _Unknown()
60
+
61
+
62
+ def prod(xs: list[int]) -> int:
63
+ """Compute the product of a list of dimension sizes."""
64
+ ...
65
+
66
+
67
+ def sum(xs: list[int]) -> int:
68
+ """Compute the sum of a list of dimension sizes."""
69
+ ...
70
+
71
+
72
+ def parse_einsum_equation(spec: str) -> list[list[list[int]]]:
73
+ """Parse an einsum equation string into output map and check pairs."""
74
+ ...
@@ -0,0 +1 @@
1
+