Skip to content

Commit 2cfe583

Browse files
cocoatomoserhiy-storchaka
cocoatomo
authored and
serhiy-storchaka
committed
[3.5] bpo-19225: Lack of c api exceptions doc (#965)
* Keep the c-api exception doc up-to-date cherry-pick'ed from ec1f5df..e3d6db3 and fix conflict
1 parent 2d8bda5 commit 2cfe583

File tree

2 files changed

+146
-56
lines changed

2 files changed

+146
-56
lines changed

‎Doc/c-api/exceptions.rst‎

Lines changed: 145 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -735,6 +735,60 @@ All standard Python exceptions are available as global variables whose names are
735735
:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
736736
the variables:
737737
738+
.. index::
739+
single: PyExc_BaseException
740+
single: PyExc_Exception
741+
single: PyExc_ArithmeticError
742+
single: PyExc_AssertionError
743+
single: PyExc_AttributeError
744+
single: PyExc_BlockingIOError
745+
single: PyExc_BrokenPipeError
746+
single: PyExc_BufferError
747+
single: PyExc_ChildProcessError
748+
single: PyExc_ConnectionAbortedError
749+
single: PyExc_ConnectionError
750+
single: PyExc_ConnectionRefusedError
751+
single: PyExc_ConnectionResetError
752+
single: PyExc_EOFError
753+
single: PyExc_FileExistsError
754+
single: PyExc_FileNotFoundError
755+
single: PyExc_FloatingPointError
756+
single: PyExc_GeneratorExit
757+
single: PyExc_ImportError
758+
single: PyExc_IndentationError
759+
single: PyExc_IndexError
760+
single: PyExc_InterruptedError
761+
single: PyExc_IsADirectoryError
762+
single: PyExc_KeyError
763+
single: PyExc_KeyboardInterrupt
764+
single: PyExc_LookupError
765+
single: PyExc_MemoryError
766+
single: PyExc_NameError
767+
single: PyExc_NotADirectoryError
768+
single: PyExc_NotImplementedError
769+
single: PyExc_OSError
770+
single: PyExc_OverflowError
771+
single: PyExc_PermissionError
772+
single: PyExc_ProcessLookupError
773+
single: PyExc_RecursionError
774+
single: PyExc_ReferenceError
775+
single: PyExc_RuntimeError
776+
single: PyExc_StopAsyncIteration
777+
single: PyExc_StopIteration
778+
single: PyExc_SyntaxError
779+
single: PyExc_SystemError
780+
single: PyExc_SystemExit
781+
single: PyExc_TabError
782+
single: PyExc_TimeoutError
783+
single: PyExc_TypeError
784+
single: PyExc_UnboundLocalError
785+
single: PyExc_UnicodeDecodeError
786+
single: PyExc_UnicodeEncodeError
787+
single: PyExc_UnicodeError
788+
single: PyExc_UnicodeTranslateError
789+
single: PyExc_ValueError
790+
single: PyExc_ZeroDivisionError
791+
738792
+-----------------------------------------+---------------------------------+----------+
739793
| C Name | Python Name | Notes |
740794
+=========================================+=================================+==========+
@@ -744,8 +798,6 @@ the variables:
744798
+-----------------------------------------+---------------------------------+----------+
745799
| :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) |
746800
+-----------------------------------------+---------------------------------+----------+
747-
| :c:data:`PyExc_LookupError` | :exc:`LookupError` | \(1) |
748-
+-----------------------------------------+---------------------------------+----------+
749801
| :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | |
750802
+-----------------------------------------+---------------------------------+----------+
751803
| :c:data:`PyExc_AttributeError` | :exc:`AttributeError` | |
@@ -754,26 +806,32 @@ the variables:
754806
+-----------------------------------------+---------------------------------+----------+
755807
| :c:data:`PyExc_BrokenPipeError` | :exc:`BrokenPipeError` | |
756808
+-----------------------------------------+---------------------------------+----------+
757-
| :c:data:`PyExc_ChildProcessError` | :exc:`ChildProcessError` | |
809+
| :c:data:`PyExc_BufferError` | :exc:`BufferError` | |
758810
+-----------------------------------------+---------------------------------+----------+
759-
| :c:data:`PyExc_ConnectionError` | :exc:`ConnectionError` | |
811+
| :c:data:`PyExc_ChildProcessError` | :exc:`ChildProcessError` | |
760812
+-----------------------------------------+---------------------------------+----------+
761813
| :c:data:`PyExc_ConnectionAbortedError` | :exc:`ConnectionAbortedError` | |
762814
+-----------------------------------------+---------------------------------+----------+
815+
| :c:data:`PyExc_ConnectionError` | :exc:`ConnectionError` | |
816+
+-----------------------------------------+---------------------------------+----------+
763817
| :c:data:`PyExc_ConnectionRefusedError` | :exc:`ConnectionRefusedError` | |
764818
+-----------------------------------------+---------------------------------+----------+
765819
| :c:data:`PyExc_ConnectionResetError` | :exc:`ConnectionResetError` | |
766820
+-----------------------------------------+---------------------------------+----------+
821+
| :c:data:`PyExc_EOFError` | :exc:`EOFError` | |
822+
+-----------------------------------------+---------------------------------+----------+
767823
| :c:data:`PyExc_FileExistsError` | :exc:`FileExistsError` | |
768824
+-----------------------------------------+---------------------------------+----------+
769825
| :c:data:`PyExc_FileNotFoundError` | :exc:`FileNotFoundError` | |
770826
+-----------------------------------------+---------------------------------+----------+
771-
| :c:data:`PyExc_EOFError` | :exc:`EOFError` | |
772-
+-----------------------------------------+---------------------------------+----------+
773827
| :c:data:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | |
774828
+-----------------------------------------+---------------------------------+----------+
829+
| :c:data:`PyExc_GeneratorExit` | :exc:`GeneratorExit` | |
830+
+-----------------------------------------+---------------------------------+----------+
775831
| :c:data:`PyExc_ImportError` | :exc:`ImportError` | |
776832
+-----------------------------------------+---------------------------------+----------+
833+
| :c:data:`PyExc_IndentationError` | :exc:`IndentationError` | |
834+
+-----------------------------------------+---------------------------------+----------+
777835
| :c:data:`PyExc_IndexError` | :exc:`IndexError` | |
778836
+-----------------------------------------+---------------------------------+----------+
779837
| :c:data:`PyExc_InterruptedError` | :exc:`InterruptedError` | |
@@ -784,6 +842,8 @@ the variables:
784842
+-----------------------------------------+---------------------------------+----------+
785843
| :c:data:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | |
786844
+-----------------------------------------+---------------------------------+----------+
845+
| :c:data:`PyExc_LookupError` | :exc:`LookupError` | \(1) |
846+
+-----------------------------------------+---------------------------------+----------+
787847
| :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | |
788848
+-----------------------------------------+---------------------------------+----------+
789849
| :c:data:`PyExc_NameError` | :exc:`NameError` | |
@@ -806,16 +866,32 @@ the variables:
806866
+-----------------------------------------+---------------------------------+----------+
807867
| :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | |
808868
+-----------------------------------------+---------------------------------+----------+
869+
| :c:data:`PyExc_StopAsyncIteration` | :exc:`StopAsyncIteration` | |
870+
+-----------------------------------------+---------------------------------+----------+
871+
| :c:data:`PyExc_StopIteration` | :exc:`StopIteration` | |
872+
+-----------------------------------------+---------------------------------+----------+
809873
| :c:data:`PyExc_SyntaxError` | :exc:`SyntaxError` | |
810874
+-----------------------------------------+---------------------------------+----------+
811875
| :c:data:`PyExc_SystemError` | :exc:`SystemError` | |
812876
+-----------------------------------------+---------------------------------+----------+
813-
| :c:data:`PyExc_TimeoutError` | :exc:`TimeoutError` | |
814-
+-----------------------------------------+---------------------------------+----------+
815877
| :c:data:`PyExc_SystemExit` | :exc:`SystemExit` | |
816878
+-----------------------------------------+---------------------------------+----------+
879+
| :c:data:`PyExc_TabError` | :exc:`TabError` | |
880+
+-----------------------------------------+---------------------------------+----------+
881+
| :c:data:`PyExc_TimeoutError` | :exc:`TimeoutError` | |
882+
+-----------------------------------------+---------------------------------+----------+
817883
| :c:data:`PyExc_TypeError` | :exc:`TypeError` | |
818884
+-----------------------------------------+---------------------------------+----------+
885+
| :c:data:`PyExc_UnboundLocalError` | :exc:`UnboundLocalError` | |
886+
+-----------------------------------------+---------------------------------+----------+
887+
| :c:data:`PyExc_UnicodeDecodeError` | :exc:`UnicodeDecodeError` | |
888+
+-----------------------------------------+---------------------------------+----------+
889+
| :c:data:`PyExc_UnicodeEncodeError` | :exc:`UnicodeEncodeError` | |
890+
+-----------------------------------------+---------------------------------+----------+
891+
| :c:data:`PyExc_UnicodeError` | :exc:`UnicodeError` | |
892+
+-----------------------------------------+---------------------------------+----------+
893+
| :c:data:`PyExc_UnicodeTranslateError` | :exc:`UnicodeTranslateError` | |
894+
+-----------------------------------------+---------------------------------+----------+
819895
| :c:data:`PyExc_ValueError` | :exc:`ValueError` | |
820896
+-----------------------------------------+---------------------------------+----------+
821897
| :c:data:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | |
@@ -832,11 +908,15 @@ the variables:
832908
and :c:data:`PyExc_TimeoutError` were introduced following :pep:`3151`.
833909
834910
.. versionadded:: 3.5
835-
:c:data:`PyExc_RecursionError`.
836-
911+
:c:data:`PyExc_StopAsyncIteration` and :c:data:`PyExc_RecursionError`.
837912
838913
These are compatibility aliases to :c:data:`PyExc_OSError`:
839914
915+
.. index::
916+
single: PyExc_EnvironmentError
917+
single: PyExc_IOError
918+
single: PyExc_WindowsError
919+
840920
+-------------------------------------+----------+
841921
| C Name | Notes |
842922
+=====================================+==========+
@@ -850,52 +930,6 @@ These are compatibility aliases to :c:data:`PyExc_OSError`:
850930
.. versionchanged:: 3.3
851931
These aliases used to be separate exception types.
852932
853-
854-
.. index::
855-
single: PyExc_BaseException
856-
single: PyExc_Exception
857-
single: PyExc_ArithmeticError
858-
single: PyExc_LookupError
859-
single: PyExc_AssertionError
860-
single: PyExc_AttributeError
861-
single: PyExc_BlockingIOError
862-
single: PyExc_BrokenPipeError
863-
single: PyExc_ConnectionError
864-
single: PyExc_ConnectionAbortedError
865-
single: PyExc_ConnectionRefusedError
866-
single: PyExc_ConnectionResetError
867-
single: PyExc_EOFError
868-
single: PyExc_FileExistsError
869-
single: PyExc_FileNotFoundError
870-
single: PyExc_FloatingPointError
871-
single: PyExc_ImportError
872-
single: PyExc_IndexError
873-
single: PyExc_InterruptedError
874-
single: PyExc_IsADirectoryError
875-
single: PyExc_KeyError
876-
single: PyExc_KeyboardInterrupt
877-
single: PyExc_MemoryError
878-
single: PyExc_NameError
879-
single: PyExc_NotADirectoryError
880-
single: PyExc_NotImplementedError
881-
single: PyExc_OSError
882-
single: PyExc_OverflowError
883-
single: PyExc_PermissionError
884-
single: PyExc_ProcessLookupError
885-
single: PyExc_RecursionError
886-
single: PyExc_ReferenceError
887-
single: PyExc_RuntimeError
888-
single: PyExc_SyntaxError
889-
single: PyExc_SystemError
890-
single: PyExc_SystemExit
891-
single: PyExc_TimeoutError
892-
single: PyExc_TypeError
893-
single: PyExc_ValueError
894-
single: PyExc_ZeroDivisionError
895-
single: PyExc_EnvironmentError
896-
single: PyExc_IOError
897-
single: PyExc_WindowsError
898-
899933
Notes:
900934
901935
(1)
@@ -907,3 +941,58 @@ Notes:
907941
(3)
908942
Only defined on Windows; protect code that uses this by testing that the
909943
preprocessor macro ``MS_WINDOWS`` is defined.
944+
945+
Standard Warnings
946+
=================
947+
948+
All standard Python warning categories are available as global variables whose
949+
names are ``PyExc_`` followed by the Python exception name. These have the type
950+
:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
951+
the variables:
952+
953+
.. index::
954+
single: PyExc_Warning
955+
single: PyExc_BytesWarning
956+
single: PyExc_DepricationWarning
957+
single: PyExc_FutureWarning
958+
single: PyExc_ImportWarning
959+
single: PyExc_PendingDeprecationWarning
960+
single: PyExc_ResourceWarning
961+
single: PyExc_RuntimeWarning
962+
single: PyExc_SyntaxWarning
963+
single: PyExc_UnicodeWarning
964+
single: PyExc_UserWarning
965+
966+
+------------------------------------------+---------------------------------+----------+
967+
| C Name | Python Name | Notes |
968+
+==========================================+=================================+==========+
969+
| :c:data:`PyExc_Warning` | :exc:`Warning` | \(1) |
970+
+------------------------------------------+---------------------------------+----------+
971+
| :c:data:`PyExc_BytesWarning` | :exc:`BytesWarning` | |
972+
+------------------------------------------+---------------------------------+----------+
973+
| :c:data:`PyExc_DeprecationWarning` | :exc:`DeprecationWarning` | |
974+
+------------------------------------------+---------------------------------+----------+
975+
| :c:data:`PyExc_FutureWarning` | :exc:`FutureWarning` | |
976+
+------------------------------------------+---------------------------------+----------+
977+
| :c:data:`PyExc_ImportWarning` | :exc:`ImportWarning` | |
978+
+------------------------------------------+---------------------------------+----------+
979+
| :c:data:`PyExc_PendingDepricationWarning`| :exc:`PendingDeprecationWarning`| |
980+
+------------------------------------------+---------------------------------+----------+
981+
| :c:data:`PyExc_ResourceWarning` | :exc:`ResourceWarning` | |
982+
+------------------------------------------+---------------------------------+----------+
983+
| :c:data:`PyExc_RuntimeWarning` | :exc:`RuntimeWarning` | |
984+
+------------------------------------------+---------------------------------+----------+
985+
| :c:data:`PyExc_SyntaxWarning` | :exc:`SyntaxWarning` | |
986+
+------------------------------------------+---------------------------------+----------+
987+
| :c:data:`PyExc_UnicodeWarning` | :exc:`UnicodeWarning` | |
988+
+------------------------------------------+---------------------------------+----------+
989+
| :c:data:`PyExc_UserWarning` | :exc:`UserWarning` | |
990+
+------------------------------------------+---------------------------------+----------+
991+
992+
.. versionadded:: 3.2
993+
:c:data:`PyExc_ResourceWarning`.
994+
995+
Notes:
996+
997+
(1)
998+
This is a base class for other standard warning categories.

‎Misc/ACKS‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -764,6 +764,7 @@ Jason Killen
764764
Jan Kim
765765
Taek Joo Kim
766766
Sam Kimbrel
767+
Tomohiko Kinebuchi
767768
James King
768769
W. Trevor King
769770
Paul Kippes

0 commit comments

Comments
 (0)