Skip to content

[2.7] bpo-19225: Lack of c api exceptions doc #964

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 8, 2017
Merged

[2.7] bpo-19225: Lack of c api exceptions doc #964

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
88f5f33
Keep the c-api exception doc up-to-date
cocoatomo Mar 29, 2017
fb3c1e8
Adjust the cherry-pick'ed patch for 2.7
cocoatomo Apr 2, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
216 changes: 150 additions & 66 deletions Doc/c-api/exceptions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -525,99 +525,132 @@ All standard Python exceptions are available as global variables whose names are
:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
the variables:

+-------------------------------------+----------------------------+----------+
| C Name | Python Name | Notes |
+=====================================+============================+==========+
| :c:data:`PyExc_BaseException` | :exc:`BaseException` | (1), (4) |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_Exception` | :exc:`Exception` | \(1) |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_StandardError` | :exc:`StandardError` | \(1) |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_LookupError` | :exc:`LookupError` | \(1) |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_AttributeError` | :exc:`AttributeError` | |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_EOFError` | :exc:`EOFError` | |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_EnvironmentError` | :exc:`EnvironmentError` | \(1) |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_IOError` | :exc:`IOError` | |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_ImportError` | :exc:`ImportError` | |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_IndexError` | :exc:`IndexError` | |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_KeyError` | :exc:`KeyError` | |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_NameError` | :exc:`NameError` | |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_OSError` | :exc:`OSError` | |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_OverflowError` | :exc:`OverflowError` | |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_SyntaxError` | :exc:`SyntaxError` | |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_SystemError` | :exc:`SystemError` | |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_SystemExit` | :exc:`SystemExit` | |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_TypeError` | :exc:`TypeError` | |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_ValueError` | :exc:`ValueError` | |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_WindowsError` | :exc:`WindowsError` | \(3) |
+-------------------------------------+----------------------------+----------+
| :c:data:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | |
+-------------------------------------+----------------------------+----------+

.. index::
single: PyExc_BaseException
single: PyExc_Exception
single: PyExc_StandardError
single: PyExc_ArithmeticError
single: PyExc_LookupError
single: PyExc_AssertionError
single: PyExc_AttributeError
single: PyExc_EOFError
single: PyExc_BufferError
single: PyExc_EnvironmentError
single: PyExc_EOFError
single: PyExc_FloatingPointError
single: PyExc_IOError
single: PyExc_GeneratorExit
single: PyExc_ImportError
single: PyExc_IndentationError
single: PyExc_IndexError
single: PyExc_IOError
single: PyExc_KeyError
single: PyExc_KeyboardInterrupt
single: PyExc_LookupError
single: PyExc_MemoryError
single: PyExc_NameError
single: PyExc_NotImplementedError
single: PyExc_OSError
single: PyExc_OverflowError
single: PyExc_ReferenceError
single: PyExc_RuntimeError
single: PyExc_StopIteration
single: PyExc_SyntaxError
single: PyExc_SystemError
single: PyExc_SystemExit
single: PyExc_TabError
single: PyExc_TypeError
single: PyExc_UnboundLocalError
single: PyExc_UnicodeDecodeError
single: PyExc_UnicodeEncodeError
single: PyExc_UnicodeError
single: PyExc_UnicodeTranslateError
single: PyExc_VMSError
single: PyExc_ValueError
single: PyExc_WindowsError
single: PyExc_ZeroDivisionError

+-----------------------------------------+---------------------------------+----------+
| C Name | Python Name | Notes |
+=========================================+=================================+==========+
| :c:data:`PyExc_BaseException` | :exc:`BaseException` | (1), (4) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_Exception` | :exc:`Exception` | \(1) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_StandardError` | :exc:`StandardError` | \(1) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_AttributeError` | :exc:`AttributeError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_BufferError` | :exc:`BufferError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_EnvironmentError` | :exc:`EnvironmentError` | \(1) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_EOFError` | :exc:`EOFError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_GeneratorExit` | :exc:`GeneratorExit` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_ImportError` | :exc:`ImportError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_IndentationError` | :exc:`IndentationError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_IndexError` | :exc:`IndexError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_IOError` | :exc:`IOError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_KeyError` | :exc:`KeyError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_LookupError` | :exc:`LookupError` | \(1) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_NameError` | :exc:`NameError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_OSError` | :exc:`OSError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_OverflowError` | :exc:`OverflowError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_StopIteration` | :exc:`StopIteration` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_SyntaxError` | :exc:`SyntaxError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_SystemError` | :exc:`SystemError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_SystemExit` | :exc:`SystemExit` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_TabError` | :exc:`TabError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_TypeError` | :exc:`TypeError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_UnboundLocalError` | :exc:`UnboundLocalError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_UnicodeDecodeError` | :exc:`UnicodeDecodeError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_UnicodeEncodeError` | :exc:`UnicodeEncodeError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_UnicodeError` | :exc:`UnicodeError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_UnicodeTranslateError` | :exc:`UnicodeTranslateError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_VMSError` | :exc:`VMSError` | \(5) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_ValueError` | :exc:`ValueError` | |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_WindowsError` | :exc:`WindowsError` | \(3) |
+-----------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | |
+-----------------------------------------+---------------------------------+----------+

Notes:

(1)
Expand All @@ -633,11 +666,62 @@ Notes:
(4)
.. versionadded:: 2.5

(5)
Only defined on VMS; protect code that uses this by testing that the
preprocessor macro ``__VMS`` is defined.

Standard Warnings
=================

All standard Python warning categories are available as global variables whose
names are ``PyExc_`` followed by the Python exception name. These have the type
:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
the variables:

.. index::
single: PyExc_Warning
single: PyExc_BytesWarning
single: PyExc_DepricationWarning
single: PyExc_FutureWarning
single: PyExc_ImportWarning
single: PyExc_PendingDeprecationWarning
single: PyExc_RuntimeWarning
single: PyExc_SyntaxWarning
single: PyExc_UnicodeWarning
single: PyExc_UserWarning

+------------------------------------------+---------------------------------+----------+
| C Name | Python Name | Notes |
+==========================================+=================================+==========+
| :c:data:`PyExc_Warning` | :exc:`Warning` | \(1) |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_BytesWarning` | :exc:`BytesWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_DeprecationWarning` | :exc:`DeprecationWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_FutureWarning` | :exc:`FutureWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_ImportWarning` | :exc:`ImportWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_PendingDepricationWarning`| :exc:`PendingDeprecationWarning`| |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_RuntimeWarning` | :exc:`RuntimeWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_SyntaxWarning` | :exc:`SyntaxWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_UnicodeWarning` | :exc:`UnicodeWarning` | |
+------------------------------------------+---------------------------------+----------+
| :c:data:`PyExc_UserWarning` | :exc:`UserWarning` | |
+------------------------------------------+---------------------------------+----------+

Notes:

(1)
This is a base class for other standard warning categories.

String Exceptions
=================

.. versionchanged:: 2.6
All exceptions to be raised or caught must be derived from :exc:`BaseException`.
Trying to raise a string exception now raises :exc:`TypeError`.

1 change: 1 addition & 0 deletions Misc/ACKS
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -717,6 +717,7 @@ Jason Killen
Jan Kim
Taek Joo Kim
Sam Kimbrel
Tomohiko Kinebuchi
W. Trevor King
Paul Kippes
Steve Kirsch
Expand Down