TypeScript

In TypeScript, function types are expressed in a syntax almost the same as the one we are proposing, but the arrow token is => and arguments have names:

(x: int, y: str) => bool

The names of the arguments are not actually relevant to the type. So, for example, this is the same callable type:

(a: int, b: str) => bool

Kotlin

Function types in Kotlin permit an identical syntax to the one we are proposing, for example:

(Int, String) -> Bool

It also optionally allows adding names to the arguments, for example:

(x: Int, y: String) -> Bool

As in TypeScript, the argument names (if provided) are just there for documentation and are not part of the type itself.

Scala

Scala uses the => arrow for function types. Other than that, their syntax is the same as the one we are proposing, for example:

(Int, String) => Bool

Scala, like Python, has the ability to provide function arguments by name. Function types can optionally include names, for example:

(x: Int, y: String) => Bool

Unlike in TypeScript and Kotlin, these names are part of the type if provided - any function implementing the type must use the same names. This is similar to the extended syntax proposal we describe in our Rejected Alternatives section.

Function Definitions vs Callable Type Annotations

In all of the languages listed above, type annotations for function definitions use a : rather than a ->. For example, in TypeScript a simple add function looks like this:

function higher_order(fn: (a: string) => string): string {
  return fn("Hello, World");
}

Scala and Kotlin use essentially the same : syntax for return annotations. The : makes sense in these languages because they all use : for type annotations of parameters and variables, and the use for function return types is similar.

In Python we use : to denote the start of a function body and -> for return annotations. As a result, even though our proposal is superficially the same as these other languages the context is different. There is potential for more confusion in Python when reading function definitions that include callable types.

This is a key concern for which we are seeking feedback with our draft PEP; one idea we have floated is to use => instead to make it easier to differentiate.

The ML Language Family

Languages in the ML family, including F#, OCaml, and Haskell, all use -> to represent function types. All of them use a parentheses-free syntax with multiple arrows, for example in Haskell:

Integer -> String -> Bool

The use of multiple arrows, which differs from our proposal, makes sense for languages in this family because they use automatic currying of function arguments, which means that a multi-argument function behaves like a single-argument function returning a function.

Precedence of ->

-> binds less tightly than other operators, both inside types and in function signatures, so the following two callable types are equivalent:

(int) -> str | bool
(int) -> (str | bool)

-> associates to the right, both inside types and in function signatures. So the following pairs are equivalent:

(int) -> (str) -> bool
(int) -> ((str) -> bool)

def f() -> (int, str) -> bool: pass
def f() -> ((int, str) -> bool): pass

def f() -> (int) -> (str) -> bool: pass
def f() -> ((int) -> ((str) -> bool)): pass

Because operators bind more tightly than ->, parentheses are required whenever an arrow type is intended to be inside an argument to an operator like |:

(int) -> () -> int | () -> bool      # syntax error!
(int) -> (() -> int) | (() -> bool)  # okay

We discussed each of these behaviors and believe they are desirable:

• Union types (represented by A | B according to PEP 604) are valid in function signature returns, so we need to allow operators in the return position for consistency.
• Given that operators bind more tightly than -> it is correct that a type like bool | () -> bool must be a syntax error. We should be sure the error message is clear because this may be a common mistake.
• Associating -> to the right, rather than requiring explicit parentheses, is consistent with other languages like TypeScript and respects the principle that valid expressions should normally be substitutable when possible.

async Keyword

All of the binding rules still work for async callable types:

(int) -> async (float) -> str | bool
(int) -> (async (float) -> (str | bool))

def f() -> async (int, str) -> bool: pass
def f() -> (async (int, str) -> bool): pass

def f() -> async (int) -> async (str) -> bool: pass
def f() -> (async (int) -> (async (str) -> bool)): pass

Trailing Commas

