Edit What's New for Python 3.11

[CAM-Gerlach]

As discussed with @pablogsal , this is a meta-issue for coordinating an editing pass on the What's New in Python 3.11 document.

The focus with this issue and its accompanying PRs will be on textual and reST/Sphinx fixes and improvements to the existing content, rather than adding any missing NEWS entries, or touching the organization of the document itself. Another issue, #95914 , will cover adding the PEPs not currently listed to the Summary - Release highlights section, as well as a few PEPs that are not documented at all in What's New, but probably should be somewhere (PEP-624, PEP-654 and PEP-670).

It seems best to split this into separate PRs, one for each top-level section. I've listed them here for reference, with PRs linked as they are submitted:

Prerequisites/General Changes

• Doc: Fix ! in C domain ref target syntax #97740
  • gh-97740: Fix bang in Sphinx C domain ref target syntax #97741
• List and document remaining significant PEPs in What's New in 3.11 #95914
  • gh-95914: Add Py_UNICODE encode APIs removed in PEP 624 to 3.11 What's New #96016
  • gh-95914: Add paragraph about PEP 654 in main body of 'What's New in 3.11' #95937
    • gh-95975: Move except/*/finally ref labels to more precise locations #95976
  • gh-95914: Add What's New item describing PEP 670 changes #98315
• gh-95913: Prepare remaining Whatsnew sections for editing #98342
• Forward-ports
  • gh-95913: Forward-port int/str security change to 3.11 What's New in main #98344
  • gh-95913: Move subinterpreter exper removal to 3.11 WhatsNew #98345

Edit Sections

• Summary
  • List and document remaining significant PEPs in What's New in 3.11 #95914
    • gh-95914: Add missing PEPs to the Summary section of 3.11 What's New #95916
    • gh-95914: Add links to 3.11 WhatsNew Summary items #98416
• New Features
  • gh-95913: Fix and copyedit New Features section of 3.11 What's New #95915
    • gh-95913: Fix PEP number in PEP 678 What's New ref label #97739
  • gh-95913: Move py.exe to appropriate What's New section & refine text #97718
• New Features related to Type Hints
  • gh-95913: Copyedit, link & format Typing Features section in 3.11 What's New #96097
• Other Language Changes
  • gh-95913: Copyedit/improve Other Language Changes What's New section #97719
• Other CPython Implementation Changes
  • gh-95913: Copyedit/improve Implementation Changes What's New section #97720
• New Modules
  • gh-95913: Copyedit/improve New Modules What's New section #97721
• Improved Modules
  • GH-95913: Update what's new in 3.11 for asyncio #97806
  • gh-95913: Copyedit, xref and organize enum section #98295
    • Enum.__str__ change could be improved in What's New #98250
  • gh-95913: Copyedit & xref FrameInfo in Whatsnew inspect section #98304
• Optimizations
  • gh-95913: Edit & expand Optimizations in 3.11 WhatsNew #98426
• Faster CPython
  • gh-95913: Edit Faster CPython section in 3.11 WhatsNew #98429
• CPython bytecode changes
  • gh-95913: Edit, expand & format Bytecode sect in 3.11 WhatsNew #98559
• Deprecated
  • gh-95913: Edit & expand Deprecated section of 3.11 WhatsNew #98581
• Pending Removal in Python 3.12
  • gh-95913: Fix, sort & expand pending removal sect in 3.11 WhatsNew #98583
• Removed
  • gh-95913: Edit, xref & sort 3.11 WhatsNew Removed section #98584
• Porting to Python 3.11
  • gh-95913: Edit, sort & expand 3.11 WhatsNew Porting section #98585
• Build Changes
  • gh-95913: Edit, link and sort 3.11 WhatsNew Build section #98588
  • gh-95913: Consolidate build requirements changes in 3.11 WhatsNew #98781
• C API Changes

Add new APIs

Adapted and updated from @pablogsal 's post

• module: asyncio.exceptions
  added: ['BrokenBarrierError']
  (Already implicitly referred to by Barrier mention, but will be linked directly in editing pass)
  GH-95913: Update what's new in 3.11 for asyncio #97806
• module: asyncio.proactor_events
  added: ['BaseProactorEventLoop.sock_recvfrom_into', 'BaseProactorEventLoop.sock_recvfrom', 'BaseProactorEventLoop.sock_sendto']
  (Already added; will be improved in editing phase)
• module: asyncio.runners
  added: ['Runner']
  GH-95913: Update what's new in 3.11 for asyncio #97806
• module: asyncio.selector_events
  added: ['BaseSelectorEventLoop.sock_recvfrom_into', 'BaseSelectorEventLoop.sock_recvfrom', 'BaseSelectorEventLoop.sock_sendto']
  (Already added; will be improved in editing phase)
  GH-95913: Update what's new in 3.11 for asyncio #97806
• module: asyncio.sslproto
  added: ['SSLProtocolState', 'AppProtocolState', 'add_flowcontrol_defaults', 'SSLProtocol.get_buffer', 'SSLProtocol.buffer_updated']
  (Considered implementation details, so @kumaraditya303 says no need to be documented (indeed, I don't see it documented anywhere else but the changelog)
• module: asyncio.tasks
  added: ['Task.cancelling', 'Task.uncancel']
  GH-95913: Update what's new in 3.11 for asyncio #97806
• module: asyncio.windows_events
  added: ['IocpProactor.recvfrom_into']
  (Appears to be undocumented implementation detail of the added socket methods)
• module: contextlib
  added: ['chdir']
  bpo-25625: Document contextlib.chdir in the 3.11 what's new #95962
• module: enum
  added: ['global_enum_repr', 'global_str', 'show_flag_values', 'global_flag_repr']
  (Not documented yet, andReprEnum and global_enum mentioned in What's New aren't either)
  Document new 3.11 enum APIs (ReprEnum, global_* and/or show_flag_values) #98298
  gh-98298: [Enum] document ReprEnum, global_enum, and show_flag_values #98455
• module: hashlib
  added: ['file_digest']
  gh-89313: Add hashlib.file_digest to whatsnew 3.11 #95965
  gh-95913: Add traceback module additions to what's new in 3.11 #95980
• module: inspect
  added: ['FrameInfo']
  Already discussed, just not explicitly referenced
  gh-95913: Copyedit & xref FrameInfo in Whatsnew inspect section #98304
• module: logging.handlers
  added: ['SysLogHandler.createSocket']
  (Not documented yet; seems like it should be?)
  Logging: SysLogHandler.createSocket added in 3.11 but not documented #98307
  gh-98307: Add docstring and documentation for SysLogHandler.createSocket (GH-98319) #98319
  gh-95913: Add WhatsNew section for new logging APIs #98320
• module: pdb
  added: ['ScriptTarget', 'ModuleTarget']
  (Made private)
  gh-95913: make the new internal classes pdb.ModuleTarget/ScriptTarget private #96053
• module: string
  added: ['Template.is_valid', 'Template.get_identifiers']
  gh-95913 Add string section to Whatsnew with new Template methods #98311
• module: tempfile
  added: ['SpooledTemporaryFile.detach', 'SpooledTemporaryFile.read1', 'SpooledTemporaryFile.writable', 'SpooledTemporaryFile.readinto1', 'SpooledTemporaryFile.seekable', 'SpooledTemporaryFile.readable', 'SpooledTemporaryFile.readinto']
  gh-95913: Add io support for SpooledTemporaryFile in Whatsnew #98312
  gh-95913: Fix grammar for SpooledTemporaryFile 3.11 whatsnew entry #98604
• module: traceback
  added: ['TracebackException.print', 'StackSummary.format_frame_summary']
  gh-95913: Add traceback module additions to what's new in 3.11 #95980
• module: zipfile
  added: ['Path.suffix', 'Path.stem', 'Path.suffixes', 'ZipFile.mkdir']
  gh-95913: Edit zipfile Whatsnew section & add new APIs #98314

Related

• Document 3.13, 3.14, 4.0 and future removals #93986

Linked PRs

• gh-95913: Edit Faster CPython section in 3.11 WhatsNew #98429
• [3.11] gh-95913: Edit Faster CPython section in 3.11 WhatsNew (GH-98429) #102490
• [3.11] gh-95913: Consolidate build requirements changes in 3.11 WhatsNew (GH-98781) #102497
• GH-95913: Add the release date for Python 3.11 #109750
• [3.12] GH-95913: Add the release date for Python 3.11 (GH-109750) #109771
• [3.11] GH-95913: Add the release date for Python 3.11 (GH-109750) #109772

[pablogsal]

The following functions has been added in 3.11 and must be (maybe) documented as well:

• module: zipfile
  added: ['Path.suffix', 'Path.stem', 'Path.suffixes', 'ZipFile.mkdir']
• module: tempfile
  added: ['SpooledTemporaryFile.detach', 'SpooledTemporaryFile.read1', 'SpooledTemporaryFile.writable', 'SpooledTemporaryFile.readinto1', 'SpooledTemporaryFile.seekable', 'SpooledTemporaryFile.readable', 'SpooledTemporaryFile.readinto']
• module: hashlib
  added: ['file_digest']
• module: traceback
  added: ['TracebackException.print', 'StackSummary.format_frame_summary']
• module: pdb
  added: ['ScriptTarget', 'ModuleTarget']
• module: inspect
  added: ['FrameInfo']
• module: contextlib
  added: ['chdir']
• module: string
  added: ['Template.is_valid', 'Template.get_identifiers']
• module: enum
  added: ['global_enum_repr', 'global_str', 'show_flag_values', 'global_flag_repr']
• module: asyncio.tasks
  added: ['Task.cancelling', 'Task.uncancel']
• module: asyncio.selector_events
  added: ['BaseSelectorEventLoop.sock_recvfrom_into', 'BaseSelectorEventLoop.sock_recvfrom', 'BaseSelectorEventLoop.sock_sendto']
• module: asyncio.proactor_events
  added: ['BaseProactorEventLoop.sock_recvfrom_into', 'BaseProactorEventLoop.sock_recvfrom', 'BaseProactorEventLoop.sock_sendto']
• module: asyncio.sslproto
  added: ['SSLProtocolState', 'AppProtocolState', 'add_flowcontrol_defaults', 'SSLProtocol.get_buffer', 'SSLProtocol.buffer_updated']
• module: asyncio.runners
  added: ['Runner']
• module: asyncio.exceptions
  added: ['BrokenBarrierError']
• module: asyncio.windows_events
  added: ['IocpProactor.recvfrom_into']
• module: logging.handlers
  added: ['SysLogHandler.createSocket']

[pablogsal]

CC: @tiran @iritkatriel @asvetlov @ambv as you were involved in some of the changes (and the dev in residence for awareness).

[tiran]

hashlib.file_digest is covered by gh-95965.

[iritkatriel]

@jaraco should pdb.ScriptTarget pdb.ModuleTarget be documented? I think they were intended to be implementation details.

[jaraco]

@jaraco should pdb.ScriptTarget pdb.ModuleTarget be documented? I think they were intended to be implementation details.

Correct. Those are implementation details.

[CAM-Gerlach]

Thanks for the ping. Unfortunately not quit yet, as a couple of the PRs are still waiting for final review and merge, and it now seems that I inadvertently never submitted the PR fixing up the final C-API section, as well as the missing "New and Improved Modules" sections.

[kumaraditya303]

Request review from me and I'll merge it for you, I'll be trusting you for the sphinx markup ;)

[CAM-Gerlach]

The thing holding up both those isn't actually just reviewing the markup as for the others which were swiftly merged, but rather questions by the relevant subject matter experts in the particular domains ensuring that they were accurate. I've pinged both in that regard, and Victor passed on reviewing #95913 while Petr said he'd review this week, and I'm awaiting Ken's respond on #98429 and will ping him on Discord if I don't hear anything in a week. Thanks!

[Fidget-Spinner]

Is there anything left for this issue? I think it can be closed.

[CAM-Gerlach]

Yeah, a couple last things; see my comment above. I hope to get back to it soon-ish especially as I get ready to spin up on 3.12 as well as deploying new automated and semi-automated tooling to keep the What's News and Changelog in sync across branches.

[erlend-aasland]

@CAM-Gerlach, can we close this?

[hugovk]

I think it's time, 3.11 is now security-only.