gh-119180: Documentation for PEP 649 and 749

[JelleZijlstra]

• Issue: Implement PEP 649 and PEP 749 #119180

---

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

[picnixz]

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

[AA-Turner]

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

[AA-Turner]

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?

[AA-Turner]

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.

[JelleZijlstra]

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.

[JelleZijlstra]

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

[AA-Turner]

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
**********************************************************************

[savannahostrowski]

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

[willingc]

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.

[JelleZijlstra]

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.

[willingc]

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. 😄