Add validation that `Shape` is always solved [rfc] (#4898) by stroxler · Pull Request #4898 · facebook/pyrefly

stroxler · 2026-09-10T23:10:05Z

Summary:

This adds a best-effort, shape-specific lint for a common stub-authoring mistake: forgetting the empty-shape default on a function whose ArrayLike-style parameter accepts either an array or a scalar.

For example:

type ArrayLike[Shape: IntTuple] = Array[Shape] | float

def as_array[Shape: IntTuple](value: ArrayLike[Shape]) -> Array[Shape]: ...

A scalar call cannot infer Shape, so the return silently becomes gradual. The lint asks the author to write Shape: IntTuple = [], making the intended scalar-to-empty-shape behavior explicit.

The check deliberately handles only IntTuple parameters that occur in some but not all arms of a top-level union after alias expansion, and only when the parameter affects the return type and has no other required parameter that always constrains it. It is not a typing-spec error or a proof that every call constrains every type variable. In particular, optional and variadic sources are left alone because overload ordering and runtime arity constraints make a broader definition-site rule noisy.

Differential Revision: D119580993

meta-codesync · 2026-09-10T23:10:13Z

@stroxler has exported this pull request. If you are a Meta employee, you can view the originating Diff in D119580993.

Summary: **The problem** This commit is a response to a concern about the previous diff, where we propose using annotations like ``` def f[S: IntTuple = []](x: Array[S] | float) -> Array[S]: ... ``` to model functions that can accept scalars and treat them "as if" they were empty-shape arrays (real examples usually are higher-arity and involve broadcasting, etc). The concern is that it would be very easy to forget the default, and accidentally have `f` behave gradually instead when passed a scalar. The same concern would apply through an alias if we had ``` type ArrayLike[Shape: IntTuple]: ndarray[Shape] | Array[Shape] | float ``` where ``` def f[S: IntTuple = []](x: ArrayLike[S]) -> Array[S]: ... ``` is what we want, but if we accidentally wrote ``` def f[S: IntTuple](x: ArrayLike[S]) -> Array[S]: ... ``` we would instead have a type that degrades to gradual `IntTuple` silently when passed a scalar. **This commit** This commit proposes adding a validation that, if an `IntTuple` type parameter appears in a return type, we can ensure it is bound or defaulted in calls. **Could this be more general?** Interestingly, this problem is *not* a shape-specific rule; the exact same issue is easy to create with vanilla types, like ``` def g[T](x: list[T] | int) -> dict[str, T] ``` which will have `T` come out unsolved (and then either solved to `Any` or turned into a partial type) when called as `g(3)` for example. So we could potentially make this validation general. But for now I'm applying it only to `IntTuple`-bound type params because I think the general case might need a bigger discussion. Differential Revision: D119580993

Summary: This adds a best-effort, shape-specific lint for a common stub-authoring mistake: forgetting the empty-shape default on a function whose ArrayLike-style parameter accepts either an array or a scalar. For example: ``` type ArrayLike[Shape: IntTuple] = Array[Shape] | float def as_array[Shape: IntTuple](value: ArrayLike[Shape]) -> Array[Shape]: ... ``` A scalar call cannot infer `Shape`, so the return silently becomes gradual. The lint asks the author to write `Shape: IntTuple = []`, making the intended scalar-to-empty-shape behavior explicit. The check deliberately handles only `IntTuple` parameters that occur in some but not all arms of a top-level union after alias expansion, and only when the parameter affects the return type and has no other required parameter that always constrains it. It is not a typing-spec error or a proof that every call constrains every type variable. In particular, optional and variadic sources are left alone because overload ordering and runtime arity constraints make a broader definition-site rule noisy. Differential Revision: D119580993

Summary: In jax and other array libraries, it's not unusual to auto-promote scalars to empty-shape arrays so that broadcasting works. For example, we can have ``` def add[S0: IntTuple, S1: IntTuple]( x: Array[S0] | float, y: Array[S1] | float ) -> Array[broadcast(S0, S1)] ``` and we want something like `f(3.141, y)` to produce the same shape as `y`. The problem is that this doesn't actually work: if we pass a `float` for `x`, we wind up failing to constrain `S0`, and it solves to gradual `IntTuple`, which means we drop the shape. The workaround is to use a default: ``` def add[S0: IntTuple = [], S1: IntTuple = []]( x: Array[S0] | float, y: Array[S1] | float ) -> Array[broadcast(S0, S1)] ``` so that taking the scalar branch of the union leads to the unconstrained shape parameter being solved to `[]` by the default. This diff adds support for the `[]` shorthand in this syntactic position for `IntTuple`-constrained type parameters, and verifies that it works as expected Differential Revision: D119566820

Summary: This adds a best-effort, shape-specific lint for a common stub-authoring mistake: forgetting the empty-shape default on a function whose ArrayLike-style parameter accepts either an array or a scalar. For example: ``` type ArrayLike[Shape: IntTuple] = Array[Shape] | float def as_array[Shape: IntTuple](value: ArrayLike[Shape]) -> Array[Shape]: ... ``` A scalar call cannot infer `Shape`, so the return silently becomes gradual. The lint asks the author to write `Shape: IntTuple = []`, making the intended scalar-to-empty-shape behavior explicit. The check deliberately handles only `IntTuple` parameters that occur in some but not all arms of a top-level union after alias expansion, and only when the parameter affects the return type and has no other required parameter that always constrains it. It is not a typing-spec error or a proof that every call constrains every type variable. In particular, optional and variadic sources are left alone because overload ordering and runtime arity constraints make a broader definition-site rule noisy. Differential Revision: D119580993

github-actions · 2026-09-11T23:44:46Z

According to mypy_primer, this change doesn't affect type check results on a corpus of open source code. ✅

meta-cla Bot added the cla signed label Sep 10, 2026

github-actions Bot assigned stroxler Sep 10, 2026

meta-codesync Bot added the meta-exported label Sep 10, 2026

github-actions Bot added the size/l label Sep 10, 2026

This comment has been minimized.

Sign in to view

meta-codesync Bot changed the title ~~Add validation that Shape is always solved [rfc]~~ Add validation that Shape is always solved [rfc] (#4898) Sep 11, 2026

meta-codesync Bot force-pushed the export-D119580993 branch from 2fd09e6 to b939df4 Compare September 11, 2026 14:45