PEP 718: subscriptable functions

[guido (Guido van Rossum)]

I will try to answer each of Carl’s toplevel bullets. Hopefully it’s not too Gargantuan a task.

@carljm

• The PEP should clarify that the runtime __getitem__ does not validate whether the function is generic, let alone how many type parameters it has; this is left purely for static verification by type checkers. (This can be discovered by looking at the runtime implementation, but the PEP should be clear about it.)

Indeed. It behaves like generic builtins, which do no checking and return types.GenericAlias (e.g. list[int, str] is not caught at runtime); it does not act like generic user-defined classes, which return typing.Generic, which does validation.

• Should type checkers allow a symbol typed with a Callable type to be subscripted, or only objects the type checker knows to be instances of one of the five mentioned “function types”?
  • If so, that for sure will lead to runtime errors not caught by the type checker. Many objects are callable (and thus can inhabit Callable types) and will not be subscriptable at runtime, including many common standard library types: functools.partial, functools.lru_cache, functools.cache… If the proposal is that this risk is acceptable, the PEP needs to make a good case for why.
  • If not, that will dramatically limit applicability. Most decorators can’t return anything more precise than a Callable type, which would effectively mean that most decorated functions can never be subscripted, which will feel to users like a strange and arbitrary limitation.
  • This was previously asked in the discussion thread and there was a fair bit of discussion around it, but the PEP remains entirely silent on it.
  • In general the PEP relies quite a bit on an assumed “we already have GenericAlias for classes, so it’ll work just as well here”, but this issue doesn’t exist in the same way for classes, so it’s important for the PEP to address it in detail.

I need to think hard about this one. You’re asking whether, after

@some_decorator
def func[T](x: T, n: int=1) -> list[T]:
    return [x] * n

can we write func[int]? I’d say that depends on whether type checkers today treat func as a generic function. If they do, subscription should be allowed too; if they don’t, it shouldn’t be.

I think the answer lies in the decorator’s signature. If it’s written as (Callable) -> Callable that sounds like it won’t be allowed. But if it’s written as (and now I’m making up syntax) [T: Callable](T) -> T it should – I tested in the mypy sandbox that such a decorator preserves genericity, so in that case thefunc should be subscriptable.

• Another runtime issue: functools.wraps crashes if used on instances of types.GenericAlias (their attribute proxy is read-only), so if a generic alias is ever passed to a function accepting a callable and using functools.wraps, that will cause a crash.

Okay, so for a generic function g, you can write wraps(g), but you can’t say wraps(g[int]). I think that’s a fine outcome, given that typical use of wraps is in a decorator, which (usually) takes a function definition. And if there’s a use case, wraps could easily be changed to special-case GenericAlias – not something that this PEP needs to prescribe (as long we have no strong use case for it).

• I personally find the section on “monomorphization and reification” very unconvincing. It’s fine for something to be left as separate future work, but there’s so little concept of how this could even possibly work presented in the PEP, that I don’t even find it justified to claim that this PEP meaningfully “opens the door” for it. In a certain sense, that door has already been opened and we already walked through it with PEP 747. But suggesting that PEP 718 can improve on PEP 747 in some way requires at least suggesting an answer to the question of how a function that expects reified generics would receive them if it is called without being explicitly specialized via subscript. Or would such functions only work if called via a GenericAlias?

Agreed. Let’s just cut that paragraph from the PEP.

• For introspection purposes, there should be a publicly supported way to tell whether a GenericAlias is for a function or class, without having to isinstance check its __origin__ against five different types.

Indeed. Let’s return an instance of a new class, FunctionGenericAlias, which subclasses GenericAlias. (This would make life easier for a future change to functools.wraps as well, see above.)

• The overload section needs a clearer specification of the modification to the overload algorithm, including precision about what is meant by “subscription may succeed.”

We need to think more about what to say. I’m no expert on overloading so I’ll decline giving it a try. But in the end it seems like it’s just an update to the PEP’s prose, not an objection to the proposal.

