pyrefly-shape-extensions 1.3.2__tar.gz → 1.4.0.dev2__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.2
3
+ Version: 1.4.0.dev2
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
@@ -44,4 +44,14 @@ typing primitives so annotations such as `Tensor[B, T]`, `IntVar("B")`, and
44
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
+
52
+ `IntTupleOrList[Values]` is a stub-authoring parameter type for APIs that accept
53
+ integer tuples and lists. A direct, unstarred list literal such as `[2, 3]`
54
+ binds `Values` to `IntTuple[2, 3]`; an existing or starred list remains gradual,
55
+ while a direct literal containing a non-integer is rejected.
56
+
47
57
  The package is versioned in lockstep with Pyrefly.
@@ -0,0 +1,21 @@
1
+ # pyrefly-shape-extensions
2
+
3
+ Runtime helpers for Pyrefly tensor shape annotations.
4
+
5
+ This package provides the lightweight `shape_extensions` module used by
6
+ Pyrefly's tensor shape stubs. It defines runtime no-op versions of the shape
7
+ typing primitives so annotations such as `Tensor[B, T]`, `IntVar("B")`, and
8
+ `assert_shape(x.shape, (2, 3))` can be evaluated by Python while Pyrefly uses the
9
+ corresponding stubs for static shape checking.
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
+
16
+ `IntTupleOrList[Values]` is a stub-authoring parameter type for APIs that accept
17
+ integer tuples and lists. A direct, unstarred list literal such as `[2, 3]`
18
+ binds `Values` to `IntTuple[2, 3]`; an existing or starred list remains gradual,
19
+ while a direct literal containing a non-integer is rejected.
20
+
21
+ 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.2"
11
+ version = "1.4.0.dev2"
12
12
  keywords = ["typechecker", "typechecking", "shapes", "tensor", "pyrefly"]
