include/python3.12/pyerrors.h

0001 #ifndef Py_ERRORS_H
0002 #define Py_ERRORS_H
0003 #ifdef __cplusplus
0004 extern "C" {
0005 #endif
0006
0007 #include <stdarg.h>               // va_list
0008
0009 /* Error handling definitions */
0010
0011 PyAPI_FUNC(void) PyErr_SetNone(PyObject *);
0012 PyAPI_FUNC(void) PyErr_SetObject(PyObject *, PyObject *);
0013 PyAPI_FUNC(void) PyErr_SetString(
0014     PyObject *exception,
0015     const char *string   /* decoded from utf-8 */
0016     );
0017 PyAPI_FUNC(PyObject *) PyErr_Occurred(void);
0018 PyAPI_FUNC(void) PyErr_Clear(void);
0019 PyAPI_FUNC(void) PyErr_Fetch(PyObject **, PyObject **, PyObject **);
0020 PyAPI_FUNC(void) PyErr_Restore(PyObject *, PyObject *, PyObject *);
0021 PyAPI_FUNC(PyObject *) PyErr_GetRaisedException(void);
0022 PyAPI_FUNC(void) PyErr_SetRaisedException(PyObject *);
0023 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030b0000
0024 PyAPI_FUNC(PyObject*) PyErr_GetHandledException(void);
0025 PyAPI_FUNC(void) PyErr_SetHandledException(PyObject *);
0026 #endif
0027 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000
0028 PyAPI_FUNC(void) PyErr_GetExcInfo(PyObject **, PyObject **, PyObject **);
0029 PyAPI_FUNC(void) PyErr_SetExcInfo(PyObject *, PyObject *, PyObject *);
0030 #endif
0031
0032 /* Defined in Python/pylifecycle.c
0033
0034    The Py_FatalError() function is replaced with a macro which logs
0035    automatically the name of the current function, unless the Py_LIMITED_API
0036    macro is defined. */
0037 PyAPI_FUNC(void) _Py_NO_RETURN Py_FatalError(const char *message);
0038
0039 /* Error testing and normalization */
0040 PyAPI_FUNC(int) PyErr_GivenExceptionMatches(PyObject *, PyObject *);
0041 PyAPI_FUNC(int) PyErr_ExceptionMatches(PyObject *);
0042 PyAPI_FUNC(void) PyErr_NormalizeException(PyObject**, PyObject**, PyObject**);
0043
0044 /* Traceback manipulation (PEP 3134) */
0045 PyAPI_FUNC(int) PyException_SetTraceback(PyObject *, PyObject *);
0046 PyAPI_FUNC(PyObject *) PyException_GetTraceback(PyObject *);
0047
0048 /* Cause manipulation (PEP 3134) */
0049 PyAPI_FUNC(PyObject *) PyException_GetCause(PyObject *);
0050 PyAPI_FUNC(void) PyException_SetCause(PyObject *, PyObject *);
0051
0052 /* Context manipulation (PEP 3134) */
0053 PyAPI_FUNC(PyObject *) PyException_GetContext(PyObject *);
0054 PyAPI_FUNC(void) PyException_SetContext(PyObject *, PyObject *);
0055
0056
0057 PyAPI_FUNC(PyObject *) PyException_GetArgs(PyObject *);
0058 PyAPI_FUNC(void) PyException_SetArgs(PyObject *, PyObject *);
0059
0060 /* */
0061
0062 #define PyExceptionClass_Check(x)                                       \
0063     (PyType_Check((x)) &&                                               \
0064      PyType_FastSubclass((PyTypeObject*)(x), Py_TPFLAGS_BASE_EXC_SUBCLASS))
0065
0066 #define PyExceptionInstance_Check(x)                    \
0067     PyType_FastSubclass(Py_TYPE(x), Py_TPFLAGS_BASE_EXC_SUBCLASS)
0068
0069 PyAPI_FUNC(const char *) PyExceptionClass_Name(PyObject *);
0070
0071 #define PyExceptionInstance_Class(x) _PyObject_CAST(Py_TYPE(x))
0072
0073 #define _PyBaseExceptionGroup_Check(x)                   \
0074     PyObject_TypeCheck((x), (PyTypeObject *)PyExc_BaseExceptionGroup)
0075
0076 /* Predefined exceptions */
0077
0078 PyAPI_DATA(PyObject *) PyExc_BaseException;
0079 PyAPI_DATA(PyObject *) PyExc_Exception;
0080 PyAPI_DATA(PyObject *) PyExc_BaseExceptionGroup;
0081 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03050000
0082 PyAPI_DATA(PyObject *) PyExc_StopAsyncIteration;
0083 #endif
0084 PyAPI_DATA(PyObject *) PyExc_StopIteration;
0085 PyAPI_DATA(PyObject *) PyExc_GeneratorExit;
0086 PyAPI_DATA(PyObject *) PyExc_ArithmeticError;
0087 PyAPI_DATA(PyObject *) PyExc_LookupError;
0088
0089 PyAPI_DATA(PyObject *) PyExc_AssertionError;
0090 PyAPI_DATA(PyObject *) PyExc_AttributeError;
0091 PyAPI_DATA(PyObject *) PyExc_BufferError;
0092 PyAPI_DATA(PyObject *) PyExc_EOFError;
0093 PyAPI_DATA(PyObject *) PyExc_FloatingPointError;
0094 PyAPI_DATA(PyObject *) PyExc_OSError;
0095 PyAPI_DATA(PyObject *) PyExc_ImportError;
0096 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03060000
0097 PyAPI_DATA(PyObject *) PyExc_ModuleNotFoundError;
0098 #endif
0099 PyAPI_DATA(PyObject *) PyExc_IndexError;
0100 PyAPI_DATA(PyObject *) PyExc_KeyError;
0101 PyAPI_DATA(PyObject *) PyExc_KeyboardInterrupt;
0102 PyAPI_DATA(PyObject *) PyExc_MemoryError;
0103 PyAPI_DATA(PyObject *) PyExc_NameError;
0104 PyAPI_DATA(PyObject *) PyExc_OverflowError;
0105 PyAPI_DATA(PyObject *) PyExc_RuntimeError;
0106 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03050000
0107 PyAPI_DATA(PyObject *) PyExc_RecursionError;
0108 #endif
0109 PyAPI_DATA(PyObject *) PyExc_NotImplementedError;
0110 PyAPI_DATA(PyObject *) PyExc_SyntaxError;
0111 PyAPI_DATA(PyObject *) PyExc_IndentationError;
0112 PyAPI_DATA(PyObject *) PyExc_TabError;
0113 PyAPI_DATA(PyObject *) PyExc_ReferenceError;
0114 PyAPI_DATA(PyObject *) PyExc_SystemError;
0115 PyAPI_DATA(PyObject *) PyExc_SystemExit;
0116 PyAPI_DATA(PyObject *) PyExc_TypeError;
0117 PyAPI_DATA(PyObject *) PyExc_UnboundLocalError;
0118 PyAPI_DATA(PyObject *) PyExc_UnicodeError;
0119 PyAPI_DATA(PyObject *) PyExc_UnicodeEncodeError;
0120 PyAPI_DATA(PyObject *) PyExc_UnicodeDecodeError;
0121 PyAPI_DATA(PyObject *) PyExc_UnicodeTranslateError;
0122 PyAPI_DATA(PyObject *) PyExc_ValueError;
0123 PyAPI_DATA(PyObject *) PyExc_ZeroDivisionError;
0124
0125 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000
0126 PyAPI_DATA(PyObject *) PyExc_BlockingIOError;
0127 PyAPI_DATA(PyObject *) PyExc_BrokenPipeError;
0128 PyAPI_DATA(PyObject *) PyExc_ChildProcessError;
0129 PyAPI_DATA(PyObject *) PyExc_ConnectionError;
0130 PyAPI_DATA(PyObject *) PyExc_ConnectionAbortedError;
0131 PyAPI_DATA(PyObject *) PyExc_ConnectionRefusedError;
0132 PyAPI_DATA(PyObject *) PyExc_ConnectionResetError;
0133 PyAPI_DATA(PyObject *) PyExc_FileExistsError;
0134 PyAPI_DATA(PyObject *) PyExc_FileNotFoundError;
0135 PyAPI_DATA(PyObject *) PyExc_InterruptedError;
0136 PyAPI_DATA(PyObject *) PyExc_IsADirectoryError;
0137 PyAPI_DATA(PyObject *) PyExc_NotADirectoryError;
0138 PyAPI_DATA(PyObject *) PyExc_PermissionError;
0139 PyAPI_DATA(PyObject *) PyExc_ProcessLookupError;
0140 PyAPI_DATA(PyObject *) PyExc_TimeoutError;
0141 #endif
0142
0143
0144 /* Compatibility aliases */
0145 PyAPI_DATA(PyObject *) PyExc_EnvironmentError;
0146 PyAPI_DATA(PyObject *) PyExc_IOError;
0147 #ifdef MS_WINDOWS
0148 PyAPI_DATA(PyObject *) PyExc_WindowsError;
0149 #endif
0150
0151 /* Predefined warning categories */
0152 PyAPI_DATA(PyObject *) PyExc_Warning;
0153 PyAPI_DATA(PyObject *) PyExc_UserWarning;
0154 PyAPI_DATA(PyObject *) PyExc_DeprecationWarning;
0155 PyAPI_DATA(PyObject *) PyExc_PendingDeprecationWarning;
0156 PyAPI_DATA(PyObject *) PyExc_SyntaxWarning;
0157 PyAPI_DATA(PyObject *) PyExc_RuntimeWarning;
0158 PyAPI_DATA(PyObject *) PyExc_FutureWarning;
0159 PyAPI_DATA(PyObject *) PyExc_ImportWarning;
0160 PyAPI_DATA(PyObject *) PyExc_UnicodeWarning;
0161 PyAPI_DATA(PyObject *) PyExc_BytesWarning;
0162 PyAPI_DATA(PyObject *) PyExc_EncodingWarning;
0163 PyAPI_DATA(PyObject *) PyExc_ResourceWarning;
0164
0165
0166 /* Convenience functions */
0167
0168 PyAPI_FUNC(int) PyErr_BadArgument(void);
0169 PyAPI_FUNC(PyObject *) PyErr_NoMemory(void);
0170 PyAPI_FUNC(PyObject *) PyErr_SetFromErrno(PyObject *);
0171 PyAPI_FUNC(PyObject *) PyErr_SetFromErrnoWithFilenameObject(
0172     PyObject *, PyObject *);
0173 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03040000
0174 PyAPI_FUNC(PyObject *) PyErr_SetFromErrnoWithFilenameObjects(
0175     PyObject *, PyObject *, PyObject *);
0176 #endif
0177 PyAPI_FUNC(PyObject *) PyErr_SetFromErrnoWithFilename(
0178     PyObject *exc,
0179     const char *filename   /* decoded from the filesystem encoding */
0180     );
0181
0182 PyAPI_FUNC(PyObject *) PyErr_Format(
0183     PyObject *exception,
0184     const char *format,   /* ASCII-encoded string  */
0185     ...
0186     );
0187 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03050000
0188 PyAPI_FUNC(PyObject *) PyErr_FormatV(
0189     PyObject *exception,
0190     const char *format,
0191     va_list vargs);
0192 #endif
0193
0194 #ifdef MS_WINDOWS
0195 PyAPI_FUNC(PyObject *) PyErr_SetFromWindowsErrWithFilename(
0196     int ierr,
0197     const char *filename        /* decoded from the filesystem encoding */
0198     );
0199 PyAPI_FUNC(PyObject *) PyErr_SetFromWindowsErr(int);
0200 PyAPI_FUNC(PyObject *) PyErr_SetExcFromWindowsErrWithFilenameObject(
0201     PyObject *,int, PyObject *);
0202 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03040000
0203 PyAPI_FUNC(PyObject *) PyErr_SetExcFromWindowsErrWithFilenameObjects(
0204     PyObject *,int, PyObject *, PyObject *);
0205 #endif
0206 PyAPI_FUNC(PyObject *) PyErr_SetExcFromWindowsErrWithFilename(
0207     PyObject *exc,
0208     int ierr,
0209     const char *filename        /* decoded from the filesystem encoding */
0210     );
0211 PyAPI_FUNC(PyObject *) PyErr_SetExcFromWindowsErr(PyObject *, int);
0212 #endif /* MS_WINDOWS */
0213
0214 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03060000
0215 PyAPI_FUNC(PyObject *) PyErr_SetImportErrorSubclass(PyObject *, PyObject *,
0216     PyObject *, PyObject *);
0217 #endif
0218 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x03030000
0219 PyAPI_FUNC(PyObject *) PyErr_SetImportError(PyObject *, PyObject *,
0220     PyObject *);
0221 #endif
0222
0223 /* Export the old function so that the existing API remains available: */
0224 PyAPI_FUNC(void) PyErr_BadInternalCall(void);
0225 PyAPI_FUNC(void) _PyErr_BadInternalCall(const char *filename, int lineno);
0226 /* Mask the old API with a call to the new API for code compiled under
0227    Python 2.0: */
0228 #define PyErr_BadInternalCall() _PyErr_BadInternalCall(__FILE__, __LINE__)
0229
0230 /* Function to create a new exception */
0231 PyAPI_FUNC(PyObject *) PyErr_NewException(
0232     const char *name, PyObject *base, PyObject *dict);
0233 PyAPI_FUNC(PyObject *) PyErr_NewExceptionWithDoc(
0234     const char *name, const char *doc, PyObject *base, PyObject *dict);
0235 PyAPI_FUNC(void) PyErr_WriteUnraisable(PyObject *);
0236
0237
0238 /* In signalmodule.c */
0239 PyAPI_FUNC(int) PyErr_CheckSignals(void);
0240 PyAPI_FUNC(void) PyErr_SetInterrupt(void);
0241 #if !defined(Py_LIMITED_API) || Py_LIMITED_API+0 >= 0x030A0000
0242 PyAPI_FUNC(int) PyErr_SetInterruptEx(int signum);
0243 #endif
0244
0245 /* Support for adding program text to SyntaxErrors */
0246 PyAPI_FUNC(void) PyErr_SyntaxLocation(
0247     const char *filename,       /* decoded from the filesystem encoding */
0248     int lineno);
0249 PyAPI_FUNC(void) PyErr_SyntaxLocationEx(
0250     const char *filename,       /* decoded from the filesystem encoding */
0251     int lineno,
0252     int col_offset);
0253 PyAPI_FUNC(PyObject *) PyErr_ProgramText(
0254     const char *filename,       /* decoded from the filesystem encoding */
0255     int lineno);
0256
0257 /* The following functions are used to create and modify unicode
0258    exceptions from C */
0259
0260 /* create a UnicodeDecodeError object */
0261 PyAPI_FUNC(PyObject *) PyUnicodeDecodeError_Create(
0262     const char *encoding,       /* UTF-8 encoded string */
0263     const char *object,
0264     Py_ssize_t length,
0265     Py_ssize_t start,
0266     Py_ssize_t end,
0267     const char *reason          /* UTF-8 encoded string */
0268     );
0269
0270 /* get the encoding attribute */
0271 PyAPI_FUNC(PyObject *) PyUnicodeEncodeError_GetEncoding(PyObject *);
0272 PyAPI_FUNC(PyObject *) PyUnicodeDecodeError_GetEncoding(PyObject *);
0273
0274 /* get the object attribute */
0275 PyAPI_FUNC(PyObject *) PyUnicodeEncodeError_GetObject(PyObject *);
0276 PyAPI_FUNC(PyObject *) PyUnicodeDecodeError_GetObject(PyObject *);
0277 PyAPI_FUNC(PyObject *) PyUnicodeTranslateError_GetObject(PyObject *);
0278
0279 /* get the value of the start attribute (the int * may not be NULL)
0280    return 0 on success, -1 on failure */
0281 PyAPI_FUNC(int) PyUnicodeEncodeError_GetStart(PyObject *, Py_ssize_t *);
0282 PyAPI_FUNC(int) PyUnicodeDecodeError_GetStart(PyObject *, Py_ssize_t *);
0283 PyAPI_FUNC(int) PyUnicodeTranslateError_GetStart(PyObject *, Py_ssize_t *);
0284
0285 /* assign a new value to the start attribute
0286    return 0 on success, -1 on failure */
0287 PyAPI_FUNC(int) PyUnicodeEncodeError_SetStart(PyObject *, Py_ssize_t);
0288 PyAPI_FUNC(int) PyUnicodeDecodeError_SetStart(PyObject *, Py_ssize_t);
0289 PyAPI_FUNC(int) PyUnicodeTranslateError_SetStart(PyObject *, Py_ssize_t);
0290
0291 /* get the value of the end attribute (the int *may not be NULL)
0292  return 0 on success, -1 on failure */
0293 PyAPI_FUNC(int) PyUnicodeEncodeError_GetEnd(PyObject *, Py_ssize_t *);
0294 PyAPI_FUNC(int) PyUnicodeDecodeError_GetEnd(PyObject *, Py_ssize_t *);
0295 PyAPI_FUNC(int) PyUnicodeTranslateError_GetEnd(PyObject *, Py_ssize_t *);
0296
0297 /* assign a new value to the end attribute
0298    return 0 on success, -1 on failure */
0299 PyAPI_FUNC(int) PyUnicodeEncodeError_SetEnd(PyObject *, Py_ssize_t);
0300 PyAPI_FUNC(int) PyUnicodeDecodeError_SetEnd(PyObject *, Py_ssize_t);
0301 PyAPI_FUNC(int) PyUnicodeTranslateError_SetEnd(PyObject *, Py_ssize_t);
0302
0303 /* get the value of the reason attribute */
0304 PyAPI_FUNC(PyObject *) PyUnicodeEncodeError_GetReason(PyObject *);
0305 PyAPI_FUNC(PyObject *) PyUnicodeDecodeError_GetReason(PyObject *);
0306 PyAPI_FUNC(PyObject *) PyUnicodeTranslateError_GetReason(PyObject *);
0307
0308 /* assign a new value to the reason attribute
0309    return 0 on success, -1 on failure */
0310 PyAPI_FUNC(int) PyUnicodeEncodeError_SetReason(
0311     PyObject *exc,
0312     const char *reason          /* UTF-8 encoded string */
0313     );
0314 PyAPI_FUNC(int) PyUnicodeDecodeError_SetReason(
0315     PyObject *exc,
0316     const char *reason          /* UTF-8 encoded string */
0317     );
0318 PyAPI_FUNC(int) PyUnicodeTranslateError_SetReason(
0319     PyObject *exc,
0320     const char *reason          /* UTF-8 encoded string */
0321     );
0322
0323 PyAPI_FUNC(int) PyOS_snprintf(char *str, size_t size, const char  *format, ...)
0324                         Py_GCC_ATTRIBUTE((format(printf, 3, 4)));
0325 PyAPI_FUNC(int) PyOS_vsnprintf(char *str, size_t size, const char  *format, va_list va)
0326                         Py_GCC_ATTRIBUTE((format(printf, 3, 0)));
0327
0328 #ifndef Py_LIMITED_API
0329 #  define Py_CPYTHON_ERRORS_H
0330 #  include "cpython/pyerrors.h"
0331 #  undef Py_CPYTHON_ERRORS_H
0332 #endif
0333
0334 #ifdef __cplusplus
0335 }
0336 #endif
0337 #endif /* !Py_ERRORS_H */