pyrefly-shape-extensions 1.4.0.dev1__py3-none-any.whl → 1.4.0.dev3__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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: pyrefly-shape-extensions
3
- Version: 1.4.0.dev1
3
+ Version: 1.4.0.dev3
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/
@@ -44,9 +44,45 @@ 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
+ `NamedInts` and `CaptureNamedInts` carry named axis lengths from `**kwargs`
48
+ into shape rules for einops-like APIs.
49
+
47
50
  `RegularNestedList[Shape, Domain]` represents regular (non-jagged) nested list
48
51
  literals; for example, `[[1, 2], [3, 4]]` binds `Shape` to `[2, 2]`. Unsupported
49
52
  containers and irregular literals use ordinary typing and any fallback overload
50
53
  supplied by the consumer.
51
54
 
55
+ `IntTupleOrList[Values]` is a stub-authoring parameter type for APIs that accept
56
+ integer tuples and lists. A direct, unstarred list literal such as `[2, 3]`
57
+ binds `Values` to `IntTuple[2, 3]`; an existing or starred list remains gradual,
58
+ while a direct literal containing a non-integer is rejected.
59
+
52
60
  The package is versioned in lockstep with Pyrefly.
61
+
62
+ ## Portable shape annotations
63
+
64
+ `Shaped[T, "..."]` is an alias for `typing.Annotated`, so other type checkers
65
+ read `T` and ignore the shape string. Inside a `@shape_vars` function or class,
66
+ Pyrefly also reads the string in annotations, casts, type aliases, and class
67
+ bases. Use `@shape_vars("")` for a literal shape with no declared dimensions.
68
+
69
+ Legacy type aliases cannot capture dimensions declared on an enclosing
70
+ `@shape_vars` function or class. For example, an `Alias: TypeAlias =
71
+ Shaped[Array, "[N]"]` inside a `@shape_vars("N")` definition reports that `N`
72
+ is not in scope for the alias. This is the same restriction that applies when
73
+ legacy type aliases capture ordinary enclosing type parameters. Use the
74
+ `Shaped` annotation directly in that scope; literal-only aliases are supported.
75
+
76
+ A defaulted `@shape_vars("N")` dimension after a `*Ts` class parameter is not
77
+ supported: Pyrefly reports the declaration and can mistake a trailing ordinary
78
+ type argument for the dimension. Pyrefly accepts
79
+ `@shape_vars("N", required=True) class Required[*Ts]` with an explicit shape,
80
+ as in `Required[int, str, 3]`; `Required[int, str]` still treats `str` as a
81
+ dimension. This explicit specialization is specific to Pyrefly, not a
82
+ portable workaround for other type checkers.
83
+
84
+ At runtime, `Shaped[Base, "..."]` can appear as a class base because
85
+ `Annotated` resolves to `Base`. Pyrefly reads its shape. In Pyright 1.1.414,
86
+ the base is rejected and inherited attributes and methods are inferred as
87
+ `Unknown` downstream. Do not rely on this base spelling when Pyright users
88
+ need inherited signatures.
@@ -0,0 +1,8 @@
1
+ shape_extensions/__init__.py,sha256=93pLPq-zYMTR_JWPe09xN6S973dnON8IcMNSdBSsEn4,20058
2
+ shape_extensions/dsl.py,sha256=Q-KfQeAv8gmWX26V9JeGdjdqPif1t8VUzQHKKhww42M,3253
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.dev3.dist-info/METADATA,sha256=rvgDuhuDx__51bJGlp_kYuhP0jfRumphg8Rvly4vbMY,4599
6
+ pyrefly_shape_extensions-1.4.0.dev3.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
7
+ pyrefly_shape_extensions-1.4.0.dev3.dist-info/licenses/LICENSE,sha256=2m03A-0Ry-Qr0hLHJZV8mNojy_8ZmMBfpLPZdtGljpM,1088
8
+ pyrefly_shape_extensions-1.4.0.dev3.dist-info/RECORD,,
@@ -1,4 +1,4 @@
1
1
  Wheel-Version: 1.0
