PEP 649: fix and improve formatting

* PEP 649: fix backticks

* PEP 649: fix typos

* PEP 649: update formatting

* PEP 649: update formatting

* PEP 649: remove redundant emacs metadata

* PEP 649: use more roles
This commit is contained in:
Hugo van Kemenade 2023-04-19 14:33:23 -06:00 committed by GitHub
parent 30e586693c
commit aea1fd51ef
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 17 additions and 27 deletions

View File

@ -162,7 +162,7 @@ But this code doesn't run—it throws a ``NameError`` on the first
line, because ``MyType`` hasn't been defined yet. line, because ``MyType`` hasn't been defined yet.
:pep:`563`'s solution is to decompile the expressions back :pep:`563`'s solution is to decompile the expressions back
into strings during compliation and store those strings as the into strings during compilation and store those strings as the
values in the annotations dict. The equivalent runtime code values in the annotations dict. The equivalent runtime code
would look something like this: would look something like this:
@ -238,7 +238,7 @@ value, for example type information.
All the annotations for a function were stored together in All the annotations for a function were stored together in
a new attribute ``__annotations__``, in an "annotation dict" a new attribute ``__annotations__``, in an "annotation dict"
that mapped parameter names (or, in the case of the return that mapped parameter names (or, in the case of the return
annotaion, using the name ``'return'``) to their Python value. annotation, using the name ``'return'``) to their Python value.
In an effort to foster experimentation, Python In an effort to foster experimentation, Python
intentionally didn't define what form this metadata should take, intentionally didn't define what form this metadata should take,
@ -249,7 +249,7 @@ make use of this functionality were slow to emerge.
After years of little progress, the BDFL chose a particular After years of little progress, the BDFL chose a particular
approach for expressing static type information, called approach for expressing static type information, called
*type hints,* as defined in :pep:`484`. Python 3.5 shipped *type hints,* as defined in :pep:`484`. Python 3.5 shipped
with a new `typing` module which quickly became very popular. with a new :mod:`typing` module which quickly became very popular.
Python 3.6 added syntax to annotate local variables, Python 3.6 added syntax to annotate local variables,
class attributes, and module attributes, using the approach class attributes, and module attributes, using the approach
@ -282,9 +282,9 @@ more CPU time to create and bind.
To solve these problems, the BDFL accepted :pep:`563`, which To solve these problems, the BDFL accepted :pep:`563`, which
added a new feature to Python 3.7: "stringized annotations". added a new feature to Python 3.7: "stringized annotations".
It was activated with a future import: It was activated with a future import::
from __future__ import annotations from __future__ import annotations
Normally, annotation expressions were evaluated at the time Normally, annotation expressions were evaluated at the time
the object was bound, with their values being stored in the the object was bound, with their values being stored in the
@ -370,7 +370,7 @@ Wrappers
Wrappers are functions or classes that wrap user functions or Wrappers are functions or classes that wrap user functions or
classes and add functionality. Examples of this would be classes and add functionality. Examples of this would be
``dataclass``, ``functools.partial``, ``attrs``, and ``wrapt``. :func:`dataclass`, :func:`functools.partial`, ``attrs``, and ``wrapt``.
Wrappers are a distinct subcategory of runtime annotation users. Wrappers are a distinct subcategory of runtime annotation users.
Although they do use annotations at runtime, they may or may not Although they do use annotations at runtime, they may or may not
@ -451,9 +451,9 @@ resolvable yet. This has proved to be difficult to reconcile;
of the three bug reports linked to below, only one has been of the three bug reports linked to below, only one has been
marked as fixed. marked as fixed.
https://github.com/python/cpython/issues/89687 * https://github.com/python/cpython/issues/89687
https://github.com/python/cpython/issues/85421 * https://github.com/python/cpython/issues/85421
https://github.com/python/cpython/issues/90531 * https://github.com/python/cpython/issues/90531
Even with proper globals *and* locals, ``eval`` can be unreliable Even with proper globals *and* locals, ``eval`` can be unreliable
on stringized annotations. on stringized annotations.
@ -562,7 +562,7 @@ Here's a formal definition of ``__annotate__``, as it will
appear in the "Magic methods" section of the Python appear in the "Magic methods" section of the Python
Language Reference: Language Reference:
__annotate__(format: int) -> dict ``__annotate__(format: int) -> dict``
Returns a new dictionary object mapping attribute/parameter Returns a new dictionary object mapping attribute/parameter
names to their annotation values. names to their annotation values.
@ -676,7 +676,7 @@ an object of any of these three types:
doesn't have a cached annotations value, and ``fn.__annotate__`` doesn't have a cached annotations value, and ``fn.__annotate__``
is ``None``, the ``fn.__annotations__`` data descriptor is ``None``, the ``fn.__annotations__`` data descriptor
creates, caches, and returns a new empty dict. (This is for creates, caches, and returns a new empty dict. (This is for
backwards compatibility with :pep:``3107`` semantics.) backwards compatibility with :pep:`3107` semantics.)
@ -1017,7 +1017,7 @@ via the ``__globals__`` attribute. Traditionally the
This PEP needs to set the "locals" dictionary to the class dict This PEP needs to set the "locals" dictionary to the class dict
when evaluating annotations defined inside a class namespace. when evaluating annotations defined inside a class namespace.
So this PEP defines a new ``__locals__`` attribute on So this PEP defines a new ``__locals__`` attribute on
functions. By default it is uninitalized, or rather is set functions. By default it is uninitialized, or rather is set
to an internal value that indicates it hasn't been explicitly set. to an internal value that indicates it hasn't been explicitly set.
It can be set to either ``None`` or a dictionary. If it's set to It can be set to either ``None`` or a dictionary. If it's set to
a dictionary, the interpreter will use that dictionary as a dictionary, the interpreter will use that dictionary as
@ -1145,7 +1145,7 @@ annotations from stock semantics:
* The format of the annotations dict stored in * The format of the annotations dict stored in
the ``__annotations__`` attribute is unchanged. the ``__annotations__`` attribute is unchanged.
Annotations dicts contain real values, not strings Annotations dicts contain real values, not strings
as per :pep:``563``. as per :pep:`563`.
* Annotations dicts are mutable, and any changes to them are * Annotations dicts are mutable, and any changes to them are
preserved. preserved.
* The ``__annotations__`` attribute can be explicitly set, * The ``__annotations__`` attribute can be explicitly set,
@ -1347,7 +1347,7 @@ adopters of :pep:`563`, who now depend on its semantics,
``inspect.get_annotations`` and ``typing.get_type_hints`` will ``inspect.get_annotations`` and ``typing.get_type_hints`` will
implement a special affordance. implement a special affordance.
The Python compiler won't generate annotation code bjects The Python compiler won't generate annotation code objects
for objects defined in a module where :pep:`563` semantics are for objects defined in a module where :pep:`563` semantics are
active, even if this PEP is accepted. So, under normal active, even if this PEP is accepted. So, under normal
circumstances, requesting ``inspect.SOURCE`` format from a circumstances, requesting ``inspect.SOURCE`` format from a
@ -1430,11 +1430,11 @@ that became some of the best aspects of this proposal:
References References
********** **********
https://github.com/larryhastings/co_annotations/issues * https://github.com/larryhastings/co_annotations/issues
https://discuss.python.org/t/two-polls-on-how-to-revise-pep-649/23628 * https://discuss.python.org/t/two-polls-on-how-to-revise-pep-649/23628
https://discuss.python.org/t/a-massive-pep-649-update-with-some-major-course-corrections/25672 * https://discuss.python.org/t/a-massive-pep-649-update-with-some-major-course-corrections/25672
@ -1444,13 +1444,3 @@ Copyright
This document is placed in the public domain or under the This document is placed in the public domain or under the
CC0-1.0-Universal license, whichever is more permissive. CC0-1.0-Universal license, whichever is more permissive.
..
Local Variables:
mode: indented-text
indent-tabs-mode: nil
sentence-end-double-space: t
fill-column: 70
coding: utf-8
End: