[Python-checkins] bpo-45464: [doc] Explain that subclassing multiple exceptions is fragile (GH-29094) (GH-29105)

[ambv]

https://github.com/python/cpython/commit/427ab124b3e9a54602b6f1d073a8e073159c0b51
commit: 427ab124b3e9a54602b6f1d073a8e073159c0b51
branch: 3.9
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: ambv <lukasz at langa.pl>
date: 2021-10-20T20:50:28+02:00
summary:

bpo-45464: [doc] Explain that subclassing multiple exceptions is fragile (GH-29094) (GH-29105)

Co-authored-by: Pablo Galindo Salgado <Pablogsal at gmail.com>
(cherry picked from commit dff0b713436e286bb1afdd7c6f3093c8e8db16dd)

Co-authored-by: Łukasz Langa <lukasz at langa.pl>

files:
A Misc/NEWS.d/next/Documentation/2021-10-20-16-26-53.bpo-45464.mOISBs.rst
M Doc/library/exceptions.rst

diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 88ce6847bb392..6c21c6b96d3c6 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. 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
 ------------
 
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 0000000000000..1721aa2c2dfc4
--- /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.