2
- Generator: hatchling 1.32.3
2
+ Generator: hatchling 1.32.4
3
3
  Root-Is-Purelib: true
4
4
  Tag: py3-none-any
@@ -11,26 +11,53 @@ These definitions provide static shape information to Pyrefly while remaining
11
11
  safe to evaluate in runtime annotations.
12
12
  """
13
13
 
14
+ import contextlib
15
+ import keyword
14
16
  import typing
15
17
  from dataclasses import dataclass
16
18
 
19
+ # A shape annotation carrying its shape as string metadata. To Pyrefly, the
20
+ # string supplies type arguments to a generic class, after any explicit ones:
21
+ # `Shaped[Tensor, "[M, N]"]` is `Tensor[[M, N]]`, and
22
+ # `Shaped[Encoder[Input], "Dim, Hidden"]` is `Encoder[Input, Dim, Hidden]`. On
23
+ # `int` and on an integer tuple, the string instead replaces the type:
24
+ # `Shaped[int, "N"]` is `Int[N]`, and `Shaped[tuple[int, int], "[M, N]"]` is
25
+ # `IntTuple[M, N]`. Every other type checker reads the first argument alone. At
26
+ # runtime it is an ordinary `Annotated` object. The names inside the string are
27
+ # declared by an enclosing `shape_vars`.
28
+ #
29
+ # This must stay an import alias: mypy rejects `Shaped = typing.Annotated` as
30
+ # "not valid as a type". `compatibility_tests` pins this.
31
+ #
32
+ # Ruff recognizes `Annotated` only under that name, so it reports the names in a
33
+ # `Shaped` string as undefined (F821). Code that uses `Shaped` should disable
34
+ # F821; a type checker already reports genuinely undefined names.
35
+ from typing import Annotated as Shaped
36
+
17
37
  __all__ = [
18
- "D",
19
38
  "Elements",
20
39
  "Int",
40
+ "IntListLiteral",
21
41
  "IntTuple",
42
+ "IntTupleOrList",
22
43
  "IntTuples",
23
44
  "IntVar",
24
45
  "Index",
25
46
  "MapIntTuples",
47
+ "NamedInts",
48
+ "CaptureNamedInts",
26
49
  "ProxyMethod",
27
50
  "RegularNestedList",
51
+ "Shaped",
28
52
  "SymbolicArithExpr",
29
53
  "assert_shape",
54
+ "assert_raises",
30
55
  "broadcast",
31
56
  "defines_assert_shape",
32
57
  "gufunc_broadcast",
33
58
  "index_shape",
59
+ "shape_vars",
60
+ "static_jaxtyping",
34
61
  "type_shape_dsl_function",
35
62
  ]
36
63
 
@@ -123,17 +150,17 @@ class IntTuples:
123
150
 
124
151
 
125
152
  class Elements:
126
- """Inverse of ``tuple[Unpack[S]]``: extracts the dimensions from an ``IntTuple``.
153
+ """Explicit inverse of ``tuple[Unpack[...]]`` for shape type variables.
127
154
 
128
155
  In the Python typing spec, ``tuple[Unpack[Ts]]`` wraps a ``TypeVarTuple`` into a
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,
131
- e.g. ``Array[[*Elements[S], OUT], DType]``.
132
-
133
- This fills a gap in the current typing spec — there is no standard mechanism to
134
- decompose a variadic shape without a ``TypeVarTuple``. Pyrefly uses the ``.pyi``
135
- stub for type inference; this class exists so annotations evaluate without crashing
136
- at runtime.
156
+ concrete tuple type. Pyrefly shapes accept the inverse operation directly: given
157
+ an ``IntTuple`` shape ``S``, a bare ``*S`` splat splices its dimensions into a
158
+ shape position, e.g. ``Array[[*S, OUT], DType]``.
159
+
160
+ ``Elements[S]`` is the explicit spelling of that same splat. It is optional in
161
+ annotations, which Pyrefly checks identically either way, but it is necessary
162
+ when the annotation is evaluated at runtime: unpacking a bare ``TypeVar`` raises
163
+ ``TypeError``, while ``Elements`` is iterable.
137
164
  """
