gh-95914: Add paragraph about PEP 654 in main body of 'What's New in 3.11' #95937

iritkatriel · 2022-08-12T18:44:58Z

Issue: List and document remaining significant PEPs in What's New in 3.11 #95914

…ew in 3.11'

gvanrossum

If you can add a link to except* in the docs, fine. Otherwise, fine too.

gvanrossum · 2022-08-12T19:55:08Z

Doc/whatsnew/3.11.rst

+to raise and handle multiple unrelated exceptions simultaneously.
+The builtin types :exc:`ExceptionGroup` and :exc:`BaseExceptionGroup`
+make it possible to group exceptions and raise them together.
+The new ``except*`` syntax generalizes ``except`` to match subgroups


In line with our policy that PEPs are historic documents, not documentation, maybe this should deep link to the part under https://docs.python.org/3.11/reference/compound_stmts.html#try where except* is described?

Both :keyword:`except* <except_star>` and :ref:`except* <except_star>` currently link to the beginning of the try section, where the except_star label is defined. For a deep link, the label should be moved down to the relevant paragraph.

Actually, the keyword appears to be linked precisely, both judging from its position in the source on both 3.12 and 3.11, and the fact that the index entry correctly links to it. But maybe a :keyword: ref doesn't?

However, the :ref: is indeed not; it would be good to move the non-try ones (that presumably don't rely on the section name for default link text, since it doesn't even mention except/else/finally) down to the appropriate passages.

I think a link to the top of the section is fine.

ezio-melotti · 2022-08-12T22:17:56Z

Doc/whatsnew/3.11.rst