• TypeVarTuple section should include an example of how to successfully subscript a function generic over a TypeVarTuple.

Ditto.

• Can you subscript a function generic over a ParamSpec? Example? What about a function generic over both a TypeVarTuple and a ParamSpec? What about a TypeVarTuple followed by a regular TypeVar? Maybe there are existing rules for some of this in the typing spec for classes that we can follow; that should be said explicitly.

Tritto?

• Is it ever allowed to subscript like foo[*tuple[int, str]] in order to disambiguate when subscripting a function parameterized by a TypeVarTuple? PEP 646 allows this in some contexts.

Quarto???

• The example C[int].method[str](0, "") is marked # OK but is wrong, method should be called on an instance of C or an explicit self must be passed.

There’s a missing call – the example should be

C[int]().method[str](0, "")

• There was a fair amount of discussion in the thread about performance, some measurements were done, and there was a lot of talk about why it does or doesn’t matter. The topic isn’t mentioned in the PEP.

Yeah, we should add a summary of that discussion (or its outcome) to the PEP.

[guido (Guido van Rossum)]

Agreed that we need a prototype implementation. Are there any type checker authors here who like this idea enough to give that a try? (Carl, you’re involved in Ty – any appetite?)

The only alternative I see is for someone to use their free Fable budget to let a coding agent write a prototype. (Perhaps for mypy or pyright, since LLMs probably still have seen more code written in Python and TypeScript than in Rust during their training.)

[carljm (Carl Meyer)]

Fully agree that most of my feedback was feedback on the PEP (to be addressed by expanding and clarifying the PEP text), not substantive feedback on the proposal. The important exception is this question:

@carljm

• Should type checkers allow a symbol typed with a Callable type to be subscripted, or only objects the type checker knows to be instances of one of the five mentioned “function types”?

Which I still think is quite a hard problem for the PEP.

@guido

I think the answer lies in the decorator’s signature. If it’s written as (Callable) -> Callable that sounds like it won’t be allowed. But if it’s written as (and now I’m making up syntax) [T: Callable](T) -> T it should – I tested in the mypy sandbox that such a decorator preserves genericity, so in that case thefunc should be subscriptable.

Decorators are allowed to return generic callables, and nothing requires that the callables they return be function objects. Consider:

from typing import Callable

class Callback:
    def __call__[T](self, arg: T) -> T:
        return arg

def make_a_generic_callable[T](func) -> Callable[[T], T]:
    return Callback()

@make_a_generic_callable
def func(): ...

# `func` is now typed as a generic callable, so the below should be allowed?
# But this will error at runtime, because instances of `Callback` are not subscriptable.
func[int]

The problem is that “being a generic Callable” and “being an instance of one of the five function types supported at runtime for subscripting” are not the same thing.

@guido

Agreed that we need a prototype implementation. Are there any type checker authors here who like this idea enough to give that a try? (Carl, you’re involved in Ty – any appetite?)

I don’t think I will personally be able to drive this, but certainly willing to take a look at an implementation in ty if someone gives it a try.

[randolf-scholz]

from typing import Callable

class Callback:
    def __call__[T](self, arg: T) -> T:
        return arg

def make_a_generic_callable[T](func) -> Callable[[T], T]:
    return Callback()

@make_a_generic_callable
def func(): ...

# `func` is now typed as a generic callable, so the below should be allowed?
# But this will error at runtime, because instances of `Callback` are not subscriptable.
func[int]

I don’t think this is quite right, shouldn’t func be something like Callable[[Unknown], Unknown] in this case? Consider:

@make_a_generic_callable[int]
def func(): ...

then clearly, func would be Callable[[int], int], and not def [T: int](arg: T, /) -> T.

[carljm (Carl Meyer)]

I would prefer your interpretation; that would be the consistent application of PEP 695 syntax in this scenario. T should be scoped to make_a_generic_callable, and thus if it is not determined by the call to make_a_generic_callable, it should fall back to Unknown.

Pre-695, there was an implicit (I don’t think it was written anywhere?) rule that in a case like def f() -> Callable[[T], T], T would be implicitly scoped to the returned callable rather than to f.

