diff options
| author | Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> | 2021-10-20 11:50:28 -0700 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-10-20 20:50:28 +0200 |
| commit | 427ab124b3e9a54602b6f1d073a8e073159c0b51 (patch) | |
| tree | 17dca5c29921a622dae325a6df3ea3e3b1e91e99 | |
| parent | 1249ce7c6c0ac7a99a72e6e7b8b10dd64158c386 (diff) | |
| download | cpython-git-427ab124b3e9a54602b6f1d073a8e073159c0b51.tar.gz | |
bpo-45464: [doc] Explain that subclassing multiple exceptions is fragile (GH-29094) (GH-29105)
Co-authored-by: Pablo Galindo Salgado <Pablogsal@gmail.com>
(cherry picked from commit dff0b713436e286bb1afdd7c6f3093c8e8db16dd)
Co-authored-by: Łukasz Langa <lukasz@langa.pl>
| -rw-r--r-- | Doc/library/exceptions.rst | 23 | ||||
| -rw-r--r-- | Misc/NEWS.d/next/Documentation/2021-10-20-16-26-53.bpo-45464.mOISBs.rst | 4 |
2 files changed, 27 insertions, 0 deletions
diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index 88ce6847bb..6c21c6b96d 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 0000000000..1721aa2c2d --- /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. |