8000 Further improve docs for `typing.Annotated` by AlexWaygood · Pull Request #105498 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

Further improve docs for typing.Annotated #105498

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

Merged
merged 2 commits into from
Jun 8, 2023
Merged

Further improve docs for typing.Annotated #105498

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7ee882a
Overhaul docs for `typing.Annotated`
AlexWaygood Jun 8, 2023
2cd15fe
Shimmy to the left
AlexWaygood Jun 8, 2023
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
Prev Previous commit
Shimmy to the left
  • Loading branch information
@AlexWaygood
AlexWaygood committed Jun 8, 2023
commit 2cd15fec0a188964b8a591eb906a81dbdd9ce32b
44 changes: 22 additions & 22 deletions Doc/library/typing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1300,30 +1300,30 @@ These can be used as types in annotations using ``[]``, each having a unique syn
where ``T1``, ``T2``, etc. are :class:`TypeVars <TypeVar>`. This would be
invalid: only one type should be passed to Annotated.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks misindented, as it's indented by one space less than the next paragraph.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, it seems the bulleted list is inconsistent about whether there should be one or two spaces after a bullet point.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I decided it was probably the next paragraph that had the wrong indentation -- does it look better after 2cd15fe?


* By default, :func:`get_type_hints` strips the metadata from annotations.
Pass ``include_extras=True`` to have the metadata preserved:
* By default, :func:`get_type_hints` strips the metadata from annotations.
Pass ``include_extras=True`` to have the metadata preserved:

.. doctest::

>>> from typing import Annotated, get_type_hints
>>> def func(x: Annotated[int, "metadata"]) -> None: pass
...
>>> get_type_hints(func)
{'x': <class 'int'>, 'return': <class 'NoneType'>}
>>> get_type_hints(func, include_extras=True)
{'x': typing.Annotated[int, 'metadata'], 'return': <class 'NoneType'>}

* At runtime, the metadata associated with an ``Annotated`` type can be
retrieved via the :attr:`!__metadata__` attribute:
.. doctest::

.. doctest::

>>> from typing import Annotated
>>> X = Annotated[int, "very", "important", "metadata"]
>>> X
typing.Annotated[int, 'very', 'important', 'metadata']
>>> X.__metadata__
('very', 'important', 'metadata')
>>> from typing import Annotated, get_type_hints
>>> def func(x: Annotated[int, "metadata"]) -> None: pass
...
>>> get_type_hints(func)
{'x': <class 'int'>, 'return': <class 'NoneType'>}
>>> get_type_hints(func, include_extras=True)
{'x': typing.Annotated[int, 'metadata'], 'return': <class 'NoneType'>}

* At runtime, the metadata associated with an ``Annotated`` type can be
retrieved via the :attr:`!__metadata__` attribute:

.. doctest::

>>> from typing import Annotated
>>> X = Annotated[int, "very", "important", "metadata"]
>>> X
typing.Annotated[int, 'very', 'important', 'metadata']
>>> X.__metadata__
('very', 'important', 'metadata')

.. seealso::

Expand Down
0