Unfortunately(?), all type checkers seem to have decided to continue applying that ad hoc rule, even when PEP 695 syntax is used in a way that should clarify the scoping of T. At root, this happens because people in the ecosystem do want to write decorators that return generic callables, and PEP 695 still does not provide any syntax for annotating a generic callable type. So we’ve followed suit in ty, to avoid breaking compatibility with that pattern (which we observed in real codebases.)

You can try my example and find that all type checkers (at least ty, pyright, mypy, pyrefly, zuban) reveal the type int or Literal[1] for reveal_type(func(1)).

I would be happy for a proposal to clearly specify the elimination of this wart, but I think practically it may require syntax for spelling a generic callable type in an annotation.

I also think PEP 718 should probably explicitly clarify how it interacts with this special case. Does your version with @make_a_generic_callable[int] re-scope T to the function itself instead of the return type, leading to a return of (int) -> int? Or is it an error, because T has already been scoped to the return callable, making make_a_generic_callable itself no longer generic, and that can’t be changed per-callsite? I suspect the latter is the version that would fall out of existing type checkers given an implementation of PEP 718 without any additional consideration of this case. Re-scoping type variables based on call-site usage seems very questionable and probably hard to implement.

EDIT: I guess we do already have syntax for spelling a generic callable type in an annotation: a callable Protocol with method-scoped generic __call__. This is a lot more verbose, but perhaps it’s enough to justify removing the re-scoping rule?

[randolf-scholz]

Yes this is something that can currently only be expressed with Callback protocols.

Eric once posted a nice overview here: PEP Idea: Extend spec of Callable to accept unpacked TypeDicts to specify keyword-only parameters - #24 by erictraut

If we ever get a nicer callable syntax, as suggested by PEP 677 or in PEP 677 with an easier-to-parse and more expressive syntax hopefully one would be able to express this “inline” without having to write a Callback Protocol every time.

FWIW I think lambda[T](arg: T) -> T would be a reasonable syntax. Once something like that is available, type checkers can probably deprecate the old behavior that conflicts with regular scoping rules. (or earlier with some transition period guiding users to use Callback Protocols instead)

[tmk (Thomas Kehrenberg)]

@randolf-scholz

I think lambda[T](arg: T) -> T would be a reasonable syntax

Someone should write a PEP for that!

[guido (Guido van Rossum)]

@carljm

The most important thing that I think this PEP needs before it can be considered is a reference implementation in at least one type checker. This is both the hardest and the most valuable part of any typing PEP. It invariably uncovers (and helps to answer) tricky edge cases and design questions, like some of the ones I mention below. In recent years a reference implementation has been a baseline requirement for all typing PEPs; some have had multiple reference implementations!

Hi Carl! I used some of my Fable credit to have it write a prototype for mypy. It complied:

PEP 718 prototype written by Fable

I have to admit that I didn’t review the code – it’s only a prototype --, but I ran it and it appears to work. It includes a fair amount of tests (including many edge cases) and they pass. You have to use it as mypy --enable-incomplete-feature SubscriptableFunctions to enable the new feature.

What we learned included a surprise: mypy strips unused typevars, and def f[T]() -> None: ... is not generic and cannot be indexed. We can’t find anything in the spec about this. The runtime is unambiguous: def f[T]() -> None: pass gives f.__type_params__ == (T,). Previously, this wasn’t observable in the type system except possibly through reveal_type() – PEP 718 makes it observable (you get an error on f[int] if f is not generic). Note that a generic class that doesn’t use its typevar is still considered generic, so this would be a wart whereby classes and functions don’t fully work the same way.

If we want such functions to be generic/subscriptable, the PEP should say so, and this would end up in the spec and mypy (and possibly others) would have to be changed. Alternatively, the PEP should explicitly say that unused typevars are stripped, and we should update the spec.

Note that this has consequences if only some of the typevars are used too – after def f[S, T](arg; T) -> T: ... the revealed signature is def [T] (arg: T) -> T and this affects subscripting: f[int] is valid but f[str, int] is not.

