pyrefly-shape-extensions 1.3.0.dev3__tar.gz → 1.3.1__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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: pyrefly-shape-extensions
3
- Version: 1.3.0.dev3
3
+ Version: 1.3.1
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/
@@ -41,7 +41,7 @@ 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
47
  The package is versioned in lockstep with Pyrefly.
@@ -5,7 +5,7 @@ Runtime helpers for Pyrefly tensor shape annotations.
5
5
  This package provides the lightweight `shape_extensions` module used by
6
6
  Pyrefly's tensor shape stubs. It defines runtime no-op versions of the shape
7
7
  typing primitives so annotations such as `Tensor[B, T]`, `IntVar("B")`, and
8
- `assert_shape(x, (2, 3))` can be evaluated by Python while Pyrefly uses the
8
+ `assert_shape(x.shape, (2, 3))` can be evaluated by Python while Pyrefly uses the
9
9
  corresponding stubs for static shape checking.
10
10
 
11
11
  The package is versioned in lockstep with Pyrefly.
@@ -8,7 +8,7 @@ description = "Shape typing primitives and DSL for Pyrefly tensor shape tracking
8
8
  readme = "README.md"
9
9
  requires-python = ">=3.12"
10
10
  license = { file = "LICENSE" }
11
- version = "1.3.0.dev3"
11
+ version = "1.3.1"
12
12
  keywords = ["typechecker", "typechecking", "shapes", "tensor", "pyrefly"]
