pyrefly-shape-extensions 1.4.0.dev2__py3-none-any.whl → 1.4.0.dev4__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.dev2
3
+ Version: 1.4.0.dev4
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,6 +44,9 @@ 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
@@ -55,3 +58,31 @@ binds `Values` to `IntTuple[2, 3]`; an existing or starred list remains gradual,
55
58
  while a direct literal containing a non-integer is rejected.
56
59
 
57
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=TWx-7WyN7tDMqznvJdLAzlHmdFIlvX_ucYVFEqvCNQs,24391
2
+ shape_extensions/dsl.py,sha256=Yz8_nLzjS2D-cNNgUoR9r2kHCa-BZTgMsU25Z_QhKm0,3580
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.dev4.dist-info/METADATA,sha256=Bpz1yJdLJKAZFXjBxR2L80RZeYXXvPSFDEYopZbc9VA,4599
6
+ pyrefly_shape_extensions-1.4.0.dev4.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
7
+ pyrefly_shape_extensions-1.4.0.dev4.dist-info/licenses/LICENSE,sha256=2m03A-0Ry-Qr0hLHJZV8mNojy_8ZmMBfpLPZdtGljpM,1088
8
+ pyrefly_shape_extensions-1.4.0.dev4.dist-info/RECORD,,
@@ -13,9 +13,29 @@ safe to evaluate in runtime annotations.
13
13
 
14
14
  import contextlib
15
15
  import keyword
16
+ import sys
16
17
  import typing
18
+ import warnings
17
19
  from dataclasses import dataclass
18
20
 