---

Going over Carl’s other questions, several of them have (partial) answers from the prototype:

• Callable – the prototype allows subscription iff it sees a generic function (this is the natural checker rule) but doesn’t resolve the dilemma: it allows some subscriptions that fail at runtime (like functools.partial and lru_cache). Here I wonder: there’s a recent discussion about introducing more kinds of Callable types; maybe there could be a separate Callable subtype specifically for subscriptable Callables? I haven’t thought very deeply about this yet. We could also just accept that type checkers may occasionally accept things that fail at runtime. Aren’t there already examples of such elsewhere in the spec (not counting cast and Any)?

• The prototype defines an overload algorithm that we should copy into the spec.

• The questions about TypeVarTuple and ParamSpec are answered affirmatively; I am pasting the AI’s reply below (click “Details”).

Here are the worked examples, each paired with its class equivalent.

TypeVarTuple

python

def variadic[*Ts](*args: *Ts) -> tuple[*Ts]: ...

variadic[int, str]        # def (int, str) -> tuple[int, str]
variadic[int, str](1, "a")  # tuple[int, str]
variadic[int, str](1, 2)    # error: arg 2 expected str
variadic[int]             # def (int) -> tuple[int]
variadic[()]              # def () -> tuple[()]     — empty case works

Prefix and suffix TypeVars both bind correctly, matching the class forms exactly:

python

def pre[T, *Ts](x: T, *rest: *Ts) -> tuple[T, *Ts]: ...
pre[int, str, bytes]      # def (x: int, str, bytes) -> tuple[int, str, bytes]

def suf[*Ts, T](*args: *Ts, last: T) -> tuple[*Ts, T]: ...
suf[int, str, bytes]      # def (int, str, *, last: bytes) -> tuple[int, str, bytes]

That suffix case is Carl’s “TypeVarTuple followed by a regular TypeVar” question — it works, and greedy-middle absorption puts int, str in Ts and bytes in T, same as class SC[*Ts, T] yields SC[int, str, bytes].

PEP 646 unpacked-tuple disambiguation — his other explicit question — also works, in all three spellings:

python

variadic[*tuple[int, str]]        # def (int, str) -> tuple[int, str]
variadic[Unpack[tuple[int, str]]] # same
variadic[*tuple[int, ...]]        # def (*args: int) -> tuple[int, ...]

The homogeneous case behaves as for classes (VC[*tuple[int, ...]]), so the answer to “is it ever allowed?” is yes, with the same semantics.

ParamSpec

python

def wrap[**P, R](f: Callable[P, R]) -> Callable[P, R]: ...

wrap[[int, str], bool]   # def (f: def (int, str) -> bool) -> def (int, str) -> bool
wrap[..., bool]          # def (f: def (*Any, **Any) -> bool) -> ...
wrap[[], bool]           # def (f: def () -> bool) -> ...

Concatenate and ParamSpec passthrough, inside a scope where the ParamSpec is bound:

python

def scope(g: Callable[P2, None]) -> None:
    wrap[Concatenate[int, P2], bool]  # def (f: def (int, *P2.args, **P2.kwargs) -> bool) -> ...
    wrap[P2, bool]                    # def (f: def (*P2.args, **P2.kwargs) -> bool) -> ...

And both TypeVarTuple and ParamSpec together, Carl’s third question:

python

def both[*Ts, **P](*args: *Ts, cb: Callable[P, None]) -> None: ...
both[int, str, [bool]]   # def (int, str, *, cb: def (bool))

On whether the class rules apply

Confirmed for every form I tested, but let me be precise about what that confirms. I ran each function case against a structurally identical generic class and compared: bracketed lists, ..., empty list, the bare-single-argument shorthand (one[int] → [int], matching OC[int] → OC[[int]]), Concatenate, passthrough, arity errors, and the mixed TVT+ParamSpec case. Every pair agreed on the resulting parameter list. Where they errored, they errored identically — including an unbound-ParamSpec-at-module-scope case where both produced the same two diagnostics.

