Skip to content

Commit 7f85947

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

File tree

2 files changed

+151
-66
lines changed

2 files changed

+151
-66
lines changed

‎Doc/c-api/exceptions.rst

Lines changed: 150 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -525,99 +525,132 @@ All standard Python exceptions are available as global variables whose names are
525525
:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
526526
the variables:
527527
528-
+-------------------------------------+----------------------------+----------+
529-
| C Name | Python Name | Notes |
530-
+=====================================+============================+==========+
531-
| :c:data:`PyExc_BaseException` | :exc:`BaseException` | (1), (4) |
532-
+-------------------------------------+----------------------------+----------+
533-
| :c:data:`PyExc_Exception` | :exc:`Exception` | \(1) |
534-
+-------------------------------------+----------------------------+----------+
535-
| :c:data:`PyExc_StandardError` | :exc:`StandardError` | \(1) |
536-
+-------------------------------------+----------------------------+----------+
537-
| :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) |
538-
+-------------------------------------+----------------------------+----------+
539-
| :c:data:`PyExc_LookupError` | :exc:`LookupError` | \(1) |
540-
+-------------------------------------+----------------------------+----------+
541-
| :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | |
542-
+-------------------------------------+----------------------------+----------+
543-
| :c:data:`PyExc_AttributeError` | :exc:`AttributeError` | |
544-
+-------------------------------------+----------------------------+----------+
545-
| :c:data:`PyExc_EOFError` | :exc:`EOFError` | |
546-
+-------------------------------------+----------------------------+----------+
547-
| :c:data:`PyExc_EnvironmentError` | :exc:`EnvironmentError` | \(1) |
548-
+-------------------------------------+----------------------------+----------+
549-
| :c:data:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | |
550-
+-------------------------------------+----------------------------+----------+
551-
| :c:data:`PyExc_IOError` | :exc:`IOError` | |
552-
+-------------------------------------+----------------------------+----------+
553-
| :c:data:`PyExc_ImportError` | :exc:`ImportError` | |
554-
+-------------------------------------+----------------------------+----------+
555-
| :c:data:`PyExc_IndexError` | :exc:`IndexError` | |
556-
+-------------------------------------+----------------------------+----------+
557-
| :c:data:`PyExc_KeyError` | :exc:`KeyError` | |
558-
+-------------------------------------+----------------------------+----------+
559-
| :c:data:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | |
560-
+-------------------------------------+----------------------------+----------+
561-
| :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | |
562-
+-------------------------------------+----------------------------+----------+
563-
| :c:data:`PyExc_NameError` | :exc:`NameError` | |
564-
+-------------------------------------+----------------------------+----------+
565-
| :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | |
566-
+-------------------------------------+----------------------------+----------+
567-
| :c:data:`PyExc_OSError` | :exc:`OSError` | |
568-
+-------------------------------------+----------------------------+----------+
569-
| :c:data:`PyExc_OverflowError` | :exc:`OverflowError` | |
570-
+-------------------------------------+----------------------------+----------+
571-
| :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) |
572-
+-------------------------------------+----------------------------+----------+
573-
| :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | |
574-
+-------------------------------------+----------------------------+----------+
575-
| :c:data:`PyExc_SyntaxError` | :exc:`SyntaxError` | |
576-
+-------------------------------------+----------------------------+----------+
577-
| :c:data:`PyExc_SystemError` | :exc:`SystemError` | |
578-
+-------------------------------------+----------------------------+----------+
579-
| :c:data:`PyExc_SystemExit` | :exc:`SystemExit` | |
580-
+-------------------------------------+----------------------------+----------+
581-
| :c:data:`PyExc_TypeError` | :exc:`TypeError` | |
582-
+-------------------------------------+----------------------------+----------+
583-
| :c:data:`PyExc_ValueError` | :exc:`ValueError` | |
584-
+-------------------------------------+----------------------------+----------+
585-
| :c:data:`PyExc_WindowsError` | :exc:`WindowsError` | \(3) |
586-
+-------------------------------------+----------------------------+----------+
587-
| :c:data:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | |
588-
+-------------------------------------+----------------------------+----------+
589-
590528
.. index::
591529
single: PyExc_BaseException
592530
single: PyExc_Exception
593531
single: PyExc_StandardError
594532
single: PyExc_ArithmeticError
595-
single: PyExc_LookupError
596533
single: PyExc_AssertionError
597534
single: PyExc_AttributeError
598-
single: PyExc_EOFError
535+
single: PyExc_BufferError
599536
single: PyExc_EnvironmentError
537+
single: PyExc_EOFError
600538
single: PyExc_FloatingPointError
601-
single: PyExc_IOError
539+
single: PyExc_GeneratorExit
602540
single: PyExc_ImportError
541+
single: PyExc_IndentationError
603542
single: PyExc_IndexError
543+
single: PyExc_IOError
604544
single: PyExc_KeyError
605545
single: PyExc_KeyboardInterrupt
546+
single: PyExc_LookupError
606547
single: PyExc_MemoryError
607548
single: PyExc_NameError
608549
single: PyExc_NotImplementedError
609550
single: PyExc_OSError
610551
single: PyExc_OverflowError
611552
single: PyExc_ReferenceError
612553
single: PyExc_RuntimeError
554+
single: PyExc_StopIteration
613555
single: PyExc_SyntaxError
614556
single: PyExc_SystemError
615557
single: PyExc_SystemExit
558+
single: PyExc_TabError
616559
single: PyExc_TypeError
560+
single: PyExc_UnboundLocalError
561+
single: PyExc_UnicodeDecodeError
562+
single: PyExc_UnicodeEncodeError
563+
single: PyExc_UnicodeError
564+
single: PyExc_UnicodeTranslateError
565+
single: PyExc_VMSError
617566
single: PyExc_ValueError
618567
single: PyExc_WindowsError
619568
single: PyExc_ZeroDivisionError
620569
570+
+-----------------------------------------+---------------------------------+----------+
571+
| C Name | Python Name | Notes |
572+
+=========================================+=================================+==========+
573+
| :c:data:`PyExc_BaseException` | :exc:`BaseException` | (1), (4) |
574+
+-----------------------------------------+---------------------------------+----------+
575+
| :c:data:`PyExc_Exception` | :exc:`Exception` | \(1) |
576+
+-----------------------------------------+---------------------------------+----------+
577+
| :c:data:`PyExc_StandardError` | :exc:`StandardError` | \(1) |
578+
+-----------------------------------------+---------------------------------+----------+
579+
| :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) |
580+
+-----------------------------------------+---------------------------------+----------+
581+
| :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | |
582+
+-----------------------------------------+---------------------------------+----------+
583+
| :c:data:`PyExc_AttributeError` | :exc:`AttributeError` | |
584+
+-----------------------------------------+---------------------------------+----------+
585+
| :c:data:`PyExc_BufferError` | :exc:`BufferError` | |
586+
+-----------------------------------------+---------------------------------+----------+
587+
| :c:data:`PyExc_EnvironmentError` | :exc:`EnvironmentError` | \(1) |
588+
+-----------------------------------------+---------------------------------+----------+
589+
| :c:data:`PyExc_EOFError` | :exc:`EOFError` | |
590+
+-----------------------------------------+---------------------------------+----------+
591+
| :c:data:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | |
592+
+-----------------------------------------+---------------------------------+----------+
593+
| :c:data:`PyExc_GeneratorExit` | :exc:`GeneratorExit` | |
594+
+-----------------------------------------+---------------------------------+----------+
595+
| :c:data:`PyExc_ImportError` | :exc:`ImportError` | |
596+
+-----------------------------------------+---------------------------------+----------+
597+
| :c:data:`PyExc_IndentationError` | :exc:`IndentationError` | |
598+
+-----------------------------------------+---------------------------------+----------+
599+
| :c:data:`PyExc_IndexError` | :exc:`IndexError` | |
600+
+-----------------------------------------+---------------------------------+----------+
601+
| :c:data:`PyExc_IOError` | :exc:`IOError` | |
602+
+-----------------------------------------+---------------------------------+----------+
603+
| :c:data:`PyExc_KeyError` | :exc:`KeyError` | |
604+
+-----------------------------------------+---------------------------------+----------+
605+
| :c:data:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | |
606+
+-----------------------------------------+---------------------------------+----------+
607+
| :c:data:`PyExc_LookupError` | :exc:`LookupError` | \(1) |
608+
+-----------------------------------------+---------------------------------+----------+
609+
| :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | |
610+
+-----------------------------------------+---------------------------------+----------+
611+
| :c:data:`PyExc_NameError` | :exc:`NameError` | |
612+
+-----------------------------------------+---------------------------------+----------+
613+
| :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | |
614+
+-----------------------------------------+---------------------------------+----------+
615+
| :c:data:`PyExc_OSError` | :exc:`OSError` | |
616+
+-----------------------------------------+---------------------------------+----------+
617+
| :c:data:`PyExc_OverflowError` | :exc:`OverflowError` | |
618+
+-----------------------------------------+---------------------------------+----------+
619+
| :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) |
620+
+-----------------------------------------+---------------------------------+----------+
621+
| :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | |
622+
+-----------------------------------------+---------------------------------+----------+
623+
| :c:data:`PyExc_StopIteration` | :exc:`StopIteration` | |
624+
+-----------------------------------------+---------------------------------+----------+
625+
| :c:data:`PyExc_SyntaxError` | :exc:`SyntaxError` | |
626+
+-----------------------------------------+---------------------------------+----------+
627+
| :c:data:`PyExc_SystemError` | :exc:`SystemError` | |
628+
+-----------------------------------------+---------------------------------+----------+
629+
| :c:data:`PyExc_SystemExit` | :exc:`SystemExit` | |
630+
+-----------------------------------------+---------------------------------+----------+
631+
| :c:data:`PyExc_TabError` | :exc:`TabError` | |
632+
+-----------------------------------------+---------------------------------+----------+
633+
| :c:data:`PyExc_TypeError` | :exc:`TypeError` | |
634+
+-----------------------------------------+---------------------------------+----------+
635+
| :c:data:`PyExc_UnboundLocalError` | :exc:`UnboundLocalError` | |
636+
+-----------------------------------------+---------------------------------+----------+
637+
| :c:data:`PyExc_UnicodeDecodeError` | :exc:`UnicodeDecodeError` | |
638+
+-----------------------------------------+---------------------------------+----------+
639+
| :c:data:`PyExc_UnicodeEncodeError` | :exc:`UnicodeEncodeError` | |
640+
+-----------------------------------------+---------------------------------+----------+
641+
| :c:data:`PyExc_UnicodeError` | :exc:`UnicodeError` | |
642+
+-----------------------------------------+---------------------------------+----------+
643+
| :c:data:`PyExc_UnicodeTranslateError` | :exc:`UnicodeTranslateError` | |
644+
+-----------------------------------------+---------------------------------+----------+
645+
| :c:data:`PyExc_VMSError` | :exc:`VMSError` | \(5) |
646+
+-----------------------------------------+---------------------------------+----------+
647+
| :c:data:`PyExc_ValueError` | :exc:`ValueError` | |
648+
+-----------------------------------------+---------------------------------+----------+
649+
| :c:data:`PyExc_WindowsError` | :exc:`WindowsError` | \(3) |
650+
+-----------------------------------------+---------------------------------+----------+
651+
| :c:data:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | |
652+
+-----------------------------------------+---------------------------------+----------+
653+
621654
Notes:
622655
623656
(1)
@@ -633,11 +666,62 @@ Notes:
633666
(4)
634667
.. versionadded:: 2.5
635668
669+
(5)
670+
Only defined on VMS; protect code that uses this by testing that the
671+
preprocessor macro ``__VMS`` is defined.
672+
673+
Standard Warnings
674+
=================
675+
676+
All standard Python warning categories are available as global variables whose
677+
names are ``PyExc_`` followed by the Python exception name. These have the type
678+
:c:type:`PyObject\*`; they are all class objects. For completeness, here are all
679+
the variables:
680+
681+
.. index::
682+
single: PyExc_Warning
683+
single: PyExc_BytesWarning
684+
single: PyExc_DepricationWarning
685+
single: PyExc_FutureWarning
686+
single: PyExc_ImportWarning
687+
single: PyExc_PendingDeprecationWarning
688+
single: PyExc_RuntimeWarning
689+
single: PyExc_SyntaxWarning
690+
single: PyExc_UnicodeWarning
691+
single: PyExc_UserWarning
692+
693+
+------------------------------------------+---------------------------------+----------+
694+
| C Name | Python Name | Notes |
695+
+==========================================+=================================+==========+
696+
| :c:data:`PyExc_Warning` | :exc:`Warning` | \(1) |
697+
+------------------------------------------+---------------------------------+----------+
698+
| :c:data:`PyExc_BytesWarning` | :exc:`BytesWarning` | |
699+
+------------------------------------------+---------------------------------+----------+
700+
| :c:data:`PyExc_DeprecationWarning` | :exc:`DeprecationWarning` | |
701+
+------------------------------------------+---------------------------------+----------+
702+
| :c:data:`PyExc_FutureWarning` | :exc:`FutureWarning` | |
703+
+------------------------------------------+---------------------------------+----------+
704+
| :c:data:`PyExc_ImportWarning` | :exc:`ImportWarning` | |
705+
+------------------------------------------+---------------------------------+----------+
706+
| :c:data:`PyExc_PendingDepricationWarning`| :exc:`PendingDeprecationWarning`| |
707+
+------------------------------------------+---------------------------------+----------+
708+
| :c:data:`PyExc_RuntimeWarning` | :exc:`RuntimeWarning` | |
709+
+------------------------------------------+---------------------------------+----------+
710+
| :c:data:`PyExc_SyntaxWarning` | :exc:`SyntaxWarning` | |
711+
+------------------------------------------+---------------------------------+----------+
712+
| :c:data:`PyExc_UnicodeWarning` | :exc:`UnicodeWarning` | |
713+
+------------------------------------------+---------------------------------+----------+
714+
| :c:data:`PyExc_UserWarning` | :exc:`UserWarning` | |
715+
+------------------------------------------+---------------------------------+----------+
716+
717+
Notes:
718+
719+
(1)
720+
This is a base class for other standard warning categories.
636721
637722
String Exceptions
638723
=================
639724
640725
.. versionchanged:: 2.6
641726
All exceptions to be raised or caught must be derived from :exc:`BaseException`.
642727
Trying to raise a string exception now raises :exc:`TypeError`.
643-

‎Misc/ACKS

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -717,6 +717,7 @@ Jason Killen
717717
Jan Kim
718718
Taek Joo Kim
719719
Sam Kimbrel
720+
Tomohiko Kinebuchi
720721
W. Trevor King
721722
Paul Kippes
722723
Steve Kirsch

0 commit comments

Comments
 (0)