TypeScript

InTypeScript,function types are expressed in a syntax almost the same as the one weare 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 inKotlin permitan 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 fordocumentation and are not part of the type itself.

Scala

Scalauses the=> arrow for function types. Other than that, their syntax isthe 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 ifprovided - any function implementing the type must use the same names.This is similar to the extended syntax proposal we describe in ourRejected Alternatives section.

Function Definitions vs Callable Type Annotations

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

functionhigher_order(fn:(a:string)=>string):string{returnfn("Hello, World");}

Scala and Kotlin use essentially the same: syntax for returnannotations. The: makes sense in these languages because theyall use: for type annotations ofparameters and variables, and the use for function return types issimilar.

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

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

The ML Language Family

Languages in the ML family, includingF#,OCaml,andHaskell, all use-> to represent function types. All of them use a parentheses-freesyntax with multiple arrows, for example in Haskell:

Integer->String->Bool

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

Precedence of ->

-> binds less tightly than other operators, both inside types andin function signatures, so the following two callable types areequivalent:

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

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

(int)->(str)->bool(int)->((str)->bool)deff()->(int,str)->bool:passdeff()->((int,str)->bool):passdeff()->(int)->(str)->bool:passdeff()->((int)->((str)->bool)):pass

Because operators bind more tightly than->, parentheses arerequired whenever an arrow type is intended to be inside an argumentto 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 byA|B according toPEP 604) arevalid in function signature returns, so we need to allow operatorsin the return position for consistency.
• Given that operators bind more tightly than-> it is correctthat a type likebool|()->bool must be a syntax error. Weshould be sure the error message is clear because this may be acommon mistake.
• Associating-> to the right, rather than requiring explicitparentheses, is consistent with other languages like TypeScript andrespects the principle that valid expressions should normally besubstitutable 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))deff()->async(int,str)->bool:passdeff()->(async(int,str)->bool):passdeff()->async(int)->async(str)->bool:passdeff()->(async(int)->(async(str)->bool)):pass

Trailing Commas

• Following the precedent of function signatures, putting a comma inan empty arguments list is illegal:(,)->bool is a syntaxerror.
• Again following precedent, trailing commas are otherwise alwayspermitted:

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

Allowing trailing commas also gives autoformatters more flexibilitywhen splitting callable types across lines, which is always legalfollowing standard python whitespace rules.

Disallowing... as an Argument Type

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

Since... is meaningless as a type and there are usabilityconcerns, our grammar rules it out and the following is a syntaxerror:

(int,...)->bool

We decided that there were compelling reasons to do this:

• The semantics of(...)->bool are different from(T)->boolfor any valid type T:(...) is a special form indicatingAnyArguments whereasT is a type parameter in the argumentslist.
• ... is used as a placeholder default value to indicate anoptional argument in stubs and callback protocols. Allowing it inthe position of a type could easily lead to confusion and possiblybugs due to typos.
• In thetuple generic type, we special-case... to mean“more of the same”, e.g. atuple[int,...] means a tuple withone or more integers. We do not use... in a a similar wayin callable types, so to prevent misunderstandings it makes senseto prevent this.

Incompatibility with other possible uses of* and**

The use of**P for supportingPEP 612ParamSpec rules out anyfuture proposal using a bare**<some_type> to typekwargs. This seems acceptable because:

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

Compatibility with Arrow-Based Lambda Syntax

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

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

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

Evaluation and Structured API

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

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

classCallableType:is_async:boolarguments:Ellipsis|tuple[CallableTypeArgument]return_type:objectclassCallableTypeArgument:kind:CallableTypeArgumentKindannotation:object@enum.global_enumclassCallableTypeArgumentKind(enum.IntEnum):POSITIONAL_ONLY:int=...PARAM_SPEC:int=...

The evaluation rules are expressed in terms of the followingpseudocode:

