python
Edit What's New for Python 3.11
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:
Pre-/co-requisites
- #97740
- #97741
- #95914
- #95916
- #96016
- #95937
- #95976
- #98315
Edit Sections
- [x] New Features
- #95915
- #97739
- #97718
- #95915
- [x] New Features related to Type Hints
- #96097
- [x] Other Language Changes
- #97719
- [x] Other CPython Implementation Changes
- #97720
- [x] New Modules
- #97721
- [ ] Improved Modules
- #97806
- #98295
- #98250
- #98304
- [ ] Optimizations
- [ ] Faster CPython
- [ ] CPython bytecode changes
- [ ] Deprecated
- [ ] Pending Removal in Python 3.12
- [ ] Removed
- [ ] Porting to Python 3.11
- [ ] Build Changes
- [ ] C API Changes
Add new APIs
Adapted and updated from @pablogsal 's post
- [x] module: asyncio.exceptions added: ['BrokenBarrierError'] (Already implicitly referred to by Barrier mention, but will be linked directly in editing pass) #97806
- [x] ~~module: asyncio.proactor_events added: ['BaseProactorEventLoop.sock_recvfrom_into', 'BaseProactorEventLoop.sock_recvfrom', 'BaseProactorEventLoop.sock_sendto']~~ (Already added; will be improved in editing phase)
- [x] module: asyncio.runners added: ['Runner'] #97806
- [x] ~~module: asyncio.selector_events added: ['BaseSelectorEventLoop.sock_recvfrom_into', 'BaseSelectorEventLoop.sock_recvfrom', 'BaseSelectorEventLoop.sock_sendto']~~ (Already added; will be improved in editing phase) #97806
- [x] ~~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)
- [x] module: asyncio.tasks added: ['Task.cancelling', 'Task.uncancel'] #97806
- [x] ~~module: asyncio.windows_events added: ['IocpProactor.recvfrom_into']~~ (Appears to be undocumented implementation detail of the added socket methods)
- [x] module: contextlib added: ['chdir'] #95962
- [ ] module: enum
added: ['global_enum_repr', 'global_str', 'show_flag_values', 'global_flag_repr']
(Not documented yet, and
ReprEnumandglobal_enummentioned in What's New aren't either) #98298 - [x] module: hashlib added: ['file_digest'] #95965 #95980
- [ ] module: inspect added: ['FrameInfo'] Already discussed, just not explicitly referenced #98304
- [ ] module: logging.handlers added: ['SysLogHandler.createSocket'] (Not documented yet; seems like it should be?) #98307 #98319 #98320
- [x] ~~module: pdb added: ['ScriptTarget', 'ModuleTarget']~~ (Made private) #96053
- [ ] module: string added: ['Template.is_valid', 'Template.get_identifiers'] #98311
- [ ] module: tempfile added: ['SpooledTemporaryFile.detach', 'SpooledTemporaryFile.read1', 'SpooledTemporaryFile.writable', 'SpooledTemporaryFile.readinto1', 'SpooledTemporaryFile.seekable', 'SpooledTemporaryFile.readable', 'SpooledTemporaryFile.readinto'] #98312
- [x] module: traceback added: ['TracebackException.print', 'StackSummary.format_frame_summary'] #95980
- [ ] module: zipfile added: ['Path.suffix', 'Path.stem', 'Path.suffixes', 'ZipFile.mkdir'] #98314
Related
- #93986
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']
- [x] module: hashlib added: ['file_digest']
- [x] module: traceback added: ['TracebackException.print', 'StackSummary.format_frame_summary']
- [x] module: pdb added: ['ScriptTarget', 'ModuleTarget']
- [ ] module: inspect added: ['FrameInfo']
- [x] 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']
- [x] module: asyncio.tasks added: ['Task.cancelling', 'Task.uncancel']
- [x] module: asyncio.selector_events added: ['BaseSelectorEventLoop.sock_recvfrom_into', 'BaseSelectorEventLoop.sock_recvfrom', 'BaseSelectorEventLoop.sock_sendto']
- [x] module: asyncio.proactor_events added: ['BaseProactorEventLoop.sock_recvfrom_into', 'BaseProactorEventLoop.sock_recvfrom', 'BaseProactorEventLoop.sock_sendto']
- [x] module: asyncio.sslproto added: ['SSLProtocolState', 'AppProtocolState', 'add_flowcontrol_defaults', 'SSLProtocol.get_buffer', 'SSLProtocol.buffer_updated']
- [x] module: asyncio.runners added: ['Runner']
- [x] module: asyncio.exceptions added: ['BrokenBarrierError']
- [x] module: asyncio.windows_events added: ['IocpProactor.recvfrom_into']
- [ ] module: logging.handlers added: ['SysLogHandler.createSocket']
CC: @tiran @iritkatriel @asvetlov @ambv as you were involved in some of the changes (and the dev in residence for awareness).
@jaraco should pdb.ScriptTarget pdb.ModuleTarget be documented? I think they were intended to be implementation details.
@jaraco should pdb.ScriptTarget pdb.ModuleTarget be documented? I think they were intended to be implementation details.
Correct. Those are implementation details.
Regarding asyncio:
module: asyncio.selector_events added: ['BaseSelectorEventLoop.sock_recvfrom_into', 'BaseSelectorEventLoop.sock_recvfrom', 'BaseSelectorEventLoop.sock_sendto']
Already documented in What's new https://docs.python.org/3.12/whatsnew/3.11.html#asyncio, although the markup can be improved.
module: asyncio.proactor_events added: ['BaseProactorEventLoop.sock_recvfrom_into', 'BaseProactorEventLoop.sock_recvfrom', 'BaseProactorEventLoop.sock_sendto']
Same as selector events.
module: asyncio.sslproto added: ['SSLProtocolState', 'AppProtocolState', 'add_flowcontrol_defaults', 'SSLProtocol.get_buffer', 'SSLProtocol.buffer_updated']
Implementation details so no need to be documented.
module: asyncio.runners added: ['Runner']
API is documented but What's New entry is missing.
@CAM-Gerlach Feel free to create a draft asyncio PR to add What's new entries, you can copy paste most from API docs. Ping me and I'll help you out in review.
Okay, thanks @kumaraditya303 . I've added an updated list to the OP.
API is documented but What's New entry is missing.
I'll go ahead and submit a PR on that and tag you and Guido for review; I assume I should add Task.cancelling/Task.uncancel as well, since they are also newly added and documented?
Implementation details so no need to be documented.
Okay, but perhaps they should they be marked as such (with _) then, like the pdb classes were in #96053 ? Too late to do that for 3.11, though... seems like asyncio.windows_events.IocpProactor.recvfrom_into is likewise an undocumented implementation detail of the added socket methods, so I marked it accordingly.
Also, the added BrokenBarrierError appears to be ancillary to the addition of Barrier, though I will give it a direct link in editing the asycio section, for completeness.
I'll just go ahead and copyedit the subsection as well as add the new APIs in the same PR, to avoid delaying the editing pass further (and same with the others).
I'm volunteering to finish the asyncio what's new entry, based on Kumar's and CAM's feedback above and my own ideas (and adding timeout, which was somehow missing from Pablo's list).
Thanks to all involved for your help thus far!
Next big batch of changes are (after a lot of catchup after the sprints) all submitted, adding the remaining missing What's New items that @pablogsal detected, as well as a handful of other missing APIs found crawling the modules' relevant documention, and documenting some elsewhere that hadn't been. In addition, the relevant sections were also edited, and a blurb was added for PEP 670, the final missing undocumented PEP.
Next up, I'll drop a quick PR separating remaining sections/subsections by at least two spaces and adding ref target labels, get that merged quickly, and then start working through them one by one. Once the PRs above all get merged (hopefully very shortly), I'll do the same for each of the Improved modules sections, and also submit the final PR linking the summary items to their entries. Finally, if time allows, I'll go through the documentation of each module not mentioned here and and check that there aren't any major missing improvements to mention.
Should this be closed now? It's been a while since 3.11 was released.
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.
Request review from me and I'll merge it for you, I'll be trusting you for the sphinx markup ;)
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!
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.