The caveat: this confirms mypy’s function path and mypy’s class path agree. It doesn’t independently verify that mypy’s class behavior is itself spec-conformant, and it’s one checker. The mechanism behind the agreement is that my semanal change routes functions through the same allow_unpack / has_param_spec machinery classes use, so agreement is somewhat by construction — which is the point, but worth stating plainly rather than presenting as independent corroboration.

So the defensible claim for the PEP is: making ParamSpec and TypeVarTuple subscription follow the existing class rules is implementable by reusing existing machinery, and produces consistent results across every form in the spec. That’s enough to justify the PEP simply saying “same rules as generic classes” rather than restating them.

[carljm (Carl Meyer)]

Nice, thank you!

My feeling is that a generic function with syntactically explicit type variables should still be treated as generic, with all of its typevars, even if they are unused. This matches the runtime introspection, and I think gives the least confusing results in the face of the new ability to explicitly subscript functions. So this would be an area where mypy would be treated as out-of-conformance.

The kinds-of-Callable issue remains the most thorny for me. It is true that there are existing unsoundnesses in the spec, but that doesn’t make me eager to add more of them.

This seems like an unpleasant footgun to leave laying around. You have some code that explicitly subscripts a function (maybe from a third-party dependency), later an upgrade to that dependency changes the function to a partial (maybe even only in certain runtime codepaths, so a quick smoke test with the new dependency version seems fine), and now your code blows up with a runtime exception in production.

I think what seems especially unpleasant about this is that it’s not just “the type checker did not catch a runtime exception”. It’s “a code change that exists only for the sake of static type checking itself broke runtime, and the static type checker can’t help you avoid that.”

So I have to say that while I don’t love blocking this PEP on the more-kinds-of-callables discussion (which hasn’t even reached PEP stage yet, and may end up itself blocked on intersections), I also remain hesitant to move forward on PEP 718 with this hole in it.

Other than that issue, I’m satisfied with your/Fable’s take so far, and would be happy to see an updated draft of the PEP text addressing my comments.

[mikeshardmind (Michael H)]

@guido

