gh-119180: Documentation for PEP 649 and 749 by JelleZijlstra · Pull Request #122235 · python/cpython · GitHub

Issue: Implement PEP 649 and PEP 749 #119180

📚 Documentation preview 📚: https://cpython-previews--122235.org.readthedocs.build/

Haven't look at everything nor had I marked every typo but here's a first round of comments.

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

Looks good, left a few comments.

General points -- the line lengths in the new text seem a bit long. Also, I wonder if it is worth covering / providing call-outs to the interactions with the annotations future? I imagine that will be something many readers will be thinking about.

A

Should we provide or link to migration guidance here, especially given that this is the first time a __future__ won't become the actual future?

Potentially this could be added later, but I think a longer narrative summary of annotationlib and where it fits in could be of use -- we jump straight into functions here. Contrast with pathlib, heapq, hashlib.

I wonder if there are words from 749 that we could incorporate? Effectively, something that briefly talks to where this module fits into the landscape, perhaps aimed at the fairly experienced user of types/inspect/typing, but someone who hasn't followed the PEPs.

Yes, I was thinking of adding that too, but ran out of energy while working on the initial version. :) I'll probably work on this later.

I wrote such a summary now, along with a historical account of annotation semantics, since that seems like something the docs should cover.

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

Doctest failures:

Document: library/annotationlib
-------------------------------
**********************************************************************
File "library/annotationlib.rst", line 67, in default
Failed example:
    call_evaluate_function(Alias.evaluate_value, Format.VALUE)
Exception raised:
    Traceback (most recent call last):
      File "/home/runner/work/cpython/cpython/Lib/doctest.py", line 1395, in __run
        exec(compile(example.source, filename, "single",
        ~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                     compileflags, True), test.globs)
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "<doctest default[1]>", line 1, in <module>
        call_evaluate_function(Alias.evaluate_value, Format.VALUE)
        ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/home/runner/work/cpython/cpython/Lib/annotationlib.py", line 421, in call_evaluate_function
        return call_annotate_function(evaluate, format, owner=owner, _is_evaluate=True)
      File "/home/runner/work/cpython/cpython/Lib/annotationlib.py", line 446, in call_annotate_function
        return annotate(format)
      File "<doctest default[0]>", line 1, in Alias
        type Alias = undefined
                     ^^^^^^^^^
    NameError: name 'undefined' is not defined
**********************************************************************

Document: library/typing
------------------------
**********************************************************************
File "library/typing.rst", line 2181, in default
Failed example:
    Alias.__value__
Exception raised:
    Traceback (most recent call last):
      File "/home/runner/work/cpython/cpython/Lib/doctest.py", line 1395, in __run
        exec(compile(example.source, filename, "single",
        ~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                     compileflags, True), test.globs)
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "<doctest default[1]>", line 1, in <module>
        Alias.__value__
      File "<doctest default[0]>", line 1, in Alias
        type Alias = undefined
                     ^^^^^^^^^
    NameError: name 'undefined' is not defined
**********************************************************************
File "library/typing.rst", line 2185, in default
Failed example:
    Alias.evaluate_value(Format.VALUE)
Exception raised:
    Traceback (most recent call last):
      File "/home/runner/work/cpython/cpython/Lib/doctest.py", line 1395, in __run
        exec(compile(example.source, filename, "single",
        ~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                     compileflags, True), test.globs)
                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "<doctest default[3]>", line 1, in <module>
        Alias.evaluate_value(Format.VALUE)
        ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^
      File "<doctest default[0]>", line 1, in Alias
        type Alias = undefined
                     ^^^^^^^^^
    NameError: name 'undefined' is not defined
**********************************************************************

Most of these are nits. I got curious about the PR and found some small things 🙈 !

Overall, this looks good @JelleZijlstra. I'm wondering if we are going a bit too deep into implementation in the Data Model Language Reference page.

Co-authored-by: Carol Willing <carolcode@willingconsulting.com>

Thanks for the review @willingc! Which part do you think goes into too much detail? I looked over the data model changes and all the changes seem relevant to me.

