pyrefly-shape-extensions 1.4.0.dev1__py3-none-any.whl → 1.4.0.dev2__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.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/
@@ -49,4 +49,9 @@ literals; for example, `[[1, 2], [3, 4]]` binds `Shape` to `[2, 2]`. Unsupported
49
49
  containers and irregular literals use ordinary typing and any fallback overload
50
50
  supplied by the consumer.
51
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
+
52
57
  The package is versioned in lockstep with Pyrefly.
@@ -0,0 +1,8 @@
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,,
@@ -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,14 +11,17 @@ 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
 
17
19
  __all__ = [
18
- "D",
19
20
  "Elements",
20
21
  "Int",
22
+ "IntListLiteral",
21
23
  "IntTuple",
24
+ "IntTupleOrList",
22
25
  "IntTuples",
23
26
  "IntVar",
24
27
  "Index",
@@ -27,10 +30,12 @@ __all__ = [
27
30
  "RegularNestedList",
28
31
  "SymbolicArithExpr",
29
32
  "assert_shape",
33
+ "assert_raises",
30
34
  "broadcast",
31
35
  "defines_assert_shape",
32
36
  "gufunc_broadcast",
33
37
  "index_shape",
38
+ "static_jaxtyping",
34
39
  "type_shape_dsl_function",
35
40
  ]
36
41
 
@@ -123,17 +128,17 @@ class IntTuples:
123
128
 
124
129
 
125
130
  class Elements:
126
- """Inverse of ``tuple[Unpack[S]]``: extracts the dimensions from an ``IntTuple``.
131
+ """Explicit inverse of ``tuple[Unpack[...]]`` for shape type variables.
127
132
 
128
133
  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.
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.
137
142
  """
138
143
 
139
144
  def __init__(self, shape):
@@ -182,20 +187,30 @@ class ProxyMethod(typing.Generic[_T]):
182
187
 
183
188
  # `TypeVar` defaults require Python 3.13 at runtime, so omit them on Python 3.12.
184
189
  if typing.TYPE_CHECKING:
185
- _RegularNestedShape = typing.TypeVar(
186
- "_RegularNestedShape", bound=IntTuple, default=IntTuple, covariant=True
190
+ _IntTupleT = typing.TypeVar(
191
+ "_IntTupleT", bound=IntTuple, default=IntTuple, covariant=True
187
192
  )
188
193
  _Domain = typing.TypeVar(
189
194
  "_Domain", default=bool | int | float | complex, covariant=True
190
195
  )
191
196
  else:
192
- _RegularNestedShape = typing.TypeVar(
193
- "_RegularNestedShape", bound=IntTuple, covariant=True
194
- )
197
+ _IntTupleT = typing.TypeVar("_IntTupleT", bound=IntTuple, covariant=True)
195
198
  _Domain = typing.TypeVar("_Domain", covariant=True)
196
199
 
197
200
 
198
- class RegularNestedList(typing.Generic[_RegularNestedShape, _Domain]):
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]):
199
214
  """A regular nested list literal whose scalar leaves belong to ``Domain``.
200
215
 
201
216
  Here, regular means the opposite of jagged or irregular: every sibling list
@@ -278,16 +293,6 @@ def _format_symbolic_arg(value):
278
293
  return str(value)
279
294
 
280
295
 
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
296
  def defines_assert_shape(fn: typing.Callable) -> typing.Callable:
292
297
  """
293
298
  Decorator that marks a function as an assert_shape helper.
@@ -323,6 +328,19 @@ def _check_runtime_shape(actual, shape):
323
328
  return actual
324
329
 
325
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
+
326
344
  @defines_assert_shape
327
345
  def assert_shape(actual, shape, *, runtime=None):
328
346
  """
@@ -387,6 +405,81 @@ def type_shape_dsl_function(fn: _F) -> _F:
387
405
  return fn
388
406
 
389
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
+
390
483
  # `dsl` imports the public schema classes above, so defer this import until they exist.
391
484
  from . import dsl as _dsl
392
485
 
@@ -414,10 +507,19 @@ class IntVar:
414
507
  return True, so Generic[N] and TypedDict + Generic[N] both work.
415
508
 
416
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]``.
417
516
  """
418
517
 
419
518
  __class__ = typing.TypeVar
420
519
 
520
+ def __class_getitem__(cls, value):
521
+ return SymbolicArithExpr("var", (value,))
522
+
421
523
  def __init__(self, name: str, *, bound=None):
422
524
  self.__name__ = name
423
525
  self.name = name
@@ -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,,