PEP 677: Minor wording and formatting fixes. (#2225)

We're getting ready for a final request for comments to python-dev,
so I did one more pass through the PEP to catch remaining readability
issues (I was especially looking for things easier to see on the actual
PEP page with formatting than the rst doc):
- found an incorrectly formatted hyperlink
- changed some sentences with ambiguous pronouns
- broke up a couple of sentences that seemed too long
- tweaked a few places where the wording was okay but nonstandard
This commit is contained in:
Steven Troxler 2022-01-11 10:18:50 -08:00 committed by GitHub
parent 4a0c9779de
commit 218e2ccaec
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 23 additions and 24 deletions

View File

@ -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 supporting the same functionality as ``typing.Callable`` but with an
arrow syntax inspired by the syntax for typed function arrow syntax inspired by the syntax for typed function
signatures. This allows types like ``Callable[[int, str], bool]`` to 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 The proposed syntax supports all the functionality provided by
``typing.Callable`` and ``typing.Concatenate``, and is intended to ``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 - The bracket structure is not visually similar to how function signatures
are written. are written.
- It requires an explicit import, unlike many of the other most common - 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 Possibly as a result, `programmers often fail to write complete
Callable types 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! flat_map(add, [1, 2, 3]) # oops, no type check error!
There's some partial type information here - we at least know that ``func`` 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 needs to be callable. But we've dropped too much type information for
the mistake. type checkers to find the bug.
With our proposal, the example looks like this:: 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. import and bracket-based syntax.
In this proposal, we chose to support all the existing semantics of 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 this decision after examining how frequently each feature might be
used in existing typed and untyped open-source code. We determined used in existing typed and untyped open-source code. We determined
that the vast majority of use cases are covered. 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 (x: Int, y: String) -> Bool
As in TypeScript, the argument names if provided are just there for documentation As in TypeScript, the argument names (if provided) are just there for
and are not part of the type itself. documentation and are not part of the type itself.
Scala 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 Unlike in TypeScript and Kotlin, these names are part of the type if
provided - any function implementing the type must use the same names. 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. `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 In all of the languages listed above, type annotations for function
definitions use a ``:`` rather than a ``->``. For example, in TypeScript 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 - 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. error.
- Again following precedent, trailing commas are otherwise always - Again following precedent, trailing commas are otherwise always
permitted:: 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 demonstrate that fewer than 3% of use cases would benefit from any
of the added features. of the added features.
- The group that debated these proposals was split down the middle - 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 - On the one hand, they make callable types more expressive. On the
other hand, they could easily confuse users who have not read 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 - We intend to implement the current proposal in a way that is
forward-compatible with the more complicated extended syntax. If the forward-compatible with the more complicated extended syntax. If the
community decides after more experience and discussion that we want community decides after more experience and discussion that we want
the additional features, they should be straightforward to propose the additional features, it should be straightforward to propose
in the future. them in the future.
- Even a full extended syntax cannot replace the use of callback - Even a full extended syntax cannot replace the use of callback
protocols for overloads. For example, no closed form of callable type protocols for overloads. For example, no closed form of callable type
could express a function that maps bools to bools and ints to floats, 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 We confirmed that the current proposal is forward-compatible with
extended syntax by extended syntax by
`implementing <https://github.com/stroxler/cpython/tree/callable-type-syntax--extended>`_ `implementing <https://github.com/stroxler/cpython/tree/callable-type-syntax--extended>`_
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 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: Key downsides that led us to reject the idea include the following:
- A large majority of use cases only use positional-only arguments, - A large majority of use cases only use positional-only arguments. This
and this syntax would be more verbose for that use case, both syntax would be more verbose for that use case, both because of requiring
because of requiring argument names and an explicit ``/``, for argument names and an explicit ``/``, for example ``(int, /) -> bool`` where
example ``(int, /) -> bool`` where our proposal allows ``(int) -> our proposal allows ``(int) -> bool``
bool``
- The requirement for explicit ``/`` for positional-only arguments has - The requirement for explicit ``/`` for positional-only arguments has
a high risk of causing frequent bugs - which often would not be a high risk of causing frequent bugs - which often would not be
detected by unit tests - where library authors would accidentally 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 multi-argument functions, but the problem is that it makes callables
with one arguments, which are the most common arity, hard to with one arguments, which are the most common arity, hard to
write: because ``(x)`` evaluates to ``x``, they would have to be write: because ``(x)`` evaluates to ``x``, they would have to be
written like ``callable[(int,), bool]``. This is awkward enough that written like ``callable[(int,), bool]``. We find this awkward.
we dislike this idea.
Moreover, none of these ideas help as much with reducing verbosity 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 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. at the PyCon Typing Summit 2021.
**Steven** `brought up this proposal on typing-sig **Steven** `brought up this proposal on typing-sig
<https://mail.python.org/archives/list/typing-sig@python.org/thread/3JNXLYH5VFPBNIVKT6FFBVVFCZO4GFR2>`. We <https://mail.python.org/archives/list/typing-sig@python.org/thread/3JNXLYH5VFPBNIVKT6FFBVVFCZO4GFR2>`_.
had several meetings to discuss alternatives, and `this presentation We had several meetings to discuss alternatives, and `this presentation
<https://www.dropbox.com/s/sshgtr4p30cs0vc/Python%20Callable%20Syntax%20Proposals.pdf?dl=0>`_ <https://www.dropbox.com/s/sshgtr4p30cs0vc/Python%20Callable%20Syntax%20Proposals.pdf?dl=0>`_
led us to the current proposal. led us to the current proposal.