21
+ # A shape annotation carrying its shape as string metadata. To Pyrefly, the
22
+ # string supplies type arguments to a generic class, after any explicit ones:
23
+ # `Shaped[Tensor, "[M, N]"]` is `Tensor[[M, N]]`, and
24
+ # `Shaped[Encoder[Input], "Dim, Hidden"]` is `Encoder[Input, Dim, Hidden]`. On
25
+ # `int` and on an integer tuple, the string instead replaces the type:
26
+ # `Shaped[int, "N"]` is `Int[N]`, and `Shaped[tuple[int, int], "[M, N]"]` is
27
+ # `IntTuple[M, N]`. Every other type checker reads the first argument alone. At
28
+ # runtime it is an ordinary `Annotated` object. The names inside the string are
29
+ # declared by an enclosing `shape_vars`.
30
+ #
31
+ # This must stay an import alias: mypy rejects `Shaped = typing.Annotated` as
32
+ # "not valid as a type". `compatibility_tests` pins this.
33
+ #
34
+ # Ruff recognizes `Annotated` only under that name, so it reports the names in a
35
+ # `Shaped` string as undefined (F821). Code that uses `Shaped` should disable
36
+ # F821; a type checker already reports genuinely undefined names.
37
+ from typing import Annotated as Shaped
38
+
19
39
  __all__ = [
20
40
  "Elements",
21
41
  "Int",
@@ -26,8 +46,11 @@ __all__ = [
26
46
  "IntVar",
27
47
  "Index",
28
48
  "MapIntTuples",
49
+ "NamedInts",
50
+ "CaptureNamedInts",
29
51
  "ProxyMethod",
30
52
  "RegularNestedList",
53
+ "Shaped",
31
54
  "SymbolicArithExpr",
32
55
  "assert_shape",
33
56
  "assert_raises",
@@ -35,6 +58,7 @@ __all__ = [
35
58
  "defines_assert_shape",
36
59
  "gufunc_broadcast",
37
60
  "index_shape",
61
+ "shape_vars",
38
62
  "static_jaxtyping",
39
63
  "type_shape_dsl_function",
40
64
  ]
@@ -48,7 +72,79 @@ def _return_int(cls, params):
48
72
  return int
49
73
 
50
74
 
51
- def _patch_torch_if_available() -> None:
75
+ class _PostImportHook:
76
+ """A one-shot `sys.meta_path` finder that calls `callback` after a module loads.
77
+
78
+ The hook wraps the loader that the finders after it return for `name`, so
79
+ `callback` runs once the module body has finished executing, while the
80
+ import system still holds the module's import lock. The import that loaded
81
+ the module, and any concurrent import of it that reaches the hook, therefore
82
+ return only after `callback` has run. An import already resolving the module
83
+ when the hook is installed can bypass it. A failed load leaves the hook
84
+ registered, so a retried import still runs `callback`.
85
+ """
86
+
87
+ def __init__(self, name, callback):
88
+ self.name = name
89
+ self.callback = callback
90
+
91
+ def find_spec(self, fullname, path, target=None):
92
+ if fullname != self.name:
93
+ return None
94
+ meta_path = sys.meta_path
95
+ # An import still iterating the list this hook was removed from can
96
+ # call it after removal; the finders after it are consulted anyway.
97
+ if self not in meta_path:
98
+ return None
99
+ for finder in meta_path[meta_path.index(self) + 1 :]:
100
+ find_spec = getattr(finder, "find_spec", None)
101
+ if find_spec is None:
102
+ continue
103
+ spec = find_spec(fullname, path, target)
104
+ if spec is None:
105
+ continue
106
+ # A legacy loader without `exec_module` loads without the callback.
107
+ if hasattr(spec.loader, "exec_module"):
108
+ spec.loader = _PostImportLoader(spec, self)
109
+ else:
110
+ self.remove()
111
+ return spec
112
+ return None
113
+
114
+ def remove(self) -> None:
115
+ # Replace the list rather than mutating it: the import system iterates
116
+ # `sys.meta_path` without a lock, and an in-place removal would make a
117
+ # concurrent import skip the finder after this one.
118
+ sys.meta_path = [finder for finder in sys.meta_path if finder is not self]
119
+
120
+
121
+ class _PostImportLoader:
122
+ """Delegates to a module's real loader, then runs its `_PostImportHook`."""
123
+
124
+ def __init__(self, spec, hook):
125
+ self.spec = spec
126
+ self.loader = spec.loader
127
+ self.hook = hook
128
+
129
+ def __getattr__(self, name):
130
+ return getattr(self.loader, name)
131
+
132
+ def create_module(self, spec):
133
+ return self.loader.create_module(spec)
134
+
135
+ def exec_module(self, module):
136
+ # The module body sees its real loader, and keeps it afterwards.
137
+ self.spec.loader = self.loader
138
+ if getattr(module, "__loader__", None) is self:
139
+ module.__loader__ = self.loader
140
+ self.loader.exec_module(module)
141
+ self.hook.remove()
142
+ self.hook.callback()
143
+
144
+
145
+ def _patch_torch() -> None:
146
+ """Make Torch classes subscriptable at runtime. Calling it again is a no-op."""
147
+
52
148
  try:
53
149
  import torch # @manual
54
150
  import torch.nn as nn # @manual
@@ -89,7 +185,50 @@ def _patch_torch_if_available() -> None:
89
185
  cls.__class_getitem__ = classmethod(_return_class)
90
186
 
91
187
 
92
- _patch_torch_if_available()
188
+ def _patch_torch_safely() -> None:
189
+ """Report incompatible Torch classes without breaking the Torch import."""
190
+
191
+ try:
192
+ _patch_torch()
193
+ except (AttributeError, TypeError) as error:
194
+ warnings.warn(
195
+ f"Could not patch torch for shape annotations: {error}",
196
+ RuntimeWarning,
197
+ stacklevel=2,
198
+ )
199
+
200
+
201
+ def _is_initializing(module) -> bool:
202
+ """Whether the import system is still executing `module`'s body."""
203
+
204
+ return getattr(getattr(module, "__spec__", None), "_initializing", False)
205
+
206
+
207
+ def _patch_torch_when_imported() -> None:
208
+ """Patch Torch now if it has been imported, and otherwise once it is.
209
+
210
+ Importing `shape_extensions` alone never imports Torch.
211
+ """
212
+
213
+ torch = sys.modules.get("torch")
214
+ if _is_initializing(torch):
215
+ # Another thread may be importing Torch, in which case `import torch`
216
+ # waits for that import to finish. If Torch's own initialization
217
+ # imported this module, it instead returns the same partially
218
+ # initialized module, which cannot be patched yet. A failed import
219
+ # leaves `sys.modules`, so the hook below patches a retried import.
220
+ with contextlib.suppress(ImportError):
221
+ import torch # @manual
222
+ torch = sys.modules.get("torch")
223
+ if _is_initializing(torch):
224
+ return
225
+ if torch is None:
226
+ sys.meta_path.insert(0, _PostImportHook("torch", _patch_torch_safely))
227
+ return
228
+ _patch_torch_safely()
229
+
230
+
231
+ _patch_torch_when_imported()
93
232
 
94
233
 
95
234
  def _patch_jax_if_available() -> None:
@@ -179,6 +318,21 @@ class Index:
179
318
  pass
180
319
 
181
320
 
321
+ class NamedInts:
322
+ """Marker bound for named integer ``**kwargs`` in einops-like APIs."""
323
+
324
+ pass
325
+
326
+
327
+ _NamedIntsT = typing.TypeVar("_NamedIntsT")
328
+
329
+
330
+ class CaptureNamedInts(int, typing.Generic[_NamedIntsT]):
331
+ """Capture einops-like axis lengths in a ``NamedInts`` type parameter."""
332
+
333
+ pass
334
+
335
+
182
336
  class ProxyMethod(typing.Generic[_T]):
183
337
  """Type-checker marker for method forwarding annotations."""
184
338
 
@@ -405,24 +559,16 @@ def type_shape_dsl_function(fn: _F) -> _F:
405
559
  return fn
406
560
 
407
561
 
408
- def static_jaxtyping(declaration: str) -> typing.Callable[[_F], _F]:
409
- """Declare the dimension names a function or class may use with jaxtyping.
562
+ def _shape_declaration(tokens: typing.Iterable[str]) -> typing.Callable[[_F], _F]:
563
+ """Build the decorator shared by `static_jaxtyping` and `shape_vars`.
410
564
 
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.
565
+ In both, a bare token names a dimension and a ``*``-prefixed token names a
566
+ variadic shape. They differ only in how the declaration string is split into
567
+ tokens.
422
568
  """
423
569
 
424
570
  declared_names: list[str] = []
425
- for token in declaration.split():
571
+ for token in tokens:
426
572
  name = token.removeprefix("*")
427
573
  if (
428
574
  name != "_"
@@ -462,7 +608,7 @@ def static_jaxtyping(declaration: str) -> typing.Callable[[_F], _F]:
462
608
  if candidate is None:
463
609
  continue
464
610
  function = getattr(candidate, "__func__", candidate)
465
- if getattr(function, "__static_jaxtyping__", False):
611
+ if getattr(function, "__shape_declaration__", False):
466
612
  continue
467
613
  delegate_descriptor = candidate
468
614
  break
@@ -473,13 +619,57 @@ def static_jaxtyping(declaration: str) -> typing.Callable[[_F], _F]:
473
619
  delegate = delegate_descriptor.__get__(None, cls)
474
620
  return delegate(ordinary_params)
475
621
 
476
- class_getitem.__static_jaxtyping__ = True
622
+ class_getitem.__shape_declaration__ = True
477
623
  value.__class_getitem__ = classmethod(class_getitem)
478
624
  return value
479
625
 
480
626
  return decorate
481
627
 
482
628
 
629
+ def static_jaxtyping(declaration: str) -> typing.Callable[[_F], _F]:
630
+ """Declare the dimension names a function or class may use with jaxtyping.
631
+
632
+ ``declaration`` is a space-separated list of dimension names, where a
633
+ leading ``*`` marks a variadic shape::
634
+
635
+ @static_jaxtyping("batch channels *rest")
636
+ def f(x: Float[Tensor, "batch channels"]) -> Float[Tensor, "*rest"]: ...
637
+
638
+ Pyrefly reads the declaration to scope the dimensions and check the shape
639
+ strings. Without it, jaxtyping annotations keep their ordinary ``Annotated``
640
+ meaning and the array shape stays gradual. At runtime functions are unchanged,
641
+ while classes become subscriptable so their static shape arguments can appear
642
+ in evaluated annotations.
643
+ """
644
+
645
+ return _shape_declaration(declaration.split())
646
+
647
+
648
+ def shape_vars(
649
+ declaration: str, *, required: bool = False
650
+ ) -> typing.Callable[[_F], _F]:
651
+ """Declare the dimension names a function or class may use with `Shaped`.
652
+
653
+ ``declaration`` is a comma-separated list of dimension names, where a
654
+ leading ``*`` marks a variadic shape::
655
+
656
+ @shape_vars("batch, channels, *rest")
657
+ def f(
658
+ x: Shaped[Tensor, "[batch, channels, *Elements[rest]]"],
659
+ ) -> Shaped[Tensor, "[*Elements[rest]]"]: ...
660
+
661
+ On a class, the declared names become type parameters that follow the
662
+ class's own, so Pyrefly reads `Shaped[Encoder, "4, 8"]` as `Encoder[4, 8]`.
663
+ They default to gradual dimensions, so a consumer's `Encoder` or
664
+ `GenericEncoder[Input]` still checks. With ``required=True`` they have no
665
+ defaults, and Pyrefly rejects a specialization that leaves them out. At
666
+ runtime, functions are unchanged, while classes become subscriptable so that
667
+ such annotations can be evaluated.
668
+ """
669
+
670
+ return _shape_declaration(token.strip() for token in declaration.split(","))
671
+
672
+
483
673
  # `dsl` imports the public schema classes above, so defer this import until they exist.
484
674
  from . import dsl as _dsl
485
675
 
shape_extensions/dsl.py CHANGED
@@ -73,6 +73,19 @@ def concat(
73
73
  return _IntTupleSchema((*left, *right))
74
74
 
75
75
 
76
+ def axis_reduce(
77
+ shape: _IntTupleSchema,
78
+ axis: int | tuple[int, ...] | None,
79
+ keepdims: bool,
80
+ empty_means_all: bool,
81
+ scalar_axis_ok: bool,
82
+ scalar_tuple_axis_ok: bool,
83
+ /,
84
+ ) -> _IntTupleSchema:
85
+ """Reduce axes, preserving dimensions outside a symbolic-rank middle."""
86
+ return _IntTupleSchema()
87
+
88
+
76
89
  def prod(xs: _IntTupleSchema, /) -> _IntSchema: ...
77
90
 
78
91
 
@@ -89,17 +102,23 @@ def einops_einsum(spec: str, shapes: _IntTuplesSchema, /) -> _IntTupleSchema:
89
102
  ...
90
103
 
91
104
 
92
- def rearrange(spec: str, shape: _IntTupleSchema, /) -> _IntTupleSchema:
105
+ def rearrange(
106
+ spec: str, shape: _IntTupleSchema, axes: object | None = None, /
107
+ ) -> _IntTupleSchema:
93
108
  """Compute the output shape described by an einops rearrange pattern."""
94
109
  ...
95
110
 
96
111
 
97
- def reduce(spec: str, shape: _IntTupleSchema, /) -> _IntTupleSchema:
112
+ def reduce(
113
+ spec: str, shape: _IntTupleSchema, axes: object | None = None, /
114
+ ) -> _IntTupleSchema:
98
115
  """Compute the output shape described by an einops reduction pattern."""
99
116
  ...
100
117
 
101
118
 
102
- def repeat(spec: str, shape: _IntTupleSchema, /) -> _IntTupleSchema:
119
+ def repeat(
120
+ spec: str, shape: _IntTupleSchema, axes: object | None = None, /
121
+ ) -> _IntTupleSchema:
103
122
  """Compute the output shape described by an einops repeat pattern."""
104
123
  ...
105
124
 
@@ -1,8 +0,0 @@
1
- shape_extensions/__init__.py,sha256=lr9SOVkvgPqeV6t0fx9JT7fr-Ipvc9BxWyBVyq22HN4,17198
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.dev2.dist-info/METADATA,sha256=ayw0BqxnMc4GrbSTMZaO7NQ3gwb08mE1FZYz84ltVAo,2890
6
- pyrefly_shape_extensions-1.4.0.dev2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
7
- pyrefly_shape_extensions-1.4.0.dev2.dist-info/licenses/LICENSE,sha256=2m03A-0Ry-Qr0hLHJZV8mNojy_8ZmMBfpLPZdtGljpM,1088
8
- pyrefly_shape_extensions-1.4.0.dev2.dist-info/RECORD,,