13
13
  classifiers = [
14
14
  "Development Status :: 4 - Beta",
@@ -20,16 +20,19 @@ __all__ = [
20
20
  "Elements",
21
21
  "Int",
22
22
  "IntTuple",
23
+ "IntTuples",
23
24
  "IntVar",
25
+ "Index",
26
+ "MapIntTuples",
24
27
  "ProxyMethod",
25
28
  "SymbolicArithExpr",
26
29
  "TypeVarTuple",
27
30
  "assert_shape",
28
31
  "broadcast",
29
32
  "defines_assert_shape",
30
- "shaped_array",
33
+ "gufunc_broadcast",
34
+ "index_shape",
31
35
  "type_shape_dsl_function",
32
- "uses_shape_dsl",
33
36
  ]
34
37
 
35
38
 
@@ -85,12 +88,25 @@ def _patch_torch_if_available() -> None:
85
88
  _patch_torch_if_available()
86
89
 
87
90
 
91
+ def _patch_jax_if_available() -> None:
92
+ try:
93
+ import jax # @manual
94
+ except ImportError:
95
+ return
96
+
97
+ if hasattr(jax, "Array") and not hasattr(jax.Array, "__class_getitem__"):
98
+ jax.Array.__class_getitem__ = classmethod(_return_class)
99
+
100
+
101
+ _patch_jax_if_available()
102
+
103
+
88
104
  class IntTuple:
89
105
  """Tuple-valued shape annotation surface.
90
106
 
91
- In type positions, Pyrefly treats `IntTuple` as the shape carrier for
92
- `tuple[int, ...]`. At runtime, calling it coerces any iterable to a plain
93
- tuple.
107
+ In type positions, Pyrefly treats `IntTuple` as a whole shape whose runtime
108
+ representation is `tuple[int, ...]`. At runtime, calling it coerces any
109
+ iterable to a plain tuple.
94
110
  """
95
111
 
96
112
  def __new__(cls, iterable=()):
@@ -100,31 +116,38 @@ class IntTuple:
100
116
  return cls
101
117
 
102
118
 
119
+ class IntTuples:
120
+ """A tuple whose elements are `IntTuple` values."""
121
+
122
+ def __new__(cls, iterable=()):
123
+ return tuple(iterable)
124
+
125
+
103
126
  class Elements:
104
- """Inverse of ``tuple[Unpack[S]]``: extracts the element sequence from a IntTuple carrier.
127
+ """Inverse of ``tuple[Unpack[S]]``: extracts the dimensions from an ``IntTuple``.
105
128
 
106
129
  In the Python typing spec, ``tuple[Unpack[Ts]]`` wraps a ``TypeVarTuple`` into a
107
- concrete tuple type. ``Elements[S]`` is the conceptual inverse: given a ``IntTuple``
108
- carrier ``S``, ``*Elements[S]`` splices its element sequence into a shape position,
130
+ concrete tuple type. ``Elements[S]`` is the conceptual inverse: given an ``IntTuple``
131
+ shape ``S``, ``*Elements[S]`` splices its dimensions into a shape position,
109
132
  e.g. ``Array[[*Elements[S], OUT], DType]``.
110
133
 
111
134
  This fills a gap in the current typing spec — there is no standard mechanism to
112
- decompose a variadic carrier without a ``TypeVarTuple``. Pyrefly uses the ``.pyi``
135
+ decompose a variadic shape without a ``TypeVarTuple``. Pyrefly uses the ``.pyi``
113
136
  stub for type inference; this class exists so annotations evaluate without crashing
114
137
  at runtime.
115
138
  """
116
139
 
117
- def __init__(self, carrier):
118
- self.carrier = carrier
140
+ def __init__(self, shape):
141
+ self.shape = shape
119
142
 
120
- def __class_getitem__(cls, carrier):
121
- return cls(carrier)
143
+ def __class_getitem__(cls, shape):
144
+ return cls(shape)
122
145
 
123
146
  def __iter__(self):
124
147
  yield self
125
148
 
126
149
  def __repr__(self):
127
- return f"Elements[{self.carrier!r}]"
150
+ return f"Elements[{self.shape!r}]"
128
151
 
129
152
 
130
153
  class Int[T]:
@@ -143,6 +166,12 @@ class Flag[T]:
143
166
  pass
144
167
 
145
168
 
169
+ class Index:
170
+ """Marker for an index value retained for type-level shape evaluation."""
171
+
172
+ pass
173
+
174
+
146
175
  class ProxyMethod[T]:
147
176
  """Type-checker marker for method forwarding annotations."""
148
177
 
@@ -226,54 +255,67 @@ def defines_assert_shape(fn: typing.Callable) -> typing.Callable:
226
255
  """
227
256
  Decorator that marks a function as an assert_shape helper.
228
257
 
229
- Used in order to allow custom assert_shape functions if necessary for
230
- different shape libraries; a default version that works for libraries
231
- like torch and numpy where `.shape` is a tuple field is defined in
232
- the `assert_shape` function of this library.
258
+ Used in order to allow custom assert_shape functions if necessary. A default
259
+ version that works for tuple-like shapes is defined in the `assert_shape`
260
+ function of this library.
233
261
  """
234
262
  return fn
235
263
 
236
264
 
237
265
  @defines_assert_shape
238
- def assert_shape(x, shape):
266
+ def assert_shape(actual, shape):
239
267
  """
240
- At runtime, assert that x has the expected runtime shape, assuming that `x` is
241
- some type like `torch.Tensor` or `np.ndarray` that has a tuple-valued
242
- field `shape` indicating the shape.
268
+ At runtime, assert that a tuple-like shape has the expected value.
243
269
 
244
- Pyrefly will validate that the shape modeled in Pyrefly's shaped array
245
- static analysis matches (similar to `assert_type`).
270
+ Pyrefly will validate that the statically modeled shape matches, similar to
271
+ `assert_type`.
246
272
 
247
273
  TODO(stroxler): for now, symbolic dimensions are skipped at runtime,
248
274
  so in the case of a symbolic `shape` the runtime validation is only checking
249
275
  the rank for those axes. But the static analysis will fully validate.
250
276
  """
251
277
 
252
- actual = tuple(x.shape)
278
+ # Preserve legacy calls that pass an array object rather than its shape.
279
+ if not isinstance(actual, tuple) and hasattr(actual, "shape"):
280
+ actual_tuple = tuple(actual.shape)
281
+ else:
282
+ actual_tuple = tuple(actual)
253
283
  expected = tuple(shape)
254
284
  if any(isinstance(dim, SymbolicArithExpr) for dim in expected):
255
- if len(actual) != len(expected):
285
+ if len(actual_tuple) != len(expected):
256
286
  raise AssertionError(
257
- f"expected rank {len(expected)} for shape {expected}, got shape {actual}"
287
+ f"expected rank {len(expected)} for shape {expected}, got shape {actual_tuple}"
258
288
  )
259
- elif actual != expected:
260
- raise AssertionError(f"expected shape {expected}, got {actual}")
261
- return x
289
+ elif actual_tuple != expected:
290
+ raise AssertionError(f"expected shape {expected}, got {actual_tuple}")
291
+ return actual
262
292
 
263
293
 
264
- def shaped_array(*, shape: str) -> typing.Callable[[type], type]:
265
- """Decorator that marks a class as carrying a shape TypeVarTuple."""
294
+ def index_shape(_shape: IntTuple, _index: typing.Any) -> IntTuple:
295
+ """Runtime placeholder for Pyrefly's native shape-indexing intrinsic."""
266
296
 
267
- def decorator(cls: type) -> type:
268
- return cls
297
+ return IntTuple()
269
298
 
270
- return decorator
271
299
 
300
+ class MapIntTuples:
301
+ """Map a unary type lambda over an ``IntTuples`` value.
272
302
 
273
- def broadcast(*_args: typing.Any) -> IntTuple:
274
- """Runtime placeholder for Pyrefly's native type-level broadcast intrinsic."""
303
+ A forward map preserves each source shape::
275
304
 
276
- return IntTuple()
305
+ MapIntTuples[lambda S: Tensor[S], tuple[IntTuple[2], IntTuple[3, 4]]]
306
+
307
+ A map used directly as a parameter annotation reverses that relationship, so
308
+ passing ``(Tensor[IntTuple[2]], Tensor[IntTuple[3, 4]])`` infers the source
309
+ as ``tuple[IntTuple[2], IntTuple[3, 4]]``. Each symbolic source may occur in
310
+ only one parameter pattern, keeping inference unambiguous.
311
+
312
+ At runtime this is a placeholder that does not inspect its arguments,
313
+ because valid static sources such as ``Any`` and ``Never`` cannot be mapped
314
+ as Python values.
315
+ """
316
+
317
+ def __class_getitem__(cls, params):
318
+ return tuple
277
319
 
278
320
 
279
321
  def type_shape_dsl_function[F: typing.Callable](fn: F) -> F:
@@ -282,6 +324,24 @@ def type_shape_dsl_function[F: typing.Callable](fn: F) -> F:
282
324
  return fn
283
325
 
284
326
 
327
+ # `dsl` imports the public schema classes above, so defer this import until they exist.
328
+ from . import dsl as _dsl
329
+
330
+
331
+ @type_shape_dsl_function
332
+ def gufunc_broadcast(spec: str, shapes: IntTuples) -> IntTuple:
333
+ """Compute the output shape described by a generalized ufunc signature."""
334
+
335
+ return _dsl._gufunc_broadcast(spec, shapes)
336
+
337
+
338
+ @type_shape_dsl_function
339
+ def broadcast(left: IntTuple, right: IntTuple) -> IntTuple:
340
+ spec = "(),()->()"
341
+ shapes = _dsl.IntTuples((left, right))
342
+ return gufunc_broadcast(spec, shapes)
343
+
344
+
285
345
  class IntVar:
286
346
  """Symbolic variable with arithmetic support for tensor shape dimensions.
287
347
 
@@ -333,6 +393,9 @@ class IntVar:
333
393
  def __typing_subst__(self, arg):
334
394
  return arg
335
395
 
396
+ def has_default(self):
397
+ return False
398
+
336
399
 
337
400
  class TypeVarTuple:
338
401
  """TypeVarTuple with support for integer shape dimensions.
@@ -371,21 +434,5 @@ class TypeVarTuple:
371
434
  def __typing_is_unpacked_typevartuple__(self):
372
435
  return True
373
436
 
374
-
375
- def uses_shape_dsl(
376
- ir_fn: typing.Callable,
377
- *,
378
- capture_init: list[str] | None = None,
379
- ) -> typing.Callable[[typing.Callable], typing.Callable]:
380
- """Decorator that associates a shape DSL function with an API function.
381
-
382
- At runtime this is a no-op: the decorator arguments are ignored and the
383
- decorated function is returned unchanged. Pyrefly uses this decorator
384
- at type-checking time to route bound arguments through the shape DSL
385
- for return-type refinement.
386
- """
387
-
388
- def decorator(fn: typing.Callable) -> typing.Callable:
389
- return fn
390
-
391
- return decorator
437
+ def has_default(self):
438
+ return False
@@ -0,0 +1,89 @@
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
+ # TODO(stroxler): Unquote `typing.TypeIs` when Python 3.13+ is the minimum version.
15
+ import typing
16
+
17
+ from . import (
18
+ Int as _IntSchema,
19
+ IntTuple as _IntTupleSchema,
20
+ IntTuples as _IntTuplesSchema,
21
+ )
22
+
23
+ # DSL builtins: these exist so that DSL definition files can import them
24
+ # and avoid unbound-name errors. The DSL compiler recognizes these names
25
+ # as builtins regardless of the Python-level definitions here.
26
+
27
+
28
+ def Invalid(message: str) -> typing.Any:
29
+ """Return an invalid shape computation from a type-shape DSL body."""
30
+
31
+ ...
32
+
33
+
34
+ class Int:
35
+ """Operations that produce values in the DSL integer domain."""
36
+
37
+ @staticmethod
38
+ def gradual() -> typing.Any: ...
39
+
40
+
41
+ class IntTuple(_IntTupleSchema):
42
+ """Operations that produce values in the DSL integer-tuple domain."""
43
+
44
+ def __new__(cls, values: typing.Iterable[typing.Any]) -> _IntTupleSchema:
45
+ return _IntTupleSchema(values)
46
+
47
+ @staticmethod
48
+ def gradual() -> typing.Any: ...
49
+
50
+
51
+ class IntTuples(_IntTuplesSchema):
52
+ """Operations that produce tuples of `IntTuple` values in the DSL."""
53
+
54
+ def __new__(cls, values: typing.Iterable[_IntTupleSchema]) -> _IntTuplesSchema:
55
+ return _IntTuplesSchema(values)
56
+
57
+ @staticmethod
58
+ def gradual() -> typing.Any: ...
59
+
60
+
61
+ # `TypeGuard`, not `TypeIs`: a false result does not narrow symbolic or gradual `Int` values.
62
+ def is_concrete_int(value: object) -> typing.TypeGuard[_IntSchema]: ...
63
+
64
+
65
+ def is_int_value(value: object) -> "typing.TypeIs[int]": ...
66
+
67
+
68
+ def concat(
69
+ left: typing.Iterable[typing.Any], right: typing.Iterable[typing.Any], /
70
+ ) -> _IntTupleSchema:
71
+ """Concatenate two shape values inside a type-shape DSL body."""
72
+
73
+ return _IntTupleSchema((*left, *right))
74
+
75
+
76
+ def prod(xs: _IntTupleSchema, /) -> _IntSchema: ...
77
+
78
+
79
+ def sum(xs: _IntTupleSchema, /) -> _IntSchema: ...
80
+
81
+
82
+ def einsum(spec: str, shapes: _IntTuplesSchema, /) -> _IntTupleSchema:
83
+ """Compute the output shape described by an explicit einsum equation."""
84
+ ...
85
+
86
+
87
+ def _gufunc_broadcast(spec: str, shapes: _IntTuplesSchema, /) -> _IntTupleSchema:
88
+ """Compute a gufunc result shape inside a type-level shape DSL function."""
89
+ return _IntTupleSchema()
@@ -1,123 +0,0 @@
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
- from __future__ import annotations
15
-
16
- import typing
17
-
18
- from . import Int as _IntSchema, IntTuple as _IntTupleSchema
19
-
20
-
21
- def shape_dsl_function(fn: typing.Callable) -> typing.Callable:
22
- """Marks a function as a shape DSL function.
23
-
24
- At runtime this is a no-op: the decorated function is returned unchanged.
25
- Pyrefly uses this decorator at type-checking time to convert the function
26
- body to DSL IR via convert_fndef.
27
- """
28
- return fn
29
-
30
-
31
- # DSL builtins: these exist so that DSL definition files can import them
32
- # and avoid unbound-name errors. The DSL compiler recognizes these names
33
- # as builtins regardless of the Python-level definitions here.
34
-
35
-
36
- class ShapedArray:
37
- """A shaped-array value in the DSL, constructed via ShapedArray(shape=[...])."""
38
-
39
- shape: list[int]
40
-
41
- def __init__(self, *, shape: list[int]) -> None:
42
- self.shape = shape
43
-
44
-
45
- class symint:
46
- """A symbolic integer dimension in the DSL."""
47
-
48
- ...
49
-
50
-
51
- class Error(Exception):
52
- """DSL error raised via `raise Error("message")`."""
53
-
54
- ...
55
-
56
-
57
- class _Unknown:
58
- """Sentinel returned from DSL functions to fall back to the declared return type."""
59
-
60
- ...
61
-
62
-
63
- Unknown: _Unknown = _Unknown()
64
-
65
-
66
- def Invalid(message: str) -> typing.Any:
67
- """Return an invalid shape computation from a type-shape DSL body."""
68
-
69
- ...
70
-
71
-
72
- class Int:
73
- """Operations that produce values in the DSL integer domain."""
74
-
75
- @staticmethod
76
- def gradual() -> typing.Any: ...
77
-
78
-
79
- class IntTuple(_IntTupleSchema):
80
- """Operations that produce values in the DSL integer-tuple domain."""
81
-
82
- def __new__(cls, values: typing.Iterable[typing.Any]) -> _IntTupleSchema:
83
- return _IntTupleSchema(values)
84
-
85
- @staticmethod
86
- def gradual() -> typing.Any: ...
87
-
88
-
89
- def is_concrete_int(value: typing.Any) -> bool: ...
90
-
91
-
92
- def is_int_value(value: object) -> typing.TypeIs[int]: ...
93
-
94
-
95
- def concat(
96
- left: typing.Iterable[typing.Any], right: typing.Iterable[typing.Any], /
97
- ) -> _IntTupleSchema:
98
- """Concatenate two shape values inside a type-shape DSL body."""
99
-
100
- return _IntTupleSchema((*left, *right))
101
-
102
-
103
- @typing.overload
104
- def prod(xs: _IntTupleSchema, /) -> _IntSchema: ...
105
-
106
-
107
- @typing.overload
108
- def prod(xs: list[int]) -> int: ...
109
-
110
-
111
- def prod(xs: _IntTupleSchema | list[int]) -> _IntSchema | int:
112
- """Compute the product of a list of dimension sizes."""
113
- ...
114
-
115
-
116
- def sum(xs: list[int]) -> int:
117
- """Compute the sum of a list of dimension sizes."""
118
- ...
119
-
120
-
121
- def parse_einsum_equation(spec: str) -> list[list[list[int]]]:
122
- """Parse an einsum equation string into output map and check pairs."""
123
- ...