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

PEP 593: Fix citation references #2640

Merged
merged 2 commits into from
Jun 18, 2022
Merged

PEP 593: Fix citation references #2640

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
09682a4
PEP 593: Remove orphan citation to fix build warning
hugovk Jun 9, 2022
d6bb011
PEP 593: Inline the references to fix warnings
hugovk Jun 9, 2022
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
49 changes: 22 additions & 27 deletions pep-0593.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,13 +43,14 @@ should ignore it and simply treat the type as ``T``. Unlike the
``no_type_check`` functionality that currently exists in the ``typing``
module which completely disables typechecking annotations on a function
or a class, the ``Annotated`` type allows for both static typechecking
of ``T`` (e.g., via mypy [mypy]_ or Pyre [pyre]_, which can safely ignore ``x``)
of ``T`` (e.g., via `mypy <mypy_>`_ or `Pyre <pyre_>`_,
which can safely ignore ``x``)
together with runtime access to ``x`` within a specific application. The
introduction of this type would address a diverse set of use cases of interest
to the broader Python community.

This was originally brought up as issue 600 [issue-600]_ in the typing github
and then discussed in Python ideas [python-ideas]_.
This was originally brought up as `issue 600 <issue-600_>`_ in the typing github
and then discussed in `Python ideas <python-ideas_>`_.

Motivating examples
-------------------
Expand Down Expand Up @@ -81,21 +82,21 @@ Lowering barriers to developing new typing constructs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Typically when adding a new type, a developer need to upstream that type to the
typing module and change mypy, PyCharm [pycharm]_, Pyre, pytype [pytype]_,
typing module and change mypy, `PyCharm <pycharm_>`_, Pyre, `pytype <pytype_>`_,
etc...
This is particularly important when working on open-source code that
makes use of these types, seeing as the code would not be immediately
transportable to other developers' tools without additional logic. As a result,
there is a high cost to developing and trying out new types in a codebase.
Ideally, authors should be able to introduce new types in a manner that allows
for graceful degradation (e.g.: when clients do not have a custom mypy plugin
[mypy-plugin]_), which would lower the barrier to development and ensure some
for graceful degradation (e.g.: when clients do not have a custom `mypy plugin
<mypy-plugin_>`_), which would lower the barrier to development and ensure some
degree of backward compatibility.

For example, suppose that an author wanted to add support for tagged unions
[tagged-union]_ to Python. One way to accomplish would be to annotate
``TypedDict`` [typed-dict]_ in Python such that only one field is allowed to be
set::
For example, suppose that an author wanted to add support for `tagged unions
<tagged-union_>`_ to Python. One way to accomplish would be to `annotate
<typed-dict_>`_ ``TypedDict`` in Python such that only one field is allowed
to be set::

Currency = Annotated[
TypedDict('Currency', {'dollars': float, 'pounds': float}, total=False),
Expand Down Expand Up @@ -236,7 +237,7 @@ cause ``Annotated`` to not integrate cleanly with the other typing annotations:
* ``Annotated`` cannot infer the decorated type. You could imagine that
``Annotated[..., Immutable]`` could be used to mark a value as immutable
while still inferring its type. Typing does not support using the
inferred type anywhere else [issue-276]_; it's best to not add this as a
inferred type `anywhere else <issue-276_>`_; it's best to not add this as a
special case.

* Using ``(Type, Ann1, Ann2, ...)`` instead of
Expand All @@ -253,40 +254,34 @@ This feature was left out to keep the design simple:
little benefit.


References
----------

.. [issue-600]
.. _issue-600:
https://github.com/python/typing/issues/600

.. [python-ideas]
.. _python-ideas:
https://mail.python.org/pipermail/python-ideas/2019-January/054908.html

.. [struct-doc]
https://docs.python.org/3/library/struct.html#examples

.. [mypy]
.. _mypy:
http://www.mypy-lang.org/

.. [pyre]
.. _pyre:
https://pyre-check.org/

.. [pycharm]
.. _pycharm:
https://www.jetbrains.com/pycharm/

.. [pytype]
.. _pytype:
https://github.com/google/pytype

.. [mypy-plugin]
.. _mypy-plugin:
https://github.com/python/mypy_extensions

.. [tagged-union]
.. _tagged-union:
https://en.wikipedia.org/wiki/Tagged_union

.. [typed-dict]
.. _typed-dict:
https://mypy.readthedocs.io/en/latest/more_types.html#typeddict

.. [issue-276]
.. _issue-276:
https://github.com/python/typing/issues/276

Copyright
Expand Down