Skip to content

Commit

Permalink
PEP 673: Inline reference links.
Browse files Browse the repository at this point in the history
This follows Guido's suggestion in python#2130.
  • Loading branch information
pradeep90 committed Nov 11, 2021
1 parent db8ebb6 commit 268c3b6
Showing 1 changed file with 27 additions and 77 deletions.
104 changes: 27 additions & 77 deletions pep-0673.rst
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@ Abstract

This PEP introduces a simple and intuitive way to annotate methods that return
an instance of their class. This behaves the same as the ``TypeVar``-based
approach specified in PEP 484 [#pep-484-self-type]_ but is more concise and
easier to follow.
approach specified in `PEP 484 <https://www.python.org/dev/peps/pep-0484>`_
but is more concise and easier to follow.

Motivation
==========
Expand Down Expand Up @@ -132,13 +132,15 @@ As in the above example, the type checker will correctly infer the type of
Usage statistics
----------------

We analyzed popular open-source projects [#self-type-usage-stats]_ and found
that patterns like the above were used about **40%** as often as popular types
like ``dict`` or ``Callable``. For example, in typeshed alone, such “Self”
types are used 523 times, compared to 1286 uses of ``dict`` and 1314 uses of
``Callable`` as of October 2021 [#callable-dict-usage-stats]_. This suggests
that a ``Self`` type will be used quite often and users will benefit a lot
from the simpler approach above.
We `analyzed
<https://github.com/pradeep90/annotation_collector/#self-type-stats>`_ popular
open-source projects and found that patterns like the above were used about
**40%** as often as popular types like ``dict`` or ``Callable``. For example,
in typeshed alone, such “Self” types are used 523 times, compared to 1286 uses
of ``dict`` and 1314 uses of ``Callable`` `as of October 2021
<https://github.com/pradeep90/annotation_collector/#overall-stats-in-typeshed>`_.
This suggests that a ``Self`` type will be used quite often and users will
benefit a lot from the simpler approach above.

Specification
=============
Expand Down Expand Up @@ -495,8 +497,9 @@ is treated equivalently to:
return self


See [#protocol-self-type]_ for details on the behavior of TypeVars bound
to protocols.
See `PEP 544
<https://www.python.org/dev/peps/pep-0544/#self-types-in-protocols>`_ for
details on the behavior of TypeVars bound to protocols.

Checking a class for compatibility with a protocol: If a protocol uses
``Self`` in methods or attribute annotations, then a class ``Foo`` is
Expand Down Expand Up @@ -753,85 +756,32 @@ Resources
=========

Similar discussions on a ``Self`` type in Python started in Mypy around 2016:
[#mypy1212]_. However, the approach ultimately taken there was the bounded
``TypeVar`` approach shown in our "before" examples. Other issues that discuss
this include [#mypy2354]_.
`Mypy issue #1212 <https://github.com/python/mypy/issues/1212>`_ - SelfType or
another way to spell "type of self". However, the approach ultimately taken
there was the bounded ``TypeVar`` approach shown in our "before" examples.
Other issues that discuss this include `Mypy issue #2354
<https://github.com/python/mypy/issues/2354>`_ - Self types in generic
classes.

**Pradeep** made a concrete proposal at the PyCon Typing Summit 2021:
[#type-variables-for-all]_ (slides [#type-variables-for-all-slides]_).
`recorded talk <https://youtu.be/ld9rwCvGdhc?t=3260>`_, `slides
<https://drive.google.com/file/d/1x-qoDVY_OvLpIV1EwT7m3vm4HrgubHPG/view>`_.

**James** brought up the proposal independently on typing-sig:
[#james-typing-sig]_.
`Typing-sig thread <https://mail.python.org/archives/list/typing-sig@python.org/thread/SJAANGA2CWZ6D6TJ7KOPG7PZQC56K73S/#B2CBLQDHXQ5HMFUMS4VNY2D4YDCFT64Q>`_.

Other languages have similar ways to express the type of the enclosing class:

+ TypeScript has the ``this`` type [#typescript-this-type]_
+ Rust has the ``Self`` type [#rust-self-type]_
+ TypeScript has the ``this`` type (`TypeScript docs
<https://typescriptlang.org/docs/handbook/2/classes.html#this-types>`_)
+ Rust has the ``Self`` type (`Rust docs
<https://doc.rust-lang.org/std/keyword.SelfTy.html>`_)

Thanks to the following people for their feedback on the PEP:

Jia Chen, Rebecca Chen, Sergei Lebedev, Kaylynn Morgan, Tuomas Suutari, Alex
Waygood, Shannon Zhu, and Никита Соболев

References
==========

.. [#pep-484-self-type] PEP 484's approach to annotating ``self`` and ``cls``.
https://www.python.org/dev/peps/pep-0484/#annotating-instance-and-class-methods
.. [#mypy1212] SelfType or another way to spell "type of self"
https://github.com/python/mypy/issues/1212
.. [#mypy2354] Self types in generic classes
https://github.com/python/mypy/issues/2354
.. [#type-variables-for-all] Type Variables for All talk
https://youtu.be/ld9rwCvGdhc?t=3260
.. [#type-variables-for-all-slides] Slides
https://drive.google.com/file/d/1x-qoDVY_OvLpIV1EwT7m3vm4HrgubHPG/view
.. [#james-typing-sig] Thread
https://mail.python.org/archives/list/typing-sig@python.org/thread/SJAANGA2CWZ6D6TJ7KOPG7PZQC56K73S/#B2CBLQDHXQ5HMFUMS4VNY2D4YDCFT64Q
.. [#property-workaround] Property workaround
https://mypy-play.net/?mypy=latest&python=3.8&gist=ae886111451833e38737721a4153fd96
.. [#self-type-usage-stats] Self type usage stats
https://github.com/pradeep90/annotation_collector/#self-type-stats
.. [#callable-dict-usage-stats] ``Callable`` and ``dict`` usage stats
https://github.com/pradeep90/annotation_collector/#overall-stats-in-typeshed
.. [#protocol-self-type] Protocol-bound ``TypeVar``
https://www.python.org/dev/peps/pep-0544/#self-types-in-protocols
.. [#rust-self-type] Rust ``Self`` type
https://doc.rust-lang.org/std/keyword.SelfTy.html
.. [#typescript-this-type] TypeScript ``this`` type
https://typescriptlang.org/docs/handbook/2/classes.html#this-types
.. [#mypy-implementation] Mypy implementation
https://github.com/Gobot1234/mypy
.. [#self-implementation] ``Self`` implementation
https://github.com/Gobot1234/typing/commit/8b41f2478144fcc32bac7a65afc3e490c24bb068
Copyright
=========

Expand Down

0 comments on commit 268c3b6

Please sign in to comment.