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.