Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

PEP 677: Minor wording and formatting fixes. #2225

Merged
merged 1 commit into from
Jan 11, 2022
Merged

PEP 677: Minor wording and formatting fixes. #2225

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 23 additions & 24 deletions pep-0677.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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::

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
~~~~~
Expand All @@ -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
Expand Down Expand Up @@ -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::
Expand Down Expand Up @@ -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
Expand All @@ -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,
Expand Down Expand Up @@ -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 <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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
<https://mail.python.org/archives/list/[email protected]/thread/3JNXLYH5VFPBNIVKT6FFBVVFCZO4GFR2>`. We
had several meetings to discuss alternatives, and `this presentation
<https://mail.python.org/archives/list/[email protected]/thread/3JNXLYH5VFPBNIVKT6FFBVVFCZO4GFR2>`_.
We had several meetings to discuss alternatives, and `this presentation
<https://www.dropbox.com/s/sshgtr4p30cs0vc/Python%20Callable%20Syntax%20Proposals.pdf?dl=0>`_
led us to the current proposal.

Expand Down