From 7979097927a568c8c90853ca86676c1a2cdc1173 Mon Sep 17 00:00:00 2001 From: Danny Yang Date: Fri, 14 Jun 2024 16:46:15 -0400 Subject: [PATCH 01/11] clarify except* documentation --- Doc/reference/compound_stmts.rst | 27 ++++++++++++++++++--------- 1 file changed, 18 insertions(+), 9 deletions(-) diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index 42cca0664df71d..900252701afa77 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -245,13 +245,17 @@ handler is started. This search inspects the :keyword:`!except` clauses in turn until one is found that matches the exception. An expression-less :keyword:`!except` clause, if present, must be last; it matches any exception. -For an :keyword:`!except` clause with an expression, -that expression is evaluated, and the clause matches the exception -if the resulting object is "compatible" with the exception. An object is -compatible with an exception if the object is the class or a -:term:`non-virtual base class ` of the exception object, -or a tuple containing an item that is the class or a non-virtual base class -of the exception object. + +For an :keyword:`!except` clause with an expression, the +expression must evaluate to a type or a tuple containing types. Each type must +be a subclass of :exc:`BaseException`, otherwise the runtime will raise a +:exc:`TypeError` when the handler is evaluated. + +The clause matches the exception if the resulting object is "compatible" with +the exception. An object is compatible with an exception if the object is the +class or a :term:`non-virtual base class ` of the exception +object, or a tuple containing an item that is the class or a non-virtual base +class of the exception object. If no :keyword:`!except` clause matches the exception, the search for an exception handler @@ -378,8 +382,13 @@ exception group with an empty message string. :: ... ExceptionGroup('', (BlockingIOError())) -An :keyword:`!except*` clause must have a matching type, -and this type cannot be a subclass of :exc:`BaseExceptionGroup`. +Unlike :keyword:`except` clauses, :keyword:`!except*` clauses must have a matching +expression; `except*:` is not valid syntax. When the handler is evaluated, the +expression must evaluate to a type or a tuple containing types. Each type must +be a subclass of :exc:`BaseException` and must not be a subclass of +:exc:`BaseExceptionGroup`, otherwise the runtime will raise a :exc:`TypeError` +when the handler is evaluated. + It is not possible to mix :keyword:`except` and :keyword:`!except*` in the same :keyword:`try`. :keyword:`break`, :keyword:`continue` and :keyword:`return` From 4a58d67c673bcf0d261b01912c3dda8796795a45 Mon Sep 17 00:00:00 2001 From: Danny Yang Date: Fri, 14 Jun 2024 21:45:27 -0400 Subject: [PATCH 02/11] fix snippet --- Doc/reference/compound_stmts.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index 900252701afa77..f860c701552696 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -383,7 +383,7 @@ exception group with an empty message string. :: ExceptionGroup('', (BlockingIOError())) Unlike :keyword:`except` clauses, :keyword:`!except*` clauses must have a matching -expression; `except*:` is not valid syntax. When the handler is evaluated, the +expression; ``except*:`` is not valid syntax. When the handler is evaluated, the expression must evaluate to a type or a tuple containing types. Each type must be a subclass of :exc:`BaseException` and must not be a subclass of :exc:`BaseExceptionGroup`, otherwise the runtime will raise a :exc:`TypeError` From 65e5286c732ae92f1e5fc817ce09a5253a023f16 Mon Sep 17 00:00:00 2001 From: Danny Yang Date: Sat, 15 Jun 2024 06:55:33 -0400 Subject: [PATCH 03/11] Update Doc/reference/compound_stmts.rst Co-authored-by: Jelle Zijlstra --- Doc/reference/compound_stmts.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index f860c701552696..6862d0f69ba5dd 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -248,7 +248,7 @@ it matches any exception. For an :keyword:`!except` clause with an expression, the expression must evaluate to a type or a tuple containing types. Each type must -be a subclass of :exc:`BaseException`, otherwise the runtime will raise a +be a subclass of :exc:`BaseException`; otherwise, the runtime will raise a :exc:`TypeError` when the handler is evaluated. The clause matches the exception if the resulting object is "compatible" with From fd3a79e6fdb257fea93b7d161ac62da81c34adbf Mon Sep 17 00:00:00 2001 From: Danny Yang Date: Sat, 15 Jun 2024 06:55:41 -0400 Subject: [PATCH 04/11] Update Doc/reference/compound_stmts.rst Co-authored-by: Jelle Zijlstra --- Doc/reference/compound_stmts.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index 6862d0f69ba5dd..753507f3e8d676 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -386,7 +386,7 @@ Unlike :keyword:`except` clauses, :keyword:`!except*` clauses must have a matchi expression; ``except*:`` is not valid syntax. When the handler is evaluated, the expression must evaluate to a type or a tuple containing types. Each type must be a subclass of :exc:`BaseException` and must not be a subclass of -:exc:`BaseExceptionGroup`, otherwise the runtime will raise a :exc:`TypeError` +:exc:`BaseExceptionGroup`; otherwise, the runtime will raise a :exc:`TypeError` when the handler is evaluated. It is not possible to mix :keyword:`except` and :keyword:`!except*` From 863b59e0daaed1392ce54568b006966cf3904589 Mon Sep 17 00:00:00 2001 From: Danny Yang Date: Sat, 15 Jun 2024 09:04:52 -0400 Subject: [PATCH 05/11] Update Doc/reference/compound_stmts.rst Co-authored-by: Irit Katriel <1055913+iritkatriel@users.noreply.github.com> --- Doc/reference/compound_stmts.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index 753507f3e8d676..2c8774c4dfa8ee 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -251,7 +251,7 @@ expression must evaluate to a type or a tuple containing types. Each type must be a subclass of :exc:`BaseException`; otherwise, the runtime will raise a :exc:`TypeError` when the handler is evaluated. -The clause matches the exception if the resulting object is "compatible" with +The clause matches an exception if the resulting object is "compatible" with the exception. An object is compatible with an exception if the object is the class or a :term:`non-virtual base class ` of the exception object, or a tuple containing an item that is the class or a non-virtual base From 33733a8ab8c30e18b2ab0057cda6324752078a32 Mon Sep 17 00:00:00 2001 From: Danny Yang Date: Sat, 15 Jun 2024 09:12:49 -0400 Subject: [PATCH 06/11] clarify wording and reduce duplication --- Doc/reference/compound_stmts.rst | 22 ++++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index 2c8774c4dfa8ee..21e3759354ce45 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -248,12 +248,13 @@ it matches any exception. For an :keyword:`!except` clause with an expression, the expression must evaluate to a type or a tuple containing types. Each type must -be a subclass of :exc:`BaseException`; otherwise, the runtime will raise a +be :exc:`BaseException` or a subclass of :exc:`BaseException`; otherwise, the runtime will raise a :exc:`TypeError` when the handler is evaluated. -The clause matches an exception if the resulting object is "compatible" with -the exception. An object is compatible with an exception if the object is the -class or a :term:`non-virtual base class ` of the exception +The clause matches an exception if the resulting object from evaluating the +clause is "compatible" with the exception. An object is compatible with an +exception if the object is the class or a +:term:`non-virtual base class ` of the exception object, or a tuple containing an item that is the class or a non-virtual base class of the exception object. @@ -382,12 +383,13 @@ exception group with an empty message string. :: ... ExceptionGroup('', (BlockingIOError())) -Unlike :keyword:`except` clauses, :keyword:`!except*` clauses must have a matching -expression; ``except*:`` is not valid syntax. When the handler is evaluated, the -expression must evaluate to a type or a tuple containing types. Each type must -be a subclass of :exc:`BaseException` and must not be a subclass of -:exc:`BaseExceptionGroup`; otherwise, the runtime will raise a :exc:`TypeError` -when the handler is evaluated. +Unlike :keyword:`except` clauses, :keyword:`!except*` clauses must have a +matching expression; ``except*:`` is not valid syntax. In addition to the +requirements for matching expressions in :keyword:`except` clauses, the +types in the matching expression of an :keyword:`!except*` clause cannot +be :exc:`BaseExceptionGroup` or a subclass of :exc:`BaseExceptionGroup`; +otherwise, the runtime will raise a :exc:`TypeError` when the handler is +evaluated. It is not possible to mix :keyword:`except` and :keyword:`!except*` in the same :keyword:`try`. From cd988b92842a9485af88cc9f0e174bf2c9e79efb Mon Sep 17 00:00:00 2001 From: Danny Yang Date: Sat, 15 Jun 2024 15:19:03 -0400 Subject: [PATCH 07/11] remove reference to runtime TypeError --- Doc/reference/compound_stmts.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index 21e3759354ce45..66699f194f78f6 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -248,8 +248,7 @@ it matches any exception. For an :keyword:`!except` clause with an expression, the expression must evaluate to a type or a tuple containing types. Each type must -be :exc:`BaseException` or a subclass of :exc:`BaseException`; otherwise, the runtime will raise a -:exc:`TypeError` when the handler is evaluated. +be :exc:`BaseException` or a subclass of :exc:`BaseException`. The clause matches an exception if the resulting object from evaluating the clause is "compatible" with the exception. An object is compatible with an @@ -387,9 +386,7 @@ Unlike :keyword:`except` clauses, :keyword:`!except*` clauses must have a matching expression; ``except*:`` is not valid syntax. In addition to the requirements for matching expressions in :keyword:`except` clauses, the types in the matching expression of an :keyword:`!except*` clause cannot -be :exc:`BaseExceptionGroup` or a subclass of :exc:`BaseExceptionGroup`; -otherwise, the runtime will raise a :exc:`TypeError` when the handler is -evaluated. +be :exc:`BaseExceptionGroup` or a subclass of :exc:`BaseExceptionGroup`. It is not possible to mix :keyword:`except` and :keyword:`!except*` in the same :keyword:`try`. From 5d34d692b127c344cdc389f4fdb03cf937858ea3 Mon Sep 17 00:00:00 2001 From: Danny Yang Date: Mon, 17 Jun 2024 10:58:43 -0400 Subject: [PATCH 08/11] Update Doc/reference/compound_stmts.rst Co-authored-by: Irit Katriel <1055913+iritkatriel@users.noreply.github.com> --- Doc/reference/compound_stmts.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index 66699f194f78f6..42bf51a11073e3 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -247,8 +247,7 @@ An expression-less :keyword:`!except` clause, if present, must be last; it matches any exception. For an :keyword:`!except` clause with an expression, the -expression must evaluate to a type or a tuple containing types. Each type must -be :exc:`BaseException` or a subclass of :exc:`BaseException`. +expression must evaluate to an exception type or a tuple of exception types. The clause matches an exception if the resulting object from evaluating the clause is "compatible" with the exception. An object is compatible with an From 2ccbb8a7bf9fb38ef38670b25abc352237e1b0a6 Mon Sep 17 00:00:00 2001 From: Danny Yang Date: Mon, 17 Jun 2024 10:59:01 -0400 Subject: [PATCH 09/11] Update Doc/reference/compound_stmts.rst Co-authored-by: Irit Katriel <1055913+iritkatriel@users.noreply.github.com> --- Doc/reference/compound_stmts.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index 42bf51a11073e3..ee12f559bead42 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -381,11 +381,9 @@ exception group with an empty message string. :: ... ExceptionGroup('', (BlockingIOError())) -Unlike :keyword:`except` clauses, :keyword:`!except*` clauses must have a -matching expression; ``except*:`` is not valid syntax. In addition to the -requirements for matching expressions in :keyword:`except` clauses, the -types in the matching expression of an :keyword:`!except*` clause cannot -be :exc:`BaseExceptionGroup` or a subclass of :exc:`BaseExceptionGroup`. +An :keyword:`!except*` clause must have a matching expression; it cannot be ``except*:``. +Furthermore, this expression cannot contain exception group types, because that would +have ambiguous semantics. It is not possible to mix :keyword:`except` and :keyword:`!except*` in the same :keyword:`try`. From 2540bcae61d86b6fdfe3a0680a71e09f64b95050 Mon Sep 17 00:00:00 2001 From: Danny Yang Date: Mon, 17 Jun 2024 10:59:15 -0400 Subject: [PATCH 10/11] Update Doc/reference/compound_stmts.rst Co-authored-by: Irit Katriel <1055913+iritkatriel@users.noreply.github.com> --- Doc/reference/compound_stmts.rst | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index ee12f559bead42..b28e7c79f95a9e 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -248,13 +248,9 @@ it matches any exception. For an :keyword:`!except` clause with an expression, the expression must evaluate to an exception type or a tuple of exception types. - -The clause matches an exception if the resulting object from evaluating the -clause is "compatible" with the exception. An object is compatible with an -exception if the object is the class or a -:term:`non-virtual base class ` of the exception -object, or a tuple containing an item that is the class or a non-virtual base -class of the exception object. +The raised exception matches an :keyword:`!except` clause whose expression evaluates +to the class or a :term:`non-virtual base class ` of the exception object, +or it evaluates to a tuple that contains such a class. If no :keyword:`!except` clause matches the exception, the search for an exception handler From e74c87997d439afd807f12d052ca53c29ec74874 Mon Sep 17 00:00:00 2001 From: Danny Yang Date: Wed, 19 Jun 2024 14:33:11 -0400 Subject: [PATCH 11/11] Update Doc/reference/compound_stmts.rst Co-authored-by: Jelle Zijlstra --- Doc/reference/compound_stmts.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/reference/compound_stmts.rst b/Doc/reference/compound_stmts.rst index b28e7c79f95a9e..8181b9759517f6 100644 --- a/Doc/reference/compound_stmts.rst +++ b/Doc/reference/compound_stmts.rst @@ -250,7 +250,7 @@ For an :keyword:`!except` clause with an expression, the expression must evaluate to an exception type or a tuple of exception types. The raised exception matches an :keyword:`!except` clause whose expression evaluates to the class or a :term:`non-virtual base class ` of the exception object, -or it evaluates to a tuple that contains such a class. +or to a tuple that contains such a class. If no :keyword:`!except` clause matches the exception, the search for an exception handler