pyrefly-shape-extensions 1.3.0.dev4__tar.gz → 1.4.0.dev1__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.dev4
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.12
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.
@@ -5,7 +5,12 @@ 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
+ `RegularNestedList[Shape, Domain]` represents regular (non-jagged) nested list
12
+ literals; for example, `[[1, 2], [3, 4]]` binds `Shape` to `[2, 2]`. Unsupported
13
+ containers and irregular literals use ordinary typing and any fallback overload
14
+ supplied by the consumer.
15
+
11
16
  The package is versioned in lockstep with Pyrefly.
@@ -6,9 +6,9 @@ build-backend = "hatchling.build"
6
6
  name = "pyrefly-shape-extensions"
7
7
  description = "Shape typing primitives and DSL for Pyrefly tensor shape tracking"
8
8
  readme = "README.md"
9
- requires-python = ">=3.12"
9
+ requires-python = ">=3.10"
10
10
  license = { file = "LICENSE" }
11
- version = "1.3.0.dev4"
11
+ version = "1.4.0.dev1"
12
12
  keywords = ["typechecker", "typechecking", "shapes", "tensor", "pyrefly"]
13
13
  classifiers = [
14
14
  "Development Status :: 4 - Beta",
@@ -7,9 +7,8 @@
7
7
 
8
8
  """Library-agnostic shape typing primitives.
9
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.
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 the shape carrier for
96
- `tuple[int, ...]`. At runtime, calling it coerces any iterable to a plain
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 element sequence from a IntTuple carrier.
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 a ``IntTuple``
119
- carrier ``S``, ``*Elements[S]`` splices its element sequence into a shape position,
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 carrier without a ``TypeVarTuple``. Pyrefly uses the ``.pyi``
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, carrier):
129
- self.carrier = carrier
139
+ def __init__(self, shape):
140
+ self.shape = shape
130
141
 
131
- def __class_getitem__(cls, carrier):
132
- return cls(carrier)
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.carrier!r}]"
149
+ return f"Elements[{self.shape!r}]"
139
150
 
140
151
 
141
- class Int[T]:
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[T]:
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[T]:
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 for
247
- different shape libraries; a default version that works for libraries
248
- like torch and numpy where `.shape` is a tuple field is defined in
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
- @defines_assert_shape
255
- def assert_shape(x, shape):
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
- Pyrefly will validate that the shape modeled in Pyrefly's shaped array
262
- static analysis matches (similar to `assert_type`).
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
- actual = tuple(x.shape)
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(actual) != len(expected):
317
+ if len(actual_tuple) != len(expected):
273
318
  raise AssertionError(
274
- f"expected rank {len(expected)} for shape {expected}, got shape {actual}"
319
+ f"expected rank {len(expected)} for shape {expected}, got shape {actual_tuple}"
275
320
  )
276
- elif actual != expected:
277
- raise AssertionError(f"expected shape {expected}, got {actual}")
278
- return x
321
+ elif actual_tuple != expected:
322
+ raise AssertionError(f"expected shape {expected}, got {actual_tuple}")
323
+ return actual
279
324
 
280
325
 
281
- def shaped_array(
282
- *, shape: str, builtin_indexing: bool = True
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
- def decorator(cls: type) -> type:
290
- return cls
331
+ Pyrefly will validate that the statically modeled shape matches, similar to
332
+ `assert_type`.
291
333
 
292
- return decorator
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
- def type_shape_dsl_function[F: typing.Callable](fn: F) -> F:
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
- class TypeVarTuple:
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
@@ -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()