138
165
 
139
166
  def __init__(self, shape):
@@ -174,6 +201,21 @@ class Index:
174
201
  pass
175
202
 
176
203
 
204
+ class NamedInts:
205
+ """Marker bound for named integer ``**kwargs`` in einops-like APIs."""
206
+
207
+ pass
208
+
209
+
210
+ _NamedIntsT = typing.TypeVar("_NamedIntsT")
211
+
212
+
213
+ class CaptureNamedInts(int, typing.Generic[_NamedIntsT]):
214
+ """Capture einops-like axis lengths in a ``NamedInts`` type parameter."""
215
+
216
+ pass
217
+
218
+
177
219
  class ProxyMethod(typing.Generic[_T]):
178
220
  """Type-checker marker for method forwarding annotations."""
179
221
 
@@ -182,20 +224,30 @@ class ProxyMethod(typing.Generic[_T]):
182
224
 
183
225
  # `TypeVar` defaults require Python 3.13 at runtime, so omit them on Python 3.12.
184
226
  if typing.TYPE_CHECKING:
185
- _RegularNestedShape = typing.TypeVar(
186
- "_RegularNestedShape", bound=IntTuple, default=IntTuple, covariant=True
227
+ _IntTupleT = typing.TypeVar(
228
+ "_IntTupleT", bound=IntTuple, default=IntTuple, covariant=True
187
229
  )
188
230
  _Domain = typing.TypeVar(
189
231
  "_Domain", default=bool | int | float | complex, covariant=True
190
232
  )
191
233
  else:
192
- _RegularNestedShape = typing.TypeVar(
193
- "_RegularNestedShape", bound=IntTuple, covariant=True
194
- )
234
+ _IntTupleT = typing.TypeVar("_IntTupleT", bound=IntTuple, covariant=True)
195
235
  _Domain = typing.TypeVar("_Domain", covariant=True)
196
236
 
197
237
 
198
- class RegularNestedList(typing.Generic[_RegularNestedShape, _Domain]):
238
+ class IntListLiteral(typing.Generic[_IntTupleT]):
239
+ """A direct integer-list literal whose values are captured as an ``IntTuple``."""
240
+
241
+ def __class_getitem__(cls, params):
242
+ return list[int]
243
+
244
+
245
+ IntTupleOrList: typing.TypeAlias = typing.Union[
246
+ _IntTupleT, IntListLiteral[_IntTupleT], list[int]
247
+ ]
248
+
249
+
250
+ class RegularNestedList(typing.Generic[_IntTupleT, _Domain]):
199
251
  """A regular nested list literal whose scalar leaves belong to ``Domain``.
200
252
 
201
253
  Here, regular means the opposite of jagged or irregular: every sibling list
@@ -278,16 +330,6 @@ def _format_symbolic_arg(value):
278
330
  return str(value)
279
331
 
280
332
 
281
- class D:
282
- """Wrap a shape type variable so Python can evaluate dimension arithmetic."""
283
-
284
- def __new__(cls, value):
285
- return SymbolicArithExpr("var", (value,))
286
-
287
- def __class_getitem__(cls, value):
288
- return cls(value)
289
-
290
-
291
333
  def defines_assert_shape(fn: typing.Callable) -> typing.Callable:
292
334
  """
293
335
  Decorator that marks a function as an assert_shape helper.
@@ -323,6 +365,19 @@ def _check_runtime_shape(actual, shape):
323
365
  return actual
324
366
 
325
367
 
368
+ @contextlib.contextmanager
369
+ def assert_raises(
370
+ expected: type[BaseException] | tuple[type[BaseException], ...],
371
+ ) -> typing.Iterator[None]:
372
+ """Assert that the body raises an exception of the expected type."""
373
+
374
+ try:
375
+ yield
376
+ except expected:
377
+ return
378
+ raise AssertionError(f"expected {expected!r} to be raised")
379
+
380
+
326
381
  @defines_assert_shape
327
382
  def assert_shape(actual, shape, *, runtime=None):
328
383
  """
@@ -387,6 +442,117 @@ def type_shape_dsl_function(fn: _F) -> _F:
387
442
  return fn
388
443
 
389
444
 
445
+ def _shape_declaration(tokens: typing.Iterable[str]) -> typing.Callable[[_F], _F]:
446
+ """Build the decorator shared by `static_jaxtyping` and `shape_vars`.
447
+
448
+ In both, a bare token names a dimension and a ``*``-prefixed token names a
449
+ variadic shape. They differ only in how the declaration string is split into
450
+ tokens.
451
+ """
452
+
453
+ declared_names: list[str] = []
454
+ for token in tokens:
455
+ name = token.removeprefix("*")
456
+ if (
457
+ name != "_"
458
+ and name.isidentifier()
459
+ and not keyword.iskeyword(name)
460
+ and name not in declared_names
461
+ ):
462
+ declared_names.append(name)
463
+ declared_dimensions = len(declared_names)
464
+
465
+ def decorate(value: _F) -> _F:
466
+ if not isinstance(value, type):
467
+ return value
468
+
469
+ original_descriptor = value.__dict__.get("__class_getitem__")
470
+
471
+ def class_getitem(cls, params):
472
+ args = params if isinstance(params, tuple) else (params,)
473
+ ordinary = args
474
+ if cls is value:
475
+ for _ in range(declared_dimensions):
476
+ if not ordinary:
477
+ break
478
+ argument = ordinary[-1]
479
+ is_dimension = isinstance(argument, (int, IntVar)) or (
480
+ isinstance(argument, list)
481
+ and all(isinstance(dim, (int, IntVar)) for dim in argument)
482
+ )
483
+ if not is_dimension:
484
+ break
485
+ ordinary = ordinary[:-1]
486
+
487
+ delegate_descriptor = original_descriptor
488
+ if delegate_descriptor is None:
489
+ for base in cls.__mro__:
490
+ candidate = base.__dict__.get("__class_getitem__")
491
+ if candidate is None:
492
+ continue
493
+ function = getattr(candidate, "__func__", candidate)
494
+ if getattr(function, "__shape_declaration__", False):
495
+ continue
496
+ delegate_descriptor = candidate
497
+ break
498
+
499
+ if not ordinary or delegate_descriptor is None:
500
+ return cls
501
+ ordinary_params = ordinary[0] if len(ordinary) == 1 else ordinary
502
+ delegate = delegate_descriptor.__get__(None, cls)
503
+ return delegate(ordinary_params)
504
+
505
+ class_getitem.__shape_declaration__ = True
506
+ value.__class_getitem__ = classmethod(class_getitem)
507
+ return value
508
+
509
+ return decorate
510
+
511
+
512
+ def static_jaxtyping(declaration: str) -> typing.Callable[[_F], _F]:
513
+ """Declare the dimension names a function or class may use with jaxtyping.
514
+
515
+ ``declaration`` is a space-separated list of dimension names, where a
516
+ leading ``*`` marks a variadic shape::
517
+
518
+ @static_jaxtyping("batch channels *rest")
519
+ def f(x: Float[Tensor, "batch channels"]) -> Float[Tensor, "*rest"]: ...
520
+
521
+ Pyrefly reads the declaration to scope the dimensions and check the shape
522
+ strings. Without it, jaxtyping annotations keep their ordinary ``Annotated``
523
+ meaning and the array shape stays gradual. At runtime functions are unchanged,
524
+ while classes become subscriptable so their static shape arguments can appear
525
+ in evaluated annotations.
526
+ """
527
+
528
+ return _shape_declaration(declaration.split())
529
+
530
+
531
+ def shape_vars(
532
+ declaration: str, *, required: bool = False
533
+ ) -> typing.Callable[[_F], _F]:
534
+ """Declare the dimension names a function or class may use with `Shaped`.
535
+
536
+ ``declaration`` is a comma-separated list of dimension names, where a
537
+ leading ``*`` marks a variadic shape::
538
+
539
+ @shape_vars("batch, channels, *rest")
540
+ def f(
541
+ x: Shaped[Tensor, "[batch, channels, *Elements[rest]]"],
542
+ ) -> Shaped[Tensor, "[*Elements[rest]]"]: ...
543
+
544
+ On a class, the declared names become type parameters that follow the
545
+ class's own, so Pyrefly reads `Shaped[Encoder, "4, 8"]` as `Encoder[4, 8]`.
546
+ They default to gradual dimensions, so a consumer's `Encoder` or
547
+ `GenericEncoder[Input]` still checks. With ``required=True`` they have no
548
+ defaults, and Pyrefly rejects a specialization that leaves them out. At
549
+ runtime, functions are unchanged, while classes become subscriptable so that
550
+ such annotations can be evaluated.
551
+ """
552
+
553
+ return _shape_declaration(token.strip() for token in declaration.split(","))
554
+
555
+
390
556
  # `dsl` imports the public schema classes above, so defer this import until they exist.
391
557
  from . import dsl as _dsl
392
558
 
@@ -414,10 +580,19 @@ class IntVar:
414
580
  return True, so Generic[N] and TypedDict + Generic[N] both work.
415
581
 
416
582
  In pyrefly, shape_extensions.IntVar marks symbolic integer dimensions.
583
+
584
+ Subscripting with a type variable, ``IntVar[N]``, is a static no-op that wraps
585
+ a PEP 695 ``TypeVar`` for runtime evaluation: a bare ``N + 1`` raises
586
+ ``TypeError`` when the annotation is evaluated, while ``IntVar[N] + 1`` builds
587
+ a symbolic expression. For readability in nontrivial formulas, alias the import
588
+ (``from shape_extensions import IntVar as iv``) and write ``iv[N]``.
417
589
  """
418
590
 
419
591
  __class__ = typing.TypeVar
420
592
 
593
+ def __class_getitem__(cls, value):
594
+ return SymbolicArithExpr("var", (value,))
595
+
421
596
  def __init__(self, name: str, *, bound=None):
422
597
  self.__name__ = name
423
598
  self.name = name
shape_extensions/dsl.py CHANGED
@@ -89,17 +89,23 @@ def einops_einsum(spec: str, shapes: _IntTuplesSchema, /) -> _IntTupleSchema:
89
89
  ...
90
90
 
91
91
 
92
- def rearrange(spec: str, shape: _IntTupleSchema, /) -> _IntTupleSchema:
92
+ def rearrange(
93
+ spec: str, shape: _IntTupleSchema, axes: object | None = None, /
94
+ ) -> _IntTupleSchema:
93
95
  """Compute the output shape described by an einops rearrange pattern."""
94
96
  ...
95
97
 
96
98
 
97
- def reduce(spec: str, shape: _IntTupleSchema, /) -> _IntTupleSchema:
99
+ def reduce(
100
+ spec: str, shape: _IntTupleSchema, axes: object | None = None, /
101
+ ) -> _IntTupleSchema:
98
102
  """Compute the output shape described by an einops reduction pattern."""
99
103
  ...
100
104
 
101
105
 
102
- def repeat(spec: str, shape: _IntTupleSchema, /) -> _IntTupleSchema:
106
+ def repeat(
107
+ spec: str, shape: _IntTupleSchema, axes: object | None = None, /
108
+ ) -> _IntTupleSchema:
103
109
  """Compute the output shape described by an einops repeat pattern."""
104
110
  ...
105
111
 
@@ -1,8 +0,0 @@
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,,