pyrefly-shape-extensions 1.3.1__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.1
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
@@ -44,4 +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
+ `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.
@@ -8,4 +8,9 @@ typing primitives so annotations such as `Tensor[B, T]`, `IntVar("B")`, and
8
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.1"
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,8 +24,8 @@ __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",
@@ -150,7 +149,10 @@ class Elements:
150
149
  return f"Elements[{self.shape!r}]"
151
150
 
152
151
 
153
- class Int[T]:
152
+ _T = typing.TypeVar("_T")
153
+
154
+
155
+ class Int(typing.Generic[_T]):
154
156
  """Symbolic integer type for dimension values.
155
157
 
156
158
  At runtime this is a no-op generic class. The type checker uses the
@@ -160,7 +162,7 @@ class Int[T]:
160
162
  pass
161
163
 
162
164
 
163
- class Flag[T]:
165
+ class Flag(typing.Generic[_T]):
164
166
  """Marker for a literal-preserving value that controls type-level evaluation."""
165
167
 
166
168
  pass
@@ -172,12 +174,47 @@ class Index:
172
174
  pass
173
175
 
174
176
 
175
- class ProxyMethod[T]:
177
+ class ProxyMethod(typing.Generic[_T]):
176
178
  """Type-checker marker for method forwarding annotations."""
177
179
 
178
180
  pass
179
181
 
180
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
+
181
218
  @dataclass(frozen=True)
182
219
  class SymbolicArithExpr:
183
220
  """Runtime representation of symbolic dimension arithmetic."""
@@ -262,17 +299,12 @@ def defines_assert_shape(fn: typing.Callable) -> typing.Callable:
262
299
  return fn
263
300
 
264
301
 
265
- @defines_assert_shape
266
- def assert_shape(actual, shape):
267
- """
268
- At runtime, assert that a tuple-like shape has the expected value.
302
+ def _check_runtime_shape(actual, shape):
303
+ """Compare `actual` against `shape`, raising on a mismatch.
269
304
 
270
- Pyrefly will validate that the statically modeled shape matches, similar to
271
- `assert_type`.
272
-
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.
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.
276
308
  """
277
309
 
278
310
  # Preserve legacy calls that pass an array object rather than its shape.
@@ -291,6 +323,34 @@ def assert_shape(actual, shape):
291
323
  return actual
292
324
 
293
325
 
326
+ @defines_assert_shape
327
+ def assert_shape(actual, shape, *, runtime=None):
328
+ """
329
+ At runtime, assert that a tuple-like shape has the expected value.
330
+
331
+ Pyrefly will validate that the statically modeled shape matches, similar to
332
+ `assert_type`.
333
+
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)
352
+
353
+
294
354
  def index_shape(_shape: IntTuple, _index: typing.Any) -> IntTuple:
295
355
  """Runtime placeholder for Pyrefly's native shape-indexing intrinsic."""
296
356
 
@@ -318,7 +378,10 @@ class MapIntTuples:
318
378
  return tuple
319
379
 
320
380
 
321
- 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:
322
385
  """Runtime no-op for a user-defined type-level shape DSL function."""
323
386
 
324
387
  return fn
@@ -395,44 +458,3 @@ class IntVar:
395
458
 
396
459
  def has_default(self):
397
460
  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()