pyrefly-shape-extensions 1.3.0.dev3__tar.gz → 1.3.0.dev4__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.0.dev3
3
+ Version: 1.3.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/
@@ -8,7 +8,7 @@ description = "Shape typing primitives and DSL for Pyrefly tensor shape tracking
8
8
  readme = "README.md"
9
9
  requires-python = ">=3.12"
10
10
  license = { file = "LICENSE" }
11
- version = "1.3.0.dev3"
11
+ version = "1.3.0.dev4"
12
12
  keywords = ["typechecker", "typechecking", "shapes", "tensor", "pyrefly"]
13
13
  classifiers = [
14
14
  "Development Status :: 4 - Beta",
@@ -20,16 +20,20 @@ __all__ = [
20
20
  "Elements",
21
21
  "Int",
22
22
  "IntTuple",
23
+ "IntTuples",
23
24
  "IntVar",
25
+ "Index",
26
+ "MapIntTuples",
24
27
  "ProxyMethod",
25
28
  "SymbolicArithExpr",
26
29
  "TypeVarTuple",
27
30
  "assert_shape",
28
31
  "broadcast",
29
32
  "defines_assert_shape",
33
+ "gufunc_broadcast",
30
34
  "shaped_array",
35
+ "index_shape",
31
36
  "type_shape_dsl_function",
32
- "uses_shape_dsl",
33
37
  ]
34
38
 
35
39
 
@@ -100,6 +104,13 @@ class IntTuple:
100
104
  return cls
101
105
 
102
106
 
107
+ class IntTuples:
108
+ """A tuple whose elements are `IntTuple` values."""
109
+
110
+ def __new__(cls, iterable=()):
111
+ return tuple(iterable)
112
+
113
+
103
114
  class Elements:
104
115
  """Inverse of ``tuple[Unpack[S]]``: extracts the element sequence from a IntTuple carrier.
105
116
 
@@ -143,6 +154,12 @@ class Flag[T]:
143
154
  pass
144
155
 
145
156
 
157
+ class Index:
158
+ """Marker for an index value retained for type-level shape evaluation."""
159
+
160
+ pass
161
+
162
+
146
163
  class ProxyMethod[T]:
147
164
  """Type-checker marker for method forwarding annotations."""
148
165
 
@@ -261,8 +278,13 @@ def assert_shape(x, shape):
261
278
  return x
262
279
 
263
280
 
264
- def shaped_array(*, shape: str) -> typing.Callable[[type], type]:
265
- """Decorator that marks a class as carrying a shape TypeVarTuple."""
281
+ def shaped_array(
282
+ *, shape: str, builtin_indexing: bool = True
283
+ ) -> typing.Callable[[type], type]:
284
+ """Mark a class as carrying a shape parameter.
285
+
286
+ ``builtin_indexing=False`` lets its annotated ``__getitem__`` determine the result.
287
+ """
266
288
 
267
289
  def decorator(cls: type) -> type:
268
290
  return cls
@@ -270,18 +292,57 @@ def shaped_array(*, shape: str) -> typing.Callable[[type], type]:
270
292
  return decorator
271
293
 
272
294
 
273
- def broadcast(*_args: typing.Any) -> IntTuple:
274
- """Runtime placeholder for Pyrefly's native type-level broadcast intrinsic."""
295
+ def index_shape(_shape: IntTuple, _index: typing.Any) -> IntTuple:
296
+ """Runtime placeholder for Pyrefly's native shape-indexing intrinsic."""
275
297
 
276
298
  return IntTuple()
277
299
 
278
300
 
301
+ class MapIntTuples:
302
+ """Map a unary type lambda over an ``IntTuples`` value.
303
+
304
+ A forward map preserves each source shape::
305
+
306
+ MapIntTuples[lambda S: Tensor[S], tuple[IntTuple[2], IntTuple[3, 4]]]
307
+
308
+ A map used directly as a parameter annotation reverses that relationship, so
309
+ passing ``(Tensor[IntTuple[2]], Tensor[IntTuple[3, 4]])`` infers the source
310
+ as ``tuple[IntTuple[2], IntTuple[3, 4]]``. Each symbolic source may occur in
311
+ only one parameter pattern, keeping inference unambiguous.
312
+
313
+ At runtime this is a placeholder that does not inspect its arguments,
314
+ because valid static sources such as ``Any`` and ``Never`` cannot be mapped
315
+ as Python values.
316
+ """
317
+
318
+ def __class_getitem__(cls, params):
319
+ return tuple
320
+
321
+
279
322
  def type_shape_dsl_function[F: typing.Callable](fn: F) -> F:
280
323
  """Runtime no-op for a user-defined type-level shape DSL function."""
281
324
 
282
325
  return fn
283
326
 
284
327
 
328
+ # `dsl` imports the public schema classes above, so defer this import until they exist.
329
+ from . import dsl as _dsl
330
+
331
+
332
+ @type_shape_dsl_function
333
+ def gufunc_broadcast(spec: str, shapes: IntTuples) -> IntTuple:
334
+ """Compute the output shape described by a generalized ufunc signature."""
335
+
336
+ return _dsl._gufunc_broadcast(spec, shapes)
337
+
338
+
339
+ @type_shape_dsl_function
340
+ def broadcast(left: IntTuple, right: IntTuple) -> IntTuple:
341
+ spec = "(),()->()"
342
+ shapes = _dsl.IntTuples((left, right))
343
+ return gufunc_broadcast(spec, shapes)
344
+
345
+
285
346
  class IntVar:
286
347
  """Symbolic variable with arithmetic support for tensor shape dimensions.
287
348
 
@@ -370,22 +431,3 @@ class TypeVarTuple:
370
431
  @property
371
432
  def __typing_is_unpacked_typevartuple__(self):
372
433
  return True
373
-
374
-
375
- def uses_shape_dsl(
376
- ir_fn: typing.Callable,
377
- *,
378
- capture_init: list[str] | None = None,
379
- ) -> typing.Callable[[typing.Callable], typing.Callable]:
380
- """Decorator that associates a shape DSL function with an API function.
381
-
382
- At runtime this is a no-op: the decorator arguments are ignored and the
383
- decorated function is returned unchanged. Pyrefly uses this decorator
384
- at type-checking time to route bound arguments through the shape DSL
385
- for return-type refinement.
386
- """
387
-
388
- def decorator(fn: typing.Callable) -> typing.Callable:
389
- return fn
390
-
391
- return decorator
@@ -0,0 +1,89 @@
1
+ # Copyright (c) Meta Platforms, Inc. and affiliates.
2
+ #
3
+ # This source code is licensed under the MIT license found in the
4
+ # LICENSE file in the root directory of this source tree.
5
+
6
+ # pyre-ignore-all-errors
7
+
8
+ """DSL internals for shape typing.
9
+
10
+ Only used inside DSL definition files (e.g. torch/_shapes.pyi), not in
11
+ normal stubs or user code.
12
+ """
13
+
14
+ # TODO(stroxler): Unquote `typing.TypeIs` when Python 3.13+ is the minimum version.
15
+ import typing
16
+
17
+ from . import (
18
+ Int as _IntSchema,
19
+ IntTuple as _IntTupleSchema,
20
+ IntTuples as _IntTuplesSchema,
21
+ )
22
+
23
+ # DSL builtins: these exist so that DSL definition files can import them
24
+ # and avoid unbound-name errors. The DSL compiler recognizes these names
25
+ # as builtins regardless of the Python-level definitions here.
26
+
27
+
28
+ def Invalid(message: str) -> typing.Any:
29
+ """Return an invalid shape computation from a type-shape DSL body."""
30
+
31
+ ...
32
+
33
+
34
+ class Int:
35
+ """Operations that produce values in the DSL integer domain."""
36
+
37
+ @staticmethod
38
+ def gradual() -> typing.Any: ...
39
+
40
+
41
+ class IntTuple(_IntTupleSchema):
42
+ """Operations that produce values in the DSL integer-tuple domain."""
43
+
44
+ def __new__(cls, values: typing.Iterable[typing.Any]) -> _IntTupleSchema:
45
+ return _IntTupleSchema(values)
46
+
47
+ @staticmethod
48
+ def gradual() -> typing.Any: ...
49
+
50
+
51
+ class IntTuples(_IntTuplesSchema):
52
+ """Operations that produce tuples of `IntTuple` values in the DSL."""
53
+
54
+ def __new__(cls, values: typing.Iterable[_IntTupleSchema]) -> _IntTuplesSchema:
55
+ return _IntTuplesSchema(values)
56
+
57
+ @staticmethod
58
+ def gradual() -> typing.Any: ...
59
+
60
+
61
+ # `TypeGuard`, not `TypeIs`: a false result does not narrow symbolic or gradual `Int` values.
62
+ def is_concrete_int(value: object) -> typing.TypeGuard[_IntSchema]: ...
63
+
64
+
65
+ def is_int_value(value: object) -> "typing.TypeIs[int]": ...
66
+
67
+
68
+ def concat(
69
+ left: typing.Iterable[typing.Any], right: typing.Iterable[typing.Any], /
70
+ ) -> _IntTupleSchema:
71
+ """Concatenate two shape values inside a type-shape DSL body."""
72
+
73
+ return _IntTupleSchema((*left, *right))
74
+
75
+
76
+ def prod(xs: _IntTupleSchema, /) -> _IntSchema: ...
77
+
78
+
79
+ def sum(xs: _IntTupleSchema, /) -> _IntSchema: ...
80
+
81
+
82
+ def einsum(spec: str, shapes: _IntTuplesSchema, /) -> _IntTupleSchema:
83
+ """Compute the output shape described by an explicit einsum equation."""
84
+ ...
85
+
86
+
87
+ def _gufunc_broadcast(spec: str, shapes: _IntTuplesSchema, /) -> _IntTupleSchema:
88
+ """Compute a gufunc result shape inside a type-level shape DSL function."""
89
+ return _IntTupleSchema()
@@ -1,123 +0,0 @@
1
- # Copyright (c) Meta Platforms, Inc. and affiliates.
2
- #
3
- # This source code is licensed under the MIT license found in the
4
- # LICENSE file in the root directory of this source tree.
5
-
6
- # pyre-ignore-all-errors
7
-
8
- """DSL internals for shape typing.
9
-
10
- Only used inside DSL definition files (e.g. torch/_shapes.pyi), not in
11
- normal stubs or user code.
12
- """
13
-
14
- from __future__ import annotations
15
-
16
- import typing
17
-
18
- from . import Int as _IntSchema, IntTuple as _IntTupleSchema
19
-
20
-
21
- def shape_dsl_function(fn: typing.Callable) -> typing.Callable:
22
- """Marks a function as a shape DSL function.
23
-
24
- At runtime this is a no-op: the decorated function is returned unchanged.
25
- Pyrefly uses this decorator at type-checking time to convert the function
26
- body to DSL IR via convert_fndef.
27
- """
28
- return fn
29
-
30
-
31
- # DSL builtins: these exist so that DSL definition files can import them
32
- # and avoid unbound-name errors. The DSL compiler recognizes these names
33
- # as builtins regardless of the Python-level definitions here.
34
-
35
-
36
- class ShapedArray:
37
- """A shaped-array value in the DSL, constructed via ShapedArray(shape=[...])."""
38
-
39
- shape: list[int]
40
-
41
- def __init__(self, *, shape: list[int]) -> None:
42
- self.shape = shape
43
-
44
-
45
- class symint:
46
- """A symbolic integer dimension in the DSL."""
47
-
48
- ...
49
-
50
-
51
- class Error(Exception):
52
- """DSL error raised via `raise Error("message")`."""
53
-
54
- ...
55
-
56
-
57
- class _Unknown:
58
- """Sentinel returned from DSL functions to fall back to the declared return type."""
59
-
60
- ...
61
-
62
-
63
- Unknown: _Unknown = _Unknown()
64
-
65
-
66
- def Invalid(message: str) -> typing.Any:
67
- """Return an invalid shape computation from a type-shape DSL body."""
68
-
69
- ...
70
-
71
-
72
- class Int:
73
- """Operations that produce values in the DSL integer domain."""
74
-
75
- @staticmethod
76
- def gradual() -> typing.Any: ...
77
-
78
-
79
- class IntTuple(_IntTupleSchema):
80
- """Operations that produce values in the DSL integer-tuple domain."""
81
-
82
- def __new__(cls, values: typing.Iterable[typing.Any]) -> _IntTupleSchema:
83
- return _IntTupleSchema(values)
84
-
85
- @staticmethod
86
- def gradual() -> typing.Any: ...
87
-
88
-
89
- def is_concrete_int(value: typing.Any) -> bool: ...
90
-
91
-
92
- def is_int_value(value: object) -> typing.TypeIs[int]: ...
93
-
94
-
95
- def concat(
96
- left: typing.Iterable[typing.Any], right: typing.Iterable[typing.Any], /
97
- ) -> _IntTupleSchema:
98
- """Concatenate two shape values inside a type-shape DSL body."""
99
-
100
- return _IntTupleSchema((*left, *right))
101
-
102
-
103
- @typing.overload
104
- def prod(xs: _IntTupleSchema, /) -> _IntSchema: ...
105
-
106
-
107
- @typing.overload
108
- def prod(xs: list[int]) -> int: ...
109
-
110
-
111
- def prod(xs: _IntTupleSchema | list[int]) -> _IntSchema | int:
112
- """Compute the product of a list of dimension sizes."""
113
- ...
114
-
115
-
116
- def sum(xs: list[int]) -> int:
117
- """Compute the sum of a list of dimension sizes."""
118
- ...
119
-
120
-
121
- def parse_einsum_equation(spec: str) -> list[list[list[int]]]:
122
- """Parse an einsum equation string into output map and check pairs."""
123
- ...