gh-95913: Copyedit, link & format Typing Features section in 3.11 What's New

[CAM-Gerlach]

Part of #95913

Fixes Sphinx and textual issues in the What's New in Python 3.11 "New Features Related to Type Hints" section, improves the clarity, quality and non-duplication of the text, and links to referenced documentation sections.

Non-trivial highlights:

• Split PEP 646 description into two paragraphs for easier readability
• Clarify the syntax and semantics of the description of the interaction of total and required
• Link the PEP 484 section implicitly referred by PEP 673 directly, as its quite non-trivial to find
• Use a more Pythonically (and perhaps culturally) first/last name in PEP 681 example
• Clarify PEP 563 status description, particularly that this is not the first deferral, the more common form as well as a link to the __future__ statement, and make the link text more descriptive

General changes:

• Add Sphinx cross-references to additional items
• Clarify the text in various spots
• Fix/improve a number of other minor grammar, punctuation and phrasing issues
• Consistent section heading capitalization, ref target labels and spacing

• Issue: Edit What's New for Python 3.11 #95913

[JelleZijlstra]

Thanks, mostly looks good!

[AlexWaygood]

What's the motivation for the ALLCAPS change here? It looks like shouting to me.

("OK" is fine but I'm not a fan of "ERROR".)

[CAM-Gerlach]

It is intended to draw emphasis to the key contrast these examples are included to illustrate—the first and second are valid, while the third is invalid and produces an error. Also, "OK" is of course the correct, canonical capitalization of "OK", while it is "Error" is ALLCAPSed given the particular importance and best practice of prominently marking bad code as such.

[AlexWaygood]

"ERROR" still seems ugly and unnecessary to me; I don't really see the need for a change here.

[AlexWaygood]

It also goes against the prevailing style in the typing docs — there are several # error comments, but none of them are ALLCAPS: https://docs.python.org/3/library/typing.html

[CAM-Gerlach]

Personally, I value clarity and explicitness over subjective aesthetic preference, given a stated rationale. Also, I'm not sure how relevant the conventions of the typing stdlib doc are here, given it is a separate document from this one, and those particular choices may or may not have a clear, thought-out rationale.

But what do others think? @ezio-melotti @JelleZijlstra ?

If an all-caps ERROR is simply too objectionable, we can at least give it proper case

Suggested change

	m3: Movie = {"year": 2022} # ERROR (missing required field title)
	m3: Movie = {"year": 2022} # Error (missing required field title)

[CAM-Gerlach]

@AlexWaygood what about if we go with @ezio-melotti 's suggestion and not ALLCAPSing Error, like this?

Suggested change

	m3: Movie = {"year": 2022} # ERROR (missing required field title)
	m3: Movie = {"year": 2022} # Error (title is required, but missing)

[AlexWaygood]

@AlexWaygood what about if we go with @ezio-melotti 's suggestion and not ALLCAPSing Error, like this?

Sounds good to me.

[CAM-Gerlach]

For inline comments like these I tend to use all lowercase and no full stops at the end, so even ok and error would be fine with me.

Same, I don't add a period at the end either for inline or single-line comments...but I notice you do use period for titles (and commit summary lines), which slightly confuses me :) (To note, I do start them with a capital letter, which follows the examples in PEP 8 and avoids looking (IMO) sloppy—though that latter point is personal aesthetic preference)

[encukou]

FWIW, in this general document, I'd appreciate a subtle indication that this is a typing error -- not a SyntaxError or runtime exception. Perhaps Wrong, in whatever case you prefer.

[CAM-Gerlach]

That's a great point—to be more specific, we could say something like Type check error or Incompatible type

[AlexWaygood]

Thanks! I still don't really think there's a good rationale for changing # error to # ERROR, but that's a minor nit :)

[encukou]

Merging, the minor nit can be resolved later.

[miss-islington]

Thanks @CAM-Gerlach for the PR, and @encukou for merging it 🌮🎉.. I'm working now to backport this PR to: 3.11.
🐍🍒⛏🤖

[bedevere-bot]

GH-96934 is a backport of this pull request to the 3.11 branch.