defevaluate_callable_type(callable_type:ast.CallableType|ast.AsyncCallableType:)->CallableType:returnCallableType(is_async=isinstance(callable_type,ast.AsyncCallableType),arguments=_evaluate_arguments(callable_type.arguments),return_type=evaluate_expression(callable_type.returns),)def_evaluate_arguments(arguments):matcharguments:caseast.AnyArguments():returnEllipsiscaseast.ArgumentsList(posonlyargs):returntuple(_evaluate_arg(arg)forarginargs)caseast.ArgumentsListConcatenation(posonlyargs,param_spec):returntuple(*(evaluate_arg(arg)forarginargs),_evaluate_arg(arg=param_spec,kind=PARAM_SPEC))ifisinstance(arguments,AnyreturnEllipsisdef_evaluate_arg(arg,kind=POSITIONAL_ONLY):returnCallableTypeArgument(kind=POSITIONAL_ONLY,annotation=evaluate_expression(value))

Backward-Compatible API

To get backward compatibility with the existingtypes.Callable API,which relies on fields__args__ and__parameters__, we can definethem as if they were written in terms of the following:

importitertoolsimporttypingdefget_args(t:CallableType)->tuple[object]:return_type_arg=(typing.Awaitable[t.return_type]ift.is_asyncelset.return_type)arguments=t.argumentsifisinstance(arguments,Ellipsis):argument_args=(Ellipsis,)else:argument_args=(arg.annotationforarginarguments)return(*arguments_args,return_type_arg)defget_parameters(t:CallableType)->tuple[object]:out=[]forarginget_args(t):ifisinstance(arg,typing.ParamSpec):out.append(t)else:out.extend(arg.__parameters__)returntuple(out)

Additional Behaviors oftypes.CallableType

As with theA|B syntax for unions introduced inPEP 604:

• The__eq__ method should treat equivalenttyping.Callablevalues as equal to values constructed using the builtin syntax, andotherwise should behave like the__eq__ oftyping.Callable.
• The__repr__ method should produce an arrow syntax representation that,when evaluated, gives us back an equaltypes.CallableType instance.

Functions-as-Types

An idea we looked at very early on was toallow using functions as types.The idea is allowing a function to stand in for its own callsignature, with roughly the same semantics as the__call__ methodof callback protocols:

defCallableType(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 viablereplacement for callable types:

• It would be difficult to handleParamSpec, which we consider acritical feature to support.
• When using functions as types, the callable types are not first-classvalues. Instead, they require a separate, out-of-line functiondefinition to define a type alias
• It would not support more features than callback protocols, and seemsmore like a shorter way to write them than a replacement forCallable.

Hybrid keyword-arrow Syntax

In the Rust language, a keywordfn is used to indicate functionsin much the same way as Python’sdef, and callable types areindicated using a hybrid arrow syntaxFn(i64,String)->bool.

We could use thedef keyword in callable types for Python, forexample our two-parameter boolean function could be written asdef(int,str)->bool. But we think this might confuse readersinto thinkingdef(A,B)->C is a lambda, particularly becauseJavascript’sfunction keyword is used in both named and anonymousfunctions.

Parenthesis-Free Syntax

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

int,str->bool

We decided against it because this is not visually as similar toexisting function header syntax. Moreover, it is visually similar tolambdas, which bind names with no parentheses:lambdax,y:x==y.

Requiring Outer Parentheses

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

defmake_adder()->(int)->int:returnlambdax:x+1

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

defmake_adder()->(int->int):returnlambdax:x+1

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

• Currently in Python commas bind very loosely, which means it might be commonto 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 wasfamiliar syntax inspired by function headers.
• This syntax may be more readable for deaply nested callables like the oneabove, but deep nesting is not very common. Encouraging extra parenthesesaround callable types in return position via a style guide would have most ofthe readability benefit without the downsides.

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

defmake_adder()->((int)->int):returnlambdax:x+1

We rejected this change because:

• The outer parentheses only help readability in some cases, mostly when acallable type is used in return position. In many other cases they hurtreadability rather than helping.
• We agree that it might make sense to encourage outer parentheses in severalcases, 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 throwsyntax errors.
  • Moreover, if a type is complicated enough that readability is a concernwe can always use type aliases, for example:

    IntToIntFunction:(int)->intdefmake_adder()->IntToIntFunction:returnlambdax:x+1

Making-> bind tighter than|

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

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

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

• It means we no would longer have to treatNone|(int,str)->bool as a syntax error.
• Looking at typeshed today, optional callable arguments are very commonbecause usingNone 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 headerdeff()->int|None:... is legaland indicates a function returning an optional int. To be consistentwith 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| bindtighter. While we do not have to follow their lead, we prefer to doso.
• We do acknowledge that optional callable types are common andhaving| bind tighter forces extra parentheses, which makes thesetypes harder to write. But code is read more often than written, andwe believe that requiring the outer parentheses for an optional callabletype like((int,str)->bool)|None is preferable for readability.

Introducing type-strings

Another idea was adding a new “special string” syntax and putting the typeinside of it, for examplet”(int,str)->bool”. We rejected thisbecause it is not as readable, and seems out of step withguidancefrom the Steering Council on ensuring that type expressions do notdiverge 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 couldlook at how to make the existing type easier to read. One proposalwould be to make the builtincallable function indexable sothat it could be used as a type:

callable[[int,str],bool]

This change would be analogous toPEP 585 that made built in collectionslikelist anddict usable as types, and would make importsmore convenient, but it wouldn’t help readability of the types themselvesmuch.

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

callable[(int,str),bool]

This actually is a significant readability improvement formulti-argument functions, but the problem is that it makes callableswith one arguments, which are the most common arity, hard towrite: because(x) evaluates tox, they would have to bewritten likecallable[(int,),bool]. We find this awkward.

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

Alternative APIs

We considered having the runtime datatypes.CallableType use amore structured API where there would be separate fields forposonlyargs andparam_spec. The current proposal waswas inspired by theinspect.Signature type.

We use “argument” in our field and type names, unlike “parameter”as ininspect.Signature, in order to avoid confusion withthecallable_type.__parameters__ field from the legacy APIthat 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 compatibilityof__args__ for async callable types likeasync(int)->str. Thereason is that one could argue they are not expressible directlyusingtyping.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 appearanceof a backward-compatible API while actually breaking its semantics onasync types, we would cause runtime type libraries that attempt tointerpretCallable using__args__ to fail silently.

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