bpo-45464: [doc] Explain that subclassing multiple exceptions is fragile (GH-29094) (GH-29104)
Co-authored-by: Pablo Galindo Salgado <Pablogsal@gmail.com>
(cherry picked from commit dff0b713436e286bb1afdd7c6f3093c8e8db16dd)
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 1a883ba..f8a692e 100644
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -34,6 +34,10 @@
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 @@
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. 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.
+
+
Base classes
------------