From 9cf6de2182da7c248c0a6abb32f7a3e9328f6f2e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Langa?= Date: Wed, 20 Oct 2021 16:19:13 +0200 Subject: [PATCH 1/4] bpo-45464: [doc] Explain that subclassing multiple exceptions is fragile --- Doc/library/exceptions.rst | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index b665c6079ab0a3..9dff68ccbd8cc8 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -34,6 +34,10 @@ class or one of its subclasses, and not from :exc:`BaseException`. More information on defining exceptions is available in the Python Tutorial under :ref:`tut-userexceptions`. + +Exception context +----------------- + When raising (or re-raising) an exception in an :keyword:`except` or :keyword:`finally` clause :attr:`__context__` is automatically set to the last exception caught; if the @@ -67,6 +71,25 @@ exceptions so that the final line of the traceback always shows the last exception that was raised. +Inheriting from built-in exceptions +----------------------------------- + +User code can create subclasses that inherit from an exception type. +It's recommended to only subclass one exception type at a time to avoid +any possible conflicts between how the bases handle the ``args`` +attribute, as well as due to possible memory layout incompatibilities. + +.. impl-detail:: + + Most built-in exceptions are implemented in C for efficiency, see: + :source:`Objects/exceptions.c`. Some have custom memory layouts + which makes it impossible to create a subclass that inherits from + multiple exception types. Memory layout of a type is an implementation + detail and might change between Python versions, leading to new + conflicts in the future. Therefore, it's recommended to avoid + subclassing multiple exception types altogether. + + Base classes ------------ From 673e69a5c965f4f06322b9afba60400524e6f53d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Langa?= Date: Wed, 20 Oct 2021 16:26:57 +0200 Subject: [PATCH 2/4] Add Blurb --- .../Documentation/2021-10-20-16-26-53.bpo-45464.mOISBs.rst | 4 ++++ 1 file changed, 4 insertions(+) create mode 100644 Misc/NEWS.d/next/Documentation/2021-10-20-16-26-53.bpo-45464.mOISBs.rst diff --git a/Misc/NEWS.d/next/Documentation/2021-10-20-16-26-53.bpo-45464.mOISBs.rst b/Misc/NEWS.d/next/Documentation/2021-10-20-16-26-53.bpo-45464.mOISBs.rst new file mode 100644 index 00000000000000..6ae4a531fc609e --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2021-10-20-16-26-53.bpo-45464.mOISBs.rst @@ -0,0 +1,4 @@ +Mention in the documentation of :ref:`Built-in Exceptions +<_bltin-exceptions>` that inheriting from multiple exception types in a +single subclass is not recommended due to possible memory layout +incompatibility. From c5df6bbb4e4b4c06f66763d524b8ea73740a4f0f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Langa?= Date: Wed, 20 Oct 2021 16:27:58 +0200 Subject: [PATCH 3/4] Minor grammar fix Co-authored-by: Pablo Galindo Salgado --- Doc/library/exceptions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index 9dff68ccbd8cc8..8fa82a98a199d6 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -84,7 +84,7 @@ attribute, as well as due to possible memory layout incompatibilities. Most built-in exceptions are implemented in C for efficiency, see: :source:`Objects/exceptions.c`. Some have custom memory layouts which makes it impossible to create a subclass that inherits from - multiple exception types. Memory layout of a type is an implementation + multiple exception types. The memory layout of a type is an implementation detail and might change between Python versions, leading to new conflicts in the future. Therefore, it's recommended to avoid subclassing multiple exception types altogether. From 4bf8d21a19f9819f69a1b250c61d8a04e93268f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Langa?= Date: Wed, 20 Oct 2021 16:42:33 +0200 Subject: [PATCH 4/4] goddammit rst --- .../next/Documentation/2021-10-20-16-26-53.bpo-45464.mOISBs.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Misc/NEWS.d/next/Documentation/2021-10-20-16-26-53.bpo-45464.mOISBs.rst b/Misc/NEWS.d/next/Documentation/2021-10-20-16-26-53.bpo-45464.mOISBs.rst index 6ae4a531fc609e..1721aa2c2dfc4e 100644 --- a/Misc/NEWS.d/next/Documentation/2021-10-20-16-26-53.bpo-45464.mOISBs.rst +++ b/Misc/NEWS.d/next/Documentation/2021-10-20-16-26-53.bpo-45464.mOISBs.rst @@ -1,4 +1,4 @@ Mention in the documentation of :ref:`Built-in Exceptions -<_bltin-exceptions>` that inheriting from multiple exception types in a +` that inheriting from multiple exception types in a single subclass is not recommended due to possible memory layout incompatibility.