Thanks for the review @willingc! Which part do you think goes into too much detail? I looked over the data model changes and all the changes seem relevant to me.

@JelleZijlstra I reread the data model changes again on the rendered page (instead of the diff). On the initial read, I thought there was implementation content mixed in, but I was mistaken and misled by the rST markup. Thanks for rechecking and sorry for the extra noise.

Let's 🚢 this. 😄

JelleZijlstra added 6 commits July 23, 2024 21:21

pythongh-119180 : Documentation for PEP 649/749

20dcb62

Document evaluate_forward_ref

206560c

Merge remote-tracking branch 'upstream/main' into pep649-doc

edd12a2

add something

79ce456

docs for annotationlib

3f70c21

Update inspect

e297349

JelleZijlstra requested a review from AlexWaygood as a code owner July 24, 2024 14:29

bedevere-app Bot mentioned this pull request Jul 24, 2024

Implement PEP 649 and PEP 749 #119180

Closed

30 tasks

bedevere-app Bot added the awaiting core review label Jul 24, 2024

picnixz reviewed Jul 24, 2024

View reviewed changes

JelleZijlstra and others added 4 commits July 27, 2024 09:17

Apply suggestions from code review

d52fb08

Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>

Merge remote-tracking branch 'upstream/main' into pep649-doc

4e7a2a5

More feedback

35312e7

Docs expansion

b30abbd

JelleZijlstra added the skip news label Jul 27, 2024

AA-Turner added the docs Documentation in the Doc dir label Jul 27, 2024

JelleZijlstra added 2 commits July 27, 2024 11:24

formatting

bcb6a9f

Merge remote-tracking branch 'upstream/main' into pep649-doc

c82fb66

AA-Turner reviewed Jul 27, 2024

View reviewed changes

JelleZijlstra and others added 5 commits July 27, 2024 11:49

                  ``from __future__ import annotations`` was previously scheduled to
-                 become mandatory in Python 3.10, but the Python Steering Council
-                 twice decided to delay the change
-                 (`announcement for Python 3.10 <https://mail.python.org/archives/list/python-dev@python.org/message/CLVXXPQ2T2LQ5MP2Y53VVQFCXYWQJHKZ/>`__;
-                 `announcement for Python 3.11 <https://mail.python.org/archives/list/python-dev@python.org/message/VIZEBX5EYMSYIJNDBF6DMUMZOCWHARSO/>`__).
-                 No final decision has been made yet. See also :pep:`563` and :pep:`649`.
+                 become mandatory in Python 3.10, but the change was delayed and ultimately
+                 canceled. This feature will eventually be deprecated and removed. See
+                 :pep:`649` and :pep:`749`.

		The :mod:`!annotationlib` module provides tools for introspecting :term:`annotations <annotation>`
		on modules, classes, and functions.

gh-119180: Documentation for PEP 649 and 749 by JelleZijlstra · Pull Request #122235 · python/cpython · GitHub

Uh oh!

Uh oh!

gh-119180: Documentation for PEP 649 and 749 - #122235

gh-119180: Documentation for PEP 649 and 749#122235JelleZijlstra merged 24 commits intopython:mainpython/cpython:mainfrom JelleZijlstra:pep649-docJelleZijlstra/cpython:pep649-docCopy head branch name to clipboard

Conversation

JelleZijlstra commented Jul 24, 2024 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

picnixz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AA-Turner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AA-Turner Jul 27, 2024

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AA-Turner Jul 27, 2024

Choose a reason for hiding this comment

Uh oh!

JelleZijlstra Jul 27, 2024

Choose a reason for hiding this comment

Uh oh!

JelleZijlstra Sep 10, 2024

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AA-Turner commented Aug 7, 2024

Uh oh!

savannahostrowski left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

willingc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JelleZijlstra commented Sep 11, 2024

Uh oh!

willingc commented Sep 11, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

gh-119180: Documentation for PEP 649 and 749#122235
JelleZijlstra merged 24 commits into
python:mainfrom
JelleZijlstra:pep649-doc

JelleZijlstra commented Jul 24, 2024 •
edited by github-actions Bot
Loading

savannahostrowski left a comment •
edited
Loading