• it allows some subscriptions that fail at runtime (like functools.partial and lru_cache

This is the part that concerns me the most about it, but I also think it’s a fixable problem without needing to solve the more general “kinds of callables” problem by making partial and lrucache (and similar) handle this, as well as ensuring that existing machinery and functions for this handle it (would also look at functools.wraps).

Which to me, would probably look like all functions being subscriptable at runtime, retaining enough context for the various machinery to be introspected, and leaving any enforcement to a mix of static analysis tools, and tools that operate on introspection at runtime.

[mikeshardmind (Michael H)]

For some additional context on making various introspection play nicely with cases like decorators, there’s currently some ugly things I’m doing to make inspecting wrapped transforming decorators work as expected with runtime introspection. This case is for generating an inspectable signature, but it’s sort of in the same vein. We can probably do something to make it easier for people to write decorators, partial applications, and other functions that wrap the original function while remaining compatible.

[guido (Guido van Rossum)]

@carljm

My feeling is that a generic function with syntactically explicit type variables should still be treated as generic, with all of its typevars, even if they are unused.

I was hoping you’d say that. The branch now has Fable’s fix, conditional under the same feature flag.

---

Regarding the more serious problem of runtime crashes in e.g. functools.partial and lru_cache, Mike H suggests that we could just fix these and other specific cases, like wraps, at runtime (i.e., give them a __getitem__ method that returns a types.GenericAlias instance). That still feels uncomfortable, because it doesn’t address the problem in general.

I’m going to do an experiment with the stricter version that only allows subscripting things statically known as generic function objects.

I also found an existing mypy issue for this, filed in April.

[mikeshardmind (Michael H)]

@guido

Mike H suggests that we could just fix these and other specific cases, like wraps, at runtime (i.e., give them a __getitem__ method that returns a types.GenericAlias instance). That still feels uncomfortable, because it doesn’t address the problem in general.

To be clear, the special case would be cases like wraps forwarding the __getitem__, and partial generating a new __getitem__ but that all functions would have one:

@mikeshardmind

Which to me, would probably look like all functions being subscriptable at runtime

It’s fine to allow functions that weren’t defined as explicitly generic to be subscripted at runtime, if it’s not a case of something wrapped, then static analysis or introspection can warn or error when it looks at it and expects any subscript to match something else that isn’t there.

[carljm (Carl Meyer)]

It is already the case in the runtime proof of concept implementation of PEP 718 that all functions are subscriptable; that’s not under debate, but it also doesn’t help. Any Python object with a __call__ method can inhabit a Callable type. This PEP does not propose to make all Python objects subscriptable (nor should it, IMO).

[mikeshardmind (Michael H)]

I guess I should take more care to be clear in what I’m saying here.

I see all functions being subscribable as correct and mostly sufficient (and wasn’t implying that I believed it wasn’t already being done, just that I agree with that being the way). The primary missing link is making it easy for people to write the right thing when they use an object that isn’t a function to wrap a function, and to do that for them in the common cases.

I don’t think this pep needs to be stalled on non-function callables. Let something like functools.wraps handle forwarding getitem in the simplest case, provide something that covers common cases like partial application, even if it’s just a recipe for library authors to use, and let adoption demand drive any changes needed outside the standard library.

As long as we make doing the right thing easy enough, this shouldn’t be a major concern. Wrapping a function with something other than a function while still annotating the wrapping as returning a callable is already in the territory of “things that require special care”

[guido (Guido van Rossum)]

While I was at it, I had a lesser AI port @Gobot1234’s runtime changes, originally a branch of 3.13.0a0, to the main branch, slated to become 3.16. It’s here: Ported @Gobot1234's function-subscript branch from 3.13a0 to main (3.16) · gvanrossum/cpython@a373a4f · GitHub

[PabloRuizCuevas (Pablo)]

Nice to see this moving again, I had somewhat limited through this lasts months, but I’m ready to help again drafting the modifications following @carljm suggestions , @Jelle and the comments on this thread.

[guido (Guido van Rossum)]

I turned all changes into draft pull requests:

mypy:

• Draft implementation for PEP 718 -- function subscription by gvanrossum · Pull Request #21880 · python/mypy · GitHub (lenient version)
• Alternate draft implementation for PEP 718 -- stricter rules by gvanrossum · Pull Request #21881 · python/mypy · GitHub (strict version)

CPython:

• Runtime changes for PEP 718 -- generic function subscription by gvanrossum · Pull Request #156201 · python/cpython · GitHub (port of @Gobot1234’s patch to 3.13)

[guido (Guido van Rossum)]

Harking back a week or so…

@jorenham

In case of

def f[T]() -> T: ...

x = f()

type-checkers will complain that f is missing a type argument. But in case of

def f[T=int]() -> T: ...

x = f()

You’d expect that type-checkers won’t complain.

Mypy, at least, complains on both function definitions that there should be at least one argument using T. Pyright is better, but still complains on the first definition, not on the call (not sure where you expected the error TBH). Ty complains about both definitions, but its concern is that ... returns None which is incompatible with T and T=int.

[jorenham (Joren Hammudoglu)]

@guido

but its concern is that ... returns None which is incompatible with T and T=int.

Ah I probably should’ve been more clear about that, but I was using ... in the .pyi stubs sense here.

---

Right now I agree that in case of f[T]() -> T type-checkers are right to complain: T is a free type-variable here, so it’s impossible to resolve it.
However, this PEP will change that, because it’d allow us to write x = f[int](), causing T to resolve to int. So now, depending on how f is called, T of f[T]() -> T can actually be determined. But as before, f() will still be invalid.

@guido

not sure where you expected the error TBH

Once PEP 718 is accepted, the solvability^[1] of T@f will depend on how f is called, i.e. with or without explicit type argument. So reporting the error at the call site seems like the way to go to me.

---

1. not sure if that’s actually a word, but I’m sure you know what I mean ↩︎