Skip to content

bpo-42737: Mention PEP 563 in doc for annotated assignment #25511

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

Closed
gousaiyang wants to merge 3 commits into from
Closed

bpo-42737: Mention PEP 563 in doc for annotated assignment #25511

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ebaeecf
bpo-42737: Mention PEP 563 in doc for annotated assignment
gousaiyang Apr 21, 2021
03e7098
Be more explicit about pre-3.10 complex target annotation evaluation …
gousaiyang Apr 25, 2021
f339c01
Merge branch 'main' into doc-var-anno-pep-563
JelleZijlstra Apr 2, 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
19 changes: 14 additions & 5 deletions Doc/reference/simple_stmts.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -335,15 +335,20 @@ statement, of a variable or attribute annotation and an optional assignment stat
The difference from normal :ref:`assignment` is that only single target is allowed.

For simple names as assignment targets, if in class or module scope,
the annotations are evaluated and stored in a special class or module
the annotations are available in a special class or module
attribute :attr:`__annotations__`
that is a dictionary mapping from variable names (mangled if private) to
evaluated annotations. This attribute is writable and is automatically
that is a dictionary mapping from variable names (mangled if private) to the

@JelleZijlstra JelleZijlstra Apr 2, 2022

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Suggested change
that is a dictionary mapping from variable names (mangled if private) to the
that is a dictionary mapping from variable names (mangled if private) to

Reads better without the article

annotations. This attribute is writable and is automatically
created at the start of class or module body execution, if annotations
are found statically.
are found statically. If the ``annotations`` import from :mod:`__future__` is used
(i.e. :pep:`563` is enabled), the annotations are stored as string values in

@JelleZijlstra JelleZijlstra Apr 2, 2022

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Ideally we should link to the documentation for the __future__ statement, not to the PEP directly. A PEP is a change proposal, not live documentation.

:attr:`__annotations__` at runtime which enables postponed evaluation. Otherwise,
they are eagerly evaluated at runtime in the corresponding scope and then stored into
:attr:`__annotations__`.

For expressions as assignment targets, the annotations are evaluated if
in class or module scope, but not stored.
in class or module scope (regardless of whether :pep:`563` is enabled), but not

@JelleZijlstra JelleZijlstra Apr 2, 2022

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Really? That seems like a bug.

stored.

If a name is annotated in a function scope, then this name is local for
that scope. Annotations are never evaluated and stored in function scopes.
Expand All @@ -366,6 +371,10 @@ target, then the interpreter evaluates the target except for the last
syntax for type annotations that can be used in static analysis tools and
IDEs.

:pep:`563` - Postponed Evaluation of Annotations
Support for forward references within annotations by preserving
annotations in a string form at runtime instead of eager evaluation.

.. versionchanged:: 3.8
Now annotated assignments allow same expressions in the right hand side as
the regular assignments. Previously, some expressions (like un-parenthesized
Expand Down