diff --git a/pep-0677.rst b/pep-0677.rst index 22fc34085f7..d1149e29211 100644 --- a/pep-0677.rst +++ b/pep-0677.rst @@ -18,7 +18,7 @@ This PEP introduces a concise and friendly syntax for callable types, supporting the same functionality as ``typing.Callable`` but with an arrow syntax inspired by the syntax for typed function signatures. This allows types like ``Callable[[int, str], bool]`` to -be written ``(int, str) -> bool``. +be written as ``(int, str) -> bool``. The proposed syntax supports all the functionality provided by ``typing.Callable`` and ``typing.Concatenate``, and is intended to @@ -78,7 +78,7 @@ There are a few usability challenges with ``Callable`` we can see here: - The bracket structure is not visually similar to how function signatures are written. - It requires an explicit import, unlike many of the other most common - types like ``list``. + types like ``list`` and ``dict``. Possibly as a result, `programmers often fail to write complete Callable types @@ -102,8 +102,8 @@ the benefits of static typing. For example, they might write this:: flat_map(add, [1, 2, 3]) # oops, no type check error! There's some partial type information here - we at least know that ``func`` -needs to be callable. But we've dropped too much type information to catch -the mistake. +needs to be callable. But we've dropped too much type information for +type checkers to find the bug. With our proposal, the example looks like this:: @@ -142,7 +142,7 @@ types, is more complicated to read and write, and still requires an import and bracket-based syntax. In this proposal, we chose to support all the existing semantics of -``typing.Callable``, without adding support for new features. We took +``typing.Callable``, without adding support for new features. We made this decision after examining how frequently each feature might be used in existing typed and untyped open-source code. We determined that the vast majority of use cases are covered. @@ -296,8 +296,8 @@ 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. +As in TypeScript, the argument names (if provided) are just there for +documentation and are not part of the type itself. Scala ~~~~~ @@ -315,11 +315,11 @@ Function types can optionally include names, for example:: 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 described in our +This is similar to the extended syntax proposal we describe in our `Rejected Alternatives`_ section. -Function Definition vs Callable Type Annotations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 @@ -542,7 +542,7 @@ Trailing Commas ~~~~~~~~~~~~~~~ - Following the precedent of function signatures, putting a comma in - an empty arguments list is illegal, ``(,) -> bool`` is a syntax + an empty arguments list is illegal: ``(,) -> bool`` is a syntax error. - Again following precedent, trailing commas are otherwise always permitted:: @@ -710,7 +710,7 @@ We decided against proposing it for the following reasons: demonstrate that fewer than 3% of use cases would benefit from any of the added features. - The group that debated these proposals was split down the middle - about whether these changes are even desirable: + about whether these changes are desirable: - On the one hand, they make callable types more expressive. On the other hand, they could easily confuse users who have not read the @@ -723,8 +723,8 @@ We decided against proposing it for the following reasons: - We intend to implement the current proposal in a way that is forward-compatible with the more complicated extended syntax. If the community decides after more experience and discussion that we want - the additional features, they should be straightforward to propose - in the future. + the additional features, it should be straightforward to propose + them in the future. - Even a full extended syntax cannot replace the use of callback protocols for overloads. For example, no closed form of callable type could express a function that maps bools to bools and ints to floats, @@ -752,7 +752,8 @@ We decided against proposing it for the following reasons: We confirmed that the current proposal is forward-compatible with extended syntax by `implementing `_ -a quick-and-dirty grammar and AST on top of this grammar and AST for. +a grammar and AST for this extended syntax on top of our reference +implementation of this PEP's grammar. Syntax Closer to Function Signatures @@ -778,11 +779,10 @@ The benefits of this proposal would have included: Key downsides that led us to reject the idea include the following: -- A large majority of use cases only use positional-only arguments, - and this syntax would be more verbose for that use case, both - because of requiring argument names and an explicit ``/``, for - example ``(int, /) -> bool`` where our proposal allows ``(int) -> - bool`` +- A large majority of use cases only use positional-only arguments. This + syntax would be more verbose for that use case, both because of requiring + argument names and an explicit ``/``, for example ``(int, /) -> bool`` where + our proposal allows ``(int) -> bool`` - The requirement for explicit ``/`` for positional-only arguments has a high risk of causing frequent bugs - which often would not be detected by unit tests - where library authors would accidentally @@ -982,8 +982,7 @@ 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]``. This is awkward enough that -we dislike this idea. +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 @@ -1078,8 +1077,8 @@ types. However, we have since begun to do so, e.g. with PEP 604. at the PyCon Typing Summit 2021. **Steven** `brought up this proposal on typing-sig -`. We -had several meetings to discuss alternatives, and `this presentation +`_. +We had several meetings to discuss alternatives, and `this presentation `_ led us to the current proposal.