13
13
  classifiers = [
14
14
  "Development Status :: 4 - Beta",
@@ -7,31 +7,35 @@
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
 
14
+ import contextlib
15
+ import keyword
15
16
  import typing
16
17
  from dataclasses import dataclass
17
18
 
18
19
  __all__ = [
19
- "D",
20
20
  "Elements",
21
21
  "Int",
22
+ "IntListLiteral",
22
23
  "IntTuple",
24
+ "IntTupleOrList",
23
25
  "IntTuples",
24
26
  "IntVar",
25
27
  "Index",
26
28
  "MapIntTuples",
27
29
  "ProxyMethod",
30
+ "RegularNestedList",
28
31
  "SymbolicArithExpr",
29
- "TypeVarTuple",
30
32
  "assert_shape",
33
+ "assert_raises",
31
34
  "broadcast",
32
35
  "defines_assert_shape",
33
36
  "gufunc_broadcast",
34
37
  "index_shape",
38
+ "static_jaxtyping",
35
39
  "type_shape_dsl_function",
36
40
  ]
37
41
 
@@ -124,17 +128,17 @@ class IntTuples:
124
128
 
125
129
 
126
130
  class Elements:
127
- """Inverse of ``tuple[Unpack[S]]``: extracts the dimensions from an ``IntTuple``.
131
+ """Explicit inverse of ``tuple[Unpack[...]]`` for shape type variables.
128
132
 
129
133
  In the Python typing spec, ``tuple[Unpack[Ts]]`` wraps a ``TypeVarTuple`` into a
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,
132
- e.g. ``Array[[*Elements[S], OUT], DType]``.
133
-
134
- This fills a gap in the current typing spec — there is no standard mechanism to
135
- decompose a variadic shape without a ``TypeVarTuple``. Pyrefly uses the ``.pyi``
136
- stub for type inference; this class exists so annotations evaluate without crashing
137
- at runtime.
134
+ concrete tuple type. Pyrefly shapes accept the inverse operation directly: given
135
+ an ``IntTuple`` shape ``S``, a bare ``*S`` splat splices its dimensions into a
136
+ shape position, e.g. ``Array[[*S, OUT], DType]``.
137
+
138
+ ``Elements[S]`` is the explicit spelling of that same splat. It is optional in
139
+ annotations, which Pyrefly checks identically either way, but it is necessary
140
+ when the annotation is evaluated at runtime: unpacking a bare ``TypeVar`` raises
141
+ ``TypeError``, while ``Elements`` is iterable.
138
142
  """
139
143
 
140
144
  def __init__(self, shape):
@@ -150,7 +154,10 @@ class Elements:
150
154
  return f"Elements[{self.shape!r}]"
151
155
 
152
156
 
153
- class Int[T]:
157
+ _T = typing.TypeVar("_T")
158
+
159
+
160
+ class Int(typing.Generic[_T]):
154
161
  """Symbolic integer type for dimension values.
155
162
 
156
163
  At runtime this is a no-op generic class. The type checker uses the
@@ -160,7 +167,7 @@ class Int[T]:
160
167
  pass
161
168
 
162
169
 
163
- class Flag[T]:
170
+ class Flag(typing.Generic[_T]):
164
171
  """Marker for a literal-preserving value that controls type-level evaluation."""
165
172
 
166
173
  pass
@@ -172,12 +179,57 @@ class Index:
172
179
  pass
173
180
 
174
181
 
175
- class ProxyMethod[T]:
182
+ class ProxyMethod(typing.Generic[_T]):
176
183
  """Type-checker marker for method forwarding annotations."""
177
184
 
178
185
  pass
179
186
 
180
187
 
188
+ # `TypeVar` defaults require Python 3.13 at runtime, so omit them on Python 3.12.
189
+ if typing.TYPE_CHECKING:
190
+ _IntTupleT = typing.TypeVar(
191
+ "_IntTupleT", bound=IntTuple, default=IntTuple, covariant=True
192
+ )
193
+ _Domain = typing.TypeVar(
194
+ "_Domain", default=bool | int | float | complex, covariant=True
195
+ )
196
+ else:
197
+ _IntTupleT = typing.TypeVar("_IntTupleT", bound=IntTuple, covariant=True)
198
+ _Domain = typing.TypeVar("_Domain", covariant=True)
199
+
200
+
201
+ class IntListLiteral(typing.Generic[_IntTupleT]):
202
+ """A direct integer-list literal whose values are captured as an ``IntTuple``."""
203
+
204
+ def __class_getitem__(cls, params):
205
+ return list[int]
206
+
207
+
208
+ IntTupleOrList: typing.TypeAlias = typing.Union[
209
+ _IntTupleT, IntListLiteral[_IntTupleT], list[int]
210
+ ]
211
+
212
+
213
+ class RegularNestedList(typing.Generic[_IntTupleT, _Domain]):
214
+ """A regular nested list literal whose scalar leaves belong to ``Domain``.
215
+
216
+ Here, regular means the opposite of jagged or irregular: every sibling list
217
+ has the same shape.
218
+
219
+ Use this as a contextual parameter type for constructor-style APIs that
220
+ accept nested Python lists and need to infer a shape type argument. It is a
221
+ static marker, not the runtime type of an existing list value.
222
+
223
+ A literal such as ``[[1, 2], [3, 4]]`` binds ``Shape`` to
224
+ ``IntTuple[2, 2]``, while ``[[1, 2], [3]]`` is jagged and therefore not
225
+ regular. Existing containers, starred literals, and statically jagged
226
+ literals use ordinary typing instead of this marker.
227
+ """
228
+
229
+ def __class_getitem__(cls, params):
230
+ return cls
231
+
232
+
181
233
  @dataclass(frozen=True)
182
234
  class SymbolicArithExpr:
183
235
  """Runtime representation of symbolic dimension arithmetic."""
@@ -241,16 +293,6 @@ def _format_symbolic_arg(value):
241
293
  return str(value)
242
294
 
243
295
 
244
- class D:
245
- """Wrap a shape type variable so Python can evaluate dimension arithmetic."""
246
-
247
- def __new__(cls, value):
248
- return SymbolicArithExpr("var", (value,))
249
-
250
- def __class_getitem__(cls, value):
251
- return cls(value)
252
-
253
-
254
296
  def defines_assert_shape(fn: typing.Callable) -> typing.Callable:
255
297
  """
256
298
  Decorator that marks a function as an assert_shape helper.
@@ -262,17 +304,12 @@ def defines_assert_shape(fn: typing.Callable) -> typing.Callable:
262
304
  return fn
263
305
 
264
306
 
265
- @defines_assert_shape
266
- def assert_shape(actual, shape):
267
- """
268
- At runtime, assert that a tuple-like shape has the expected value.
269
-
270
- Pyrefly will validate that the statically modeled shape matches, similar to
271
- `assert_type`.
307
+ def _check_runtime_shape(actual, shape):
308
+ """Compare `actual` against `shape`, raising on a mismatch.
272
309
 
273
- TODO(stroxler): for now, symbolic dimensions are skipped at runtime,
274
- so in the case of a symbolic `shape` the runtime validation is only checking
275
- the rank for those axes. But the static analysis will fully validate.
310
+ Split out from `assert_shape` so the runtime comparison reads on its own.
311
+ Kept private because the test harness counts calls to `assert_shape`, and a
312
+ public helper reachable from it would be counted twice.
276
313
  """
277
314
 
278
315
  # Preserve legacy calls that pass an array object rather than its shape.
@@ -291,6 +328,47 @@ def assert_shape(actual, shape):
291
328
  return actual
292
329
 
293
330
 
331
+ @contextlib.contextmanager
332
+ def assert_raises(
333
+ expected: type[BaseException] | tuple[type[BaseException], ...],
334
+ ) -> typing.Iterator[None]:
335
+ """Assert that the body raises an exception of the expected type."""
336
+
337
+ try:
338
+ yield
339
+ except expected:
340
+ return
341
+ raise AssertionError(f"expected {expected!r} to be raised")
342
+
343
+
344
+ @defines_assert_shape
345
+ def assert_shape(actual, shape, *, runtime=None):
346
+ """
347
+ At runtime, assert that a tuple-like shape has the expected value.
348
+
349
+ Pyrefly will validate that the statically modeled shape matches, similar to
350
+ `assert_type`.
351
+
352
+ `shape` is the shape Pyrefly infers, and normally the library produces it too,
353
+ so one argument pins both behaviors. `runtime` is for the cases where the two
354
+ disagree: pass it the shape the library actually produces, and the runtime
355
+ check uses it instead of `shape`. Two things need it:
356
+
357
+ - An expression Pyrefly infers gradually: spell `shape` as `IntTuple` when it
358
+ has no shape at all, or as a tuple such as `(int,)` when the rank is known
359
+ and only a dimension is not.
360
+ - A known bug, where Pyrefly infers a shape the library does not produce.
361
+ Writing that wrong shape as `shape` documents it and makes the test fail
362
+ once it is fixed, rather than leaving the discrepancy unrecorded.
363
+
364
+ TODO(stroxler): for now, symbolic dimensions are skipped at runtime,
365
+ so in the case of a symbolic `shape` the runtime validation is only checking
366
+ the rank for those axes. But the static analysis will fully validate.
367
+ """
368
+
369
+ return _check_runtime_shape(actual, shape if runtime is None else runtime)
370
+
371
+
294
372
  def index_shape(_shape: IntTuple, _index: typing.Any) -> IntTuple:
295
373
  """Runtime placeholder for Pyrefly's native shape-indexing intrinsic."""
296
374
 
@@ -318,12 +396,90 @@ class MapIntTuples:
318
396
  return tuple
319
397
 
320
398
 
321
- def type_shape_dsl_function[F: typing.Callable](fn: F) -> F:
399
+ _F = typing.TypeVar("_F", bound=typing.Callable)
400
+
401
+
402
+ def type_shape_dsl_function(fn: _F) -> _F:
322
403
  """Runtime no-op for a user-defined type-level shape DSL function."""
323
404
 
324
405
  return fn
325
406
 
326
407
 
408
+ def static_jaxtyping(declaration: str) -> typing.Callable[[_F], _F]:
409
+ """Declare the dimension names a function or class may use with jaxtyping.
410
+
411
+ ``declaration`` is a space-separated list of dimension names, where a
412
+ leading ``*`` marks a variadic shape::
413
+
414
+ @static_jaxtyping("batch channels *rest")
415
+ def f(x: Float[Tensor, "batch channels"]) -> Float[Tensor, "*rest"]: ...
416
+
417
+ Pyrefly reads the declaration to scope the dimensions and check the shape
418
+ strings. Without it, jaxtyping annotations keep their ordinary ``Annotated``
419
+ meaning and the array shape stays gradual. At runtime functions are unchanged,
420
+ while classes become subscriptable so their static shape arguments can appear
421
+ in evaluated annotations.
422
+ """
423
+
424
+ declared_names: list[str] = []
425
+ for token in declaration.split():
426
+ name = token.removeprefix("*")
427
+ if (
428
+ name != "_"
429
+ and name.isidentifier()
430
+ and not keyword.iskeyword(name)
431
+ and name not in declared_names
432
+ ):
433
+ declared_names.append(name)
434
+ declared_dimensions = len(declared_names)
435
+
436
+ def decorate(value: _F) -> _F:
437
+ if not isinstance(value, type):
438
+ return value
439
+
440
+ original_descriptor = value.__dict__.get("__class_getitem__")
441
+
442
+ def class_getitem(cls, params):
443
+ args = params if isinstance(params, tuple) else (params,)
444
+ ordinary = args
445
+ if cls is value:
446
+ for _ in range(declared_dimensions):
447
+ if not ordinary:
448
+ break
449
+ argument = ordinary[-1]
450
+ is_dimension = isinstance(argument, (int, IntVar)) or (
451
+ isinstance(argument, list)
452
+ and all(isinstance(dim, (int, IntVar)) for dim in argument)
453
+ )
454
+ if not is_dimension:
455
+ break
456
+ ordinary = ordinary[:-1]
457
+
458
+ delegate_descriptor = original_descriptor
459
+ if delegate_descriptor is None:
460
+ for base in cls.__mro__:
461
+ candidate = base.__dict__.get("__class_getitem__")
462
+ if candidate is None:
463
+ continue
464
+ function = getattr(candidate, "__func__", candidate)
465
+ if getattr(function, "__static_jaxtyping__", False):
466
+ continue
467
+ delegate_descriptor = candidate
468
+ break
469
+
470
+ if not ordinary or delegate_descriptor is None:
471
+ return cls
472
+ ordinary_params = ordinary[0] if len(ordinary) == 1 else ordinary
473
+ delegate = delegate_descriptor.__get__(None, cls)
474
+ return delegate(ordinary_params)
475
+
476
+ class_getitem.__static_jaxtyping__ = True
477
+ value.__class_getitem__ = classmethod(class_getitem)
478
+ return value
479
+
480
+ return decorate
481
+
482
+
327
483
  # `dsl` imports the public schema classes above, so defer this import until they exist.
328
484
  from . import dsl as _dsl
329
485
 
@@ -351,10 +507,19 @@ class IntVar:
351
507
  return True, so Generic[N] and TypedDict + Generic[N] both work.
352
508
 
353
509
  In pyrefly, shape_extensions.IntVar marks symbolic integer dimensions.
510
+
511
+ Subscripting with a type variable, ``IntVar[N]``, is a static no-op that wraps
512
+ a PEP 695 ``TypeVar`` for runtime evaluation: a bare ``N + 1`` raises
513
+ ``TypeError`` when the annotation is evaluated, while ``IntVar[N] + 1`` builds
514
+ a symbolic expression. For readability in nontrivial formulas, alias the import
515
+ (``from shape_extensions import IntVar as iv``) and write ``iv[N]``.
354
516
  """
355
517
 
356
518
  __class__ = typing.TypeVar
357
519
 
520
+ def __class_getitem__(cls, value):
521
+ return SymbolicArithExpr("var", (value,))
522
+
358
523
  def __init__(self, name: str, *, bound=None):
359
524
  self.__name__ = name
360
525
  self.name = name
@@ -395,44 +560,3 @@ class IntVar:
395
560
 
396
561
  def has_default(self):
397
562
  return False
398
-
399
-
400
- class TypeVarTuple:
401
- """TypeVarTuple with support for integer shape dimensions.
402
-
403
- Like typing.TypeVarTuple but for use in tensor shape annotations.
404
- Setting __class__ = typing.TypeVarTuple and providing
405
- __typing_is_unpacked_typevartuple__ makes Generic[*Ns] work.
406
-
407
- In pyrefly, shape_extensions.TypeVarTuple is treated identically to
408
- typing.TypeVarTuple.
409
-
410
- __iter__ yields self so that *Ns unpacking works in subscripts
411
- like Generic[*Ns] or Tensor[*Ns, 3]. Python's star-unpacking
412
- calls __iter__ on the object.
413
- """
414
-
415
- __class__ = typing.TypeVarTuple
416
-
417
- def __init__(self, name: str):
418
- self.__name__ = name
419
- self.name = name
420
-
421
- def __repr__(self):
422
- return f"*{self.name}"
423
-
424
- def __hash__(self):
425
- return hash(self.name)
426
-
427
- def __eq__(self, other):
428
- return self is other
429
-
430
- def __iter__(self):
431
- yield self
432
-
433
- @property
434
- def __typing_is_unpacked_typevartuple__(self):
435
- return True
436
-
437
- def has_default(self):
438
- 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()
@@ -1,11 +0,0 @@
1
- # pyrefly-shape-extensions
2
-
3
- Runtime helpers for Pyrefly tensor shape annotations.
4
-
5
- This package provides the lightweight `shape_extensions` module used by
6
- Pyrefly's tensor shape stubs. It defines runtime no-op versions of the shape
7
- typing primitives so annotations such as `Tensor[B, T]`, `IntVar("B")`, and
8
- `assert_shape(x.shape, (2, 3))` can be evaluated by Python while Pyrefly uses the
9
- corresponding stubs for static shape checking.
10
-
11
- The package is versioned in lockstep with Pyrefly.