+
+See :pep:`654` for more details.
+
+(Contributed by Irit Katriel in :issue:`45292`. PEP written by


Suggested change

(Contributed by Irit Katriel in :issue:`45292`. PEP written by

(Contributed by Irit Katriel in :gh:`89455`. PEP written by

This should be done (if at all) in a separate PR where the summary reference to the same issue is updated as well.

I say "if at all" because this is not historically accurate - I did the work under a bpo issue. Are you going to change all references to bpo issues in the docs to the gh issues they were mapped to?

ezio-melotti · 2022-08-12T22:18:00Z

Doc/whatsnew/3.11.rst

+
+See :pep:`678` for more details.
+
+(Contributed by Irit Katriel in :issue:`45607`. PEP written by


Suggested change

(Contributed by Irit Katriel in :issue:`45607`. PEP written by

(Contributed by Irit Katriel in :gh:`89770`. PEP written by

ezio-melotti · 2022-08-12T22:28:47Z

Doc/whatsnew/3.11.rst

+to raise and handle multiple unrelated exceptions simultaneously.
+The builtin types :exc:`ExceptionGroup` and :exc:`BaseExceptionGroup`
+make it possible to group exceptions and raise them together.
+The new ``except*`` syntax generalizes ``except`` to match subgroups


Both :keyword:`except* <except_star>` and :ref:`except* <except_star>` currently link to the beginning of the try section, where the except_star label is defined. For a deep link, the label should be moved down to the relevant paragraph.

CAM-Gerlach

Thanks, @iritkatriel . A few relatively modest comments, mostly as applyable suggestions.

Doc/whatsnew/3.11.rst

CAM-Gerlach · 2022-08-13T00:20:34Z

Doc/whatsnew/3.11.rst

@@ -176,14 +176,33 @@ The :option:`-X` ``no_debug_ranges`` option and the environment variable
 See :pep:`657` for more details. (Contributed by Pablo Galindo, Batuhan Taskaya
 and Ammar Askar in :issue:`43950`.)

+Exception Groups and ``except*`` (PEP 654)


Could we be consistent about PEP numbers in Feature section titles? Right now the type hint PEP sections are in the form PEP NNN: <Title>, this section and the one below is in the form <Title> (PEP NNN), and the two above it don't mention the PEP number at all in the title.

IMO, it would seem to make sense to either elide the PEP numbers in the New Features section titles (as I do for the section below in #95914 , since they don't add much value for most users and are already mentioned/linked in the section body and Summary), or consistently use them with the same format between these two sections (I can take care of the others in my separate PRs, but it would be nice to be consistent here).

CAM-Gerlach · 2022-08-13T00:30:21Z

Doc/whatsnew/3.11.rst

+to raise and handle multiple unrelated exceptions simultaneously.
+The builtin types :exc:`ExceptionGroup` and :exc:`BaseExceptionGroup`
+make it possible to group exceptions and raise them together.
+The new ``except*`` syntax generalizes ``except`` to match subgroups


Actually, the keyword appears to be linked precisely, both judging from its position in the source on both 3.12 and 3.11, and the fact that the index entry correctly links to it. But maybe a :keyword: ref doesn't?

However, the :ref: is indeed not; it would be good to move the non-try ones (that presumably don't rely on the section name for default link text, since it doesn't even mention except/else/finally) down to the appropriate passages.

Doc/whatsnew/3.11.rst

CAM-Gerlach · 2022-08-13T00:37:10Z

Doc/whatsnew/3.11.rst

+default traceback.
+
+See :pep:`678` for more details.
+
+(Contributed by Irit Katriel in :issue:`45607`. PEP written by
+Zac Hatfield-Dodds.)


Could we make these changes in #95915 instead, since that PR is closer to the scope of the change (copyediting existing entries vs. adding a specific new one), and it will cause a significant merge conflict for whichever PR gets merged second otherwise?

ok, I'll remove it and you can put it there.

Co-authored-by: CAM Gerlach <[email protected]>

miss-islington · 2022-08-13T11:49:07Z

Thanks @iritkatriel for the PR 🌮🎉.. I'm working now to backport this PR to: 3.11.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

…ew in 3.11' (pythonGH-95937) (cherry picked from commit 1402d2c) Co-authored-by: Irit Katriel <[email protected]>

bedevere-bot · 2022-08-13T11:49:20Z

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

CAM-Gerlach · 2022-08-14T04:57:20Z

A quick followup about the except* keyword—based on some testing by @ezio-melotti and myself, the index entry was a red herring; what actually happens with the :keyword: role is that it applies semantics and styling (i.e. literal, typically) but it just links to normal ref target labels, rather than ones created by a special directives, which the Sphinx docs also confirm. I'll open a separate PR to move the relevant ref target labels in compound_statement to more precise locations.

…3.11' (GH-95937) (cherry picked from commit 1402d2c) Co-authored-by: Irit Katriel <[email protected]>

pythongh-95914: add paragraph about pep 654 in main body of 'what's n…

232d87b

…ew in 3.11'

bedevere-bot added docs Documentation in the Doc dir skip news awaiting core review labels Aug 12, 2022

iritkatriel requested review from 1st1, gvanrossum and CAM-Gerlach August 12, 2022 18:45

gvanrossum changed the title ~~gh-95914: add paragraph about pep 654 in main body of 'what's new in 3.11'~~ gh-95914: Add paragraph about pep 654 in main body of 'what's new in 3.11' Aug 12, 2022

gvanrossum changed the title ~~gh-95914: Add paragraph about pep 654 in main body of 'what's new in 3.11'~~ gh-95914: Add paragraph about PEP 654 in main body of 'What's New in 3.11' Aug 12, 2022

gvanrossum approved these changes Aug 12, 2022

View reviewed changes

bedevere-bot added awaiting merge and removed awaiting core review labels Aug 12, 2022

ezio-melotti reviewed Aug 12, 2022

View reviewed changes

CAM-Gerlach mentioned this pull request Aug 12, 2022

List and document remaining significant PEPs in What's New in 3.11 #95914

Closed

5 tasks

CAM-Gerlach added needs backport to 3.10 only security fixes 3.10 only security fixes needs backport to 3.11 only security fixes 3.11 only security fixes and removed needs backport to 3.10 only security fixes 3.10 only security fixes labels Aug 13, 2022

CAM-Gerlach requested changes Aug 13, 2022

View reviewed changes

iritkatriel and others added 7 commits August 13, 2022 12:18

whitespace

6953eba

Co-authored-by: CAM Gerlach <[email protected]>

heading

87d77c4

Co-authored-by: CAM Gerlach <[email protected]>

whitespace

e18ee3c

Co-authored-by: CAM Gerlach <[email protected]>

:keyword:

4b13c09

Co-authored-by: CAM Gerlach <[email protected]>

revert PEP-678 changes. Update titles

dd28613

whitespace

c64a047

whitespace

602fdc9

iritkatriel merged commit 1402d2c into python:main Aug 13, 2022

bedevere-bot removed the awaiting merge label Aug 13, 2022

iritkatriel deleted the whatsnew branch August 13, 2022 11:49

bedevere-bot removed the needs backport to 3.11 only security fixes label Aug 13, 2022

This was referenced Aug 14, 2022

Ref target labels for except/except*/finally not located precisely #95975

Closed

gh-95975: Move except/*/finally ref labels to more precise locations #95976

Merged

gh-95913: Fix and copyedit New Features section of 3.11 What's New #95915

Merged

miss-islington added a commit that referenced this pull request Sep 8, 2022

gh-95914: Add paragraph about PEP 654 in main body of 'What's New in …

1276e73

…3.11' (GH-95937) (cherry picked from commit 1402d2c) Co-authored-by: Irit Katriel <[email protected]>

CAM-Gerlach mentioned this pull request Sep 26, 2022

Edit What's New for Python 3.11 #95913

Closed

33 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

gh-95914: Add paragraph about PEP 654 in main body of 'What's New in 3.11' #95937

gh-95914: Add paragraph about PEP 654 in main body of 'What's New in 3.11' #95937

iritkatriel commented Aug 12, 2022 •

edited by bedevere-bot

Loading

gvanrossum left a comment

gvanrossum Aug 12, 2022

ezio-melotti Aug 12, 2022

CAM-Gerlach Aug 13, 2022 •

edited

Loading

iritkatriel Aug 13, 2022

ezio-melotti Aug 12, 2022

iritkatriel Aug 13, 2022

ezio-melotti Aug 12, 2022

ezio-melotti Aug 12, 2022

CAM-Gerlach left a comment

CAM-Gerlach Aug 13, 2022

CAM-Gerlach Aug 13, 2022 •

edited

Loading

CAM-Gerlach Aug 13, 2022

iritkatriel Aug 13, 2022

miss-islington commented Aug 13, 2022

bedevere-bot commented Aug 13, 2022

CAM-Gerlach commented Aug 14, 2022


		See :pep:`654` for more details.

		(Contributed by Irit Katriel in :issue:`45292`. PEP written by

	(Contributed by Irit Katriel in :issue:`45292`. PEP written by
	(Contributed by Irit Katriel in :gh:`89455`. PEP written by


		See :pep:`678` for more details.

		(Contributed by Irit Katriel in :issue:`45607`. PEP written by

	(Contributed by Irit Katriel in :issue:`45607`. PEP written by
	(Contributed by Irit Katriel in :gh:`89770`. PEP written by

gh-95914: Add paragraph about PEP 654 in main body of 'What's New in 3.11' #95937

gh-95914: Add paragraph about PEP 654 in main body of 'What's New in 3.11' #95937

Conversation

iritkatriel commented Aug 12, 2022 • edited by bedevere-bot Loading

gvanrossum left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

CAM-Gerlach Aug 13, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

CAM-Gerlach left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

CAM-Gerlach Aug 13, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

miss-islington commented Aug 13, 2022

bedevere-bot commented Aug 13, 2022

CAM-Gerlach commented Aug 14, 2022

iritkatriel commented Aug 12, 2022 •

edited by bedevere-bot

Loading

CAM-Gerlach Aug 13, 2022 •

edited

Loading

CAM-Gerlach Aug 13, 2022 •

edited

Loading