• Following the precedent of function signatures, putting a comma in an empty arguments list is illegal: (,) -> bool is a syntax error.
• Again following precedent, trailing commas are otherwise always permitted:

  ((int,) -> bool == (int) -> bool
  ((int, **P,) -> bool == (int, **P) -> bool
  ((...,) -> bool) == ((...) -> bool)
  

Allowing trailing commas also gives autoformatters more flexibility when splitting callable types across lines, which is always legal following standard python whitespace rules.

Disallowing ... as an Argument Type

Under normal circumstances, any valid expression is permitted where we want a type annotation and ... is a valid expression. This is never semantically valid and all type checkers would reject it, but the grammar would allow it if we did not explicitly prevent this.

Since ... is meaningless as a type and there are usability concerns, our grammar rules it out and the following is a syntax error:

(int, ...) -> bool

We decided that there were compelling reasons to do this:

• The semantics of (...) -> bool are different from (T) -> bool for any valid type T: (...) is a special form indicating AnyArguments whereas T is a type parameter in the arguments list.
• ... is used as a placeholder default value to indicate an optional argument in stubs and callback protocols. Allowing it in the position of a type could easily lead to confusion and possibly bugs due to typos.
• In the tuple generic type, we special-case ... to mean “more of the same”, e.g. a tuple[int, ...] means a tuple with one or more integers. We do not use ... in a a similar way in callable types, so to prevent misunderstandings it makes sense to prevent this.

Incompatibility with other possible uses of * and **

The use of **P for supporting PEP 612 ParamSpec rules out any future proposal using a bare **<some_type> to type kwargs. This seems acceptable because:

• If we ever do want such a syntax, it would be clearer to require an argument name anyway. This would also make the type look more similar to a function signature. In other words, if we ever support typing kwargs in callable types, we would prefer (int, **kwargs: str) rather than (int, **str).
• PEP 646 unpacking syntax would rule out using *<some_type> for args. The kwargs case is similar enough that this rules out a bare **<some_type> anyway.

Compatibility with Arrow-Based Lambda Syntax

To the best of our knowledge there is no active discussion of arrow-style lambda syntax that we are aware of, but it is nonetheless worth considering what possibilities would be ruled out by adopting this proposal.

It would be incompatible with this proposal to adopt the same a parenthesized ->-based arrow syntax for lambdas, e.g. (x, y) -> x + y for lambda x, y: x + y.

Our view is that if we want arrow syntax for lambdas in the future, it would be a better choice to use =>, e.g. (x, y) => x + y. Many languages use the same arrow token for both lambdas and callable types, but Python is unique in that types are expressions and have to evaluate to runtime values. Our view is that this merits using separate tokens, and given the existing use of -> for return types in function signatures it would be more coherent to use -> for callable types and => for lambdas.

Evaluation and Structured API

We intend to create new builtin types to which the new AST nodes will evaluate, exposing them in the types module.

Our plan is to expose a structured API as if they were defined as follows:

class CallableType:
    is_async: bool
    arguments: Ellipsis | tuple[CallableTypeArgument]
    return_type: object

class CallableTypeArgument:
    kind: CallableTypeArgumentKind
    annotation: object

@enum.global_enum
class CallableTypeArgumentKind(enum.IntEnum):
    POSITIONAL_ONLY: int = ...
    PARAM_SPEC: int = ...

The evaluation rules are expressed in terms of the following pseudocode:

def evaluate_callable_type(
    callable_type: ast.CallableType | ast.AsyncCallableType:
) -> CallableType:
    return CallableType(
       is_async=isinstance(callable_type, ast.AsyncCallableType),
       arguments=_evaluate_arguments(callable_type.arguments),
       return_type=evaluate_expression(callable_type.returns),
    )

def _evaluate_arguments(arguments):
    match arguments:
        case ast.AnyArguments():
            return Ellipsis
        case ast.ArgumentsList(posonlyargs):
            return tuple(
                _evaluate_arg(arg) for arg in args
            )
        case ast.ArgumentsListConcatenation(posonlyargs, param_spec):
            return tuple(
                *(evaluate_arg(arg) for arg in args),
                _evaluate_arg(arg=param_spec, kind=PARAM_SPEC)
            )
        if isinstance(arguments, Any
    return Ellipsis

def _evaluate_arg(arg, kind=POSITIONAL_ONLY):
    return CallableTypeArgument(
        kind=POSITIONAL_ONLY,
        annotation=evaluate_expression(value)
    )

Backward-Compatible API

To get backward compatibility with the existing types.Callable API, which relies on fields __args__ and __parameters__, we can define them as if they were written in terms of the following:

import itertools
import typing

def get_args(t: CallableType) -> tuple[object]:
    return_type_arg = (
        typing.Awaitable[t.return_type]
        if t.is_async
        else t.return_type
    )
    arguments = t.arguments
    if isinstance(arguments, Ellipsis):
        argument_args = (Ellipsis,)
    else:
        argument_args = (arg.annotation for arg in arguments)
    return (
        *arguments_args,
        return_type_arg
    )

def get_parameters(t: CallableType) -> tuple[object]:
    out = []
    for arg in get_args(t):
        if isinstance(arg, typing.ParamSpec):
            out.append(t)
        else:
            out.extend(arg.__parameters__)
    return tuple(out)

Additional Behaviors of types.CallableType

As with the A | B syntax for unions introduced in PEP 604:

• The __eq__ method should treat equivalent typing.Callable values as equal to values constructed using the builtin syntax, and otherwise should behave like the __eq__ of typing.Callable.
• The __repr__ method should produce an arrow syntax representation that, when evaluated, gives us back an equal types.CallableType instance.

Functions-as-Types

An idea we looked at very early on was to allow using functions as types. The idea is allowing a function to stand in for its own call signature, with roughly the same semantics as the __call__ method of callback protocols:

def CallableType(
    positional_only: int,
    /,
    named: str,
    *args: float,
    keyword_only: int = ...,
    **kwargs: str
) -> bool: ...

f: CallableType = ...
f(5, 6.6, 6.7, named=6, x="hello", y="world")  # typechecks as bool

This may be a good idea, but we do not consider it a viable replacement for callable types:

• It would be difficult to handle ParamSpec, which we consider a critical feature to support.
• When using functions as types, the callable types are not first-class values. Instead, they require a separate, out-of-line function definition to define a type alias
• It would not support more features than callback protocols, and seems more like a shorter way to write them than a replacement for Callable.

Hybrid keyword-arrow Syntax

In the Rust language, a keyword fn is used to indicate functions in much the same way as Python’s def, and callable types are indicated using a hybrid arrow syntax Fn(i64, String) -> bool.

We could use the def keyword in callable types for Python, for example our two-parameter boolean function could be written as def(int, str) -> bool. But we think this might confuse readers into thinking def(A, B) -> C is a lambda, particularly because Javascript’s function keyword is used in both named and anonymous functions.

Parenthesis-Free Syntax

We considered a parentheses-free syntax that would have been even more concise:

int, str -> bool

We decided against it because this is not visually as similar to existing function header syntax. Moreover, it is visually similar to lambdas, which bind names with no parentheses: lambda x, y: x == y.

Requiring Outer Parentheses

A concern with the current proposal is readability, particularly when callable types are used in return type position which leads to multiple top-level -> tokens, for example:

def make_adder() -> (int) -> int:
    return lambda x: x + 1

We considered a few ideas to prevent this by changing rules about parentheses. One was to move the parentheses to the outside, so that a two-argument boolean function is written (int, str -> bool). With this change, the example above becomes:

def make_adder() -> (int -> int):
    return lambda x: x + 1

This makes the nesting of many examples that are difficult to follow clear, but we rejected it because

• Currently in Python commas bind very loosely, which means it might be common to misread (int, str -> bool) as a tuple whose first element is an int, rather than a two-parameter callable type.
• It is not very similar to function header syntax, and one of our goals was familiar syntax inspired by function headers.
• This syntax may be more readable for deaply nested callables like the one above, but deep nesting is not very common. Encouraging extra parentheses around callable types in return position via a style guide would have most of the readability benefit without the downsides.

We also considered requiring parentheses on both the parameter list and the outside, e.g. ((int, str) -> bool). With this change, the example above becomes:

def make_adder() -> ((int) -> int):
    return lambda x: x + 1

We rejected this change because:

• The outer parentheses only help readability in some cases, mostly when a callable type is used in return position. In many other cases they hurt readability rather than helping.
• We agree that it might make sense to encourage outer parentheses in several cases, particularly callable types in function return annotations. But
  • We believe it is more appropriate to encourage this in style guides, linters, and autoformatters than to bake it into the parser and throw syntax errors.
  • Moreover, if a type is complicated enough that readability is a concern we can always use type aliases, for example:

    IntToIntFunction: (int) -> int
    
    def make_adder() -> IntToIntFunction:
        return lambda x: x + 1
    

Making -> bind tighter than |

In order to allow both -> and | tokens in type expressions we had to choose precedence. In the current proposal, this is a function returning an optional boolean:

(int, str) -> bool | None  # equivalent ot (int, str) -> (bool | None)

We considered having -> bind tighter so that instead the expression would parse as ((int, str) -> bool) | None. There are two advantages to this:

• It means we no would longer have to treat None | (int, str) -> bool as a syntax error.
• Looking at typeshed today, optional callable arguments are very common because using None as a default value is a standard Python idiom. Having -> bind tighter would make these easier to write.

We decided against this for a few reasons:

• The function header def f() -> int | None: ... is legal and indicates a function returning an optional int. To be consistent with function headers, callable types should do the same.
• TypeScript is the other popular language we know of that uses both -> and | tokens in type expressions, and they have | bind tighter. While we do not have to follow their lead, we prefer to do so.
• We do acknowledge that optional callable types are common and having | bind tighter forces extra parentheses, which makes these types harder to write. But code is read more often than written, and we believe that requiring the outer parentheses for an optional callable type like ((int, str) -> bool) | None is preferable for readability.

Introducing type-strings

Another idea was adding a new “special string” syntax and putting the type inside of it, for example t”(int, str) -> bool”. We rejected this because it is not as readable, and seems out of step with guidance from the Steering Council on ensuring that type expressions do not diverge from the rest of Python’s syntax.

Improving Usability of the Indexed Callable Type

If we do not want to add new syntax for callable types, we could look at how to make the existing type easier to read. One proposal would be to make the builtin callable function indexable so that it could be used as a type:

callable[[int, str], bool]

This change would be analogous to PEP 585 that made built in collections like list and dict usable as types, and would make imports more convenient, but it wouldn’t help readability of the types themselves much.

In order to reduce the number of brackets needed in complex callable types, it would be possible to allow tuples for the argument list:

callable[(int, str), bool]

This actually is a significant readability improvement for multi-argument functions, but the problem is that it makes callables with one arguments, which are the most common arity, hard to write: because (x) evaluates to x, they would have to be written like callable[(int,), bool]. We find this awkward.

Moreover, none of these ideas help as much with reducing verbosity as the current proposal, nor do they introduce as strong a visual cue as the -> between the parameter types and the return type.

Alternative APIs

We considered having the runtime data types.CallableType use a more structured API where there would be separate fields for posonlyargs and param_spec. The current proposal was was inspired by the inspect.Signature type.

We use “argument” in our field and type names, unlike “parameter” as in inspect.Signature, in order to avoid confusion with the callable_type.__parameters__ field from the legacy API that refers to type parameters rather than callable parameters.

Using the plain return type in __args__ for async types

It is debatable whether we are required to preserve backward compatiblity of __args__ for async callable types like async (int) -> str. The reason is that one could argue they are not expressible directly using typing.Callable, and therefore it would be fine to set __args__ as (int, int) rather than (int, typing.Awaitable[int]).

But we believe this would be problematic. By preserving the appearance of a backward-compatible API while actually breaking its semantics on async types, we would cause runtime type libraries that attempt to interpret Callable using __args__ to fail silently.

It is for this reason that we automatically wrap the return type in Awaitable.