From aea1fd51ef5d0570207fe1a41d40c5c98649436c Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Wed, 19 Apr 2023 14:33:23 -0600 Subject: [PATCH] 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 --- pep-0649.rst | 44 +++++++++++++++++--------------------------- 1 file changed, 17 insertions(+), 27 deletions(-) diff --git a/pep-0649.rst b/pep-0649.rst index d6f179922..a45ebe734 100644 --- a/pep-0649.rst +++ b/pep-0649.rst @@ -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. :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 would look something like this: @@ -238,7 +238,7 @@ value, for example type information. All the annotations for a function were stored together in a new attribute ``__annotations__``, in an "annotation dict" 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 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 approach for expressing static type information, called *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, 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 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 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 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. 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 marked as fixed. - https://github.com/python/cpython/issues/89687 - https://github.com/python/cpython/issues/85421 - https://github.com/python/cpython/issues/90531 +* https://github.com/python/cpython/issues/89687 +* https://github.com/python/cpython/issues/85421 +* https://github.com/python/cpython/issues/90531 Even with proper globals *and* locals, ``eval`` can be unreliable 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 Language Reference: - __annotate__(format: int) -> dict + ``__annotate__(format: int) -> dict`` Returns a new dictionary object mapping attribute/parameter 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__`` is ``None``, the ``fn.__annotations__`` data descriptor 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 when evaluating annotations defined inside a class namespace. 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. It can be set to either ``None`` or a dictionary. If it's set to 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 ``__annotations__`` attribute is unchanged. 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 preserved. * 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 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 active, even if this PEP is accepted. So, under normal circumstances, requesting ``inspect.SOURCE`` format from a @@ -1430,11 +1430,11 @@ that became some of the best aspects of this proposal: 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 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: