مدیریت استثنا¶

توابعی که در این فصل توضیح داده شده‌اند به شما امکان می‌دهند تا استثناهای پایتون را مدیریت و برپا کنید. درک برخی از مبانی مدیریت استثنا در پایتون اهمیت دارد. این سازوکار تا حدی مانند متغیر errno در POSIX کار می‌کند: یک نشانگر سراسری (به ازای هر نخ) برای آخرین خطای رخ‌داده وجود دارد. بیشتر توابع C API این نشانگر را در صورت موفقیت پاک نمی‌کنند، اما در صورت شکست آن را برای نشان دادن علت خطا تنظیم می‌کنند. بیشتر توابع C API همچنین یک نشانگر خطا برمی‌گردانند؛ معمولاً NULL اگر قرار باشد اشاره‌گر برگردانند، یا -1 اگر عدد صحیح برگردانند (استثنا: توابع PyArg_* برای موفقیت 1 و برای شکست 0 برمی‌گردانند).

به‌طور مشخص، نشانگر خطا از سه اشاره‌گر شیء تشکیل شده است: نوع استثنا، مقدار استثنا، و شیء ردگیری. هر یک از این اشاره‌گرها می‌تواند در صورت تنظیم‌نشده بودن NULL باشد (هرچند برخی ترکیب‌ها ممنوع هستند؛ برای مثال، اگر نوع استثنا NULL باشد، نمی‌توانید ردگیری‌ای داشته باشید که NULL نباشد).

وقتی تابعی باید به این دلیل شکست بخورد که تابعی که آن را فراخوانی کرده شکست خورده است، معمولاً نشانگر خطا را تنظیم نمی‌کند؛ تابع فراخوانی‌شده قبلاً آن را تنظیم کرده است. مسئولیت این تابع است که یا خطا را مدیریت کند و استثنا را پاک کند، یا پس از پاک‌سازی هر منبعی که در اختیار دارد (مانند ارجاع‌های شیء یا تخصیص‌های حافظه) بازگشت کند؛ اگر برای مدیریت خطا آماده نباشد، نباید به‌صورت عادی ادامه دهد. در صورت بازگشت به‌دلیل خطا، مهم است به فراخواننده نشان داده شود که خطایی تنظیم شده است. اگر خطا مدیریت نشود یا به‌دقت بالا برده نشود، ممکن است فراخوانی‌های بعدی در Python/C API آن‌گونه که در نظر گرفته شده است رفتار نکنند و به شیوه‌های مرموز شکست بخورند.

توجه

نشانگر خطا نتیجه‌ی sys.exc_info() نیست. اولی به استثنایی مربوط است که هنوز گرفته‌نشده است (و بنابراین همچنان در حال انتشار است)، در حالی که دومی استثنا را پس از گرفته‌شدن آن برمی‌گرداند (و بنابراین انتشار آن متوقف شده است).

چاپ و پاک کردن¶

void PyErr_Clear()¶: قسمتی از ABI پایدار.
نشانگر خطا را پاک می‌کند. اگر نشانگر خطا تنظیم نشده باشد، هیچ اثری ندارد.

void PyErr_PrintEx(int set_sys_last_vars)¶

قسمتی از ABI پایدار.

یک ردگیری استاندارد در sys.stderr چاپ می‌کند و نشانگر خطا را پاک می‌کند. مگر اینکه خطا یک SystemExit باشد، در این حالت هیچ ردگیری‌ای چاپ نمی‌شود و فرایند پایتون با کد خطای تعیین‌شده توسط نمونه‌ی SystemExit خارج خواهد شد.

این تابع را فقط زمانی فراخوانی کنید که نشانگر خطا تنظیم شده باشد. در غیر این صورت، باعث خطای مهلک خواهد شد!

اگر set_sys_last_vars ناصفر باشد، متغیر sys.last_exc به استثنای چاپ‌شده تنظیم می‌شود. برای سازگاری با نسخه‌های پیشین، متغیرهای منسوخ sys.last_type، sys.last_value و sys.last_traceback نیز به ترتیب به نوع، مقدار و ردگیری این استثنا تنظیم می‌شوند.

تغییر یافته در نسخه‌ی 3.12: تنظیم sys.last_exc اضافه شد.

void PyErr_Print()¶: قسمتی از ABI پایدار.
مستعار برای PyErr_PrintEx(1).

void PyErr_WriteUnraisable(PyObject *obj)¶

قسمتی از ABI پایدار.

sys.unraisablehook() را با استفاده از استثنای فعلی و آرگومان obj فراخوانی کنید.

این تابع کاربردی زمانی که استثنایی تنظیم‌شده باشد اما برافکندن آن برای مفسر واقعاً ممکن نباشد، یک پیام هشدار در sys.stderr چاپ می‌کند. این تابع برای مثال زمانی استفاده می‌شود که استثنایی در متد __del__() رخ دهد.

این تابع با یک آرگومان واحد obj فراخوانی می‌شود که زمینه‌ی وقوع استثنای غیرقابل‌صدور (unraisable exception) را شناسایی می‌کند. در صورت امکان، repr مربوط به obj در پیام هشدار چاپ می‌شود. اگر obj برابر NULL باشد، فقط ردگیری پشته چاپ می‌شود.

هنگام فراخوانی این تابع، باید یک استثنا تنظیم شده باشد.

تغییر یافته در نسخه‌ی 3.4: یک ردگیری پشته چاپ می‌کند. اگر obj برابر NULL باشد، فقط ردگیری پشته را چاپ می‌کند.

تغییر یافته در نسخه‌ی 3.8: از sys.unraisablehook() استفاده کنید.

void PyErr_FormatUnraisable(const char *format, ...)¶: مشابه PyErr_WriteUnraisable() است، اما format و پارامترهای بعدی به قالب‌بندی پیام هشدار کمک می‌کنند؛ معنا و مقادیر آن‌ها همانند PyUnicode_FromFormat() است. PyErr_WriteUnraisable(obj) تقریباً معادل PyErr_FormatUnraisable("Exception ignored in: %R", obj) است. اگر format برابر NULL باشد، فقط ردگیری پشته چاپ می‌شود.

اضافه شده در نسخه‌ی 3.13.

void PyErr_DisplayException(PyObject *exc)¶: قسمتی از ABI پایدار از نسخه‌ی 3.12.
نمایش استاندارد ردگیری exc را به‌همراه استثناهای زنجیره‌شده و یادداشت‌ها در sys.stderr چاپ می‌کند.

اضافه شده در نسخه‌ی 3.12.

void PyErr_Display(PyObject *unused, PyObject *value, PyObject *tb)¶

قسمتی از ABI پایدار.

گونه‌ی قدیمیِ PyErr_DisplayException().

مقدار استثنا value را همراه با ردگیری آن در sys.stderr چاپ می‌کند. اگر برای value هیچ ردگیری‌ای تنظیم نشده باشد، از tb به‌عنوان ردگیری آن استفاده می‌شود. آرگومان اول نادیده گرفته می‌شود.

اگر sys.stderr برابر None باشد، چیزی چاپ نمی‌شود. اگر sys.stderr تنظیم نشده باشد، استثنا در عوض به جریان stderr زبان C برون‌ریزی می‌شود.

منسوخ شده از نسخه‌ی 3.12: به جای آن از PyErr_DisplayException() استفاده کنید.

برخاست دادن استثناها¶

این توابع به شما کمک می‌کنند نشانگر خطای نخ جاری را تنظیم کنید. برای سهولت، برخی از این توابع همیشه یک اشاره‌گر NULL برای استفاده در دستور return برمی‌گردانند.

void PyErr_SetString(PyObject *type, const char *message)¶: قسمتی از ABI پایدار.
این رایج‌ترین روش برای تنظیم نشانگر خطا است. آرگومان اول نوع استثنا را مشخص می‌کند؛ این آرگومان معمولاً یکی از استثناهای استاندارد است، برای مثال PyExc_RuntimeError. لازم نیست ارجاع قوی جدیدی به آن ایجاد کنید (مثلاً با Py_INCREF()). آرگومان دوم یک پیام خطا است؛ این پیام از 'utf-8' کدگشایی می‌شود.

void PyErr_SetObject(PyObject *type, PyObject *value)¶: قسمتی از ABI پایدار.
این تابع مشابه PyErr_SetString() است، اما به شما اجازه می‌دهد یک شیء دلخواه پایتون را به‌عنوان «مقدار» استثنا مشخص کنید.

PyObject *PyErr_Format(PyObject *exception, const char *format, ...)¶: مقدار بازگشتی: همیشه NULL. قسمتی از ABI پایدار.
این تابع نشانگر خطا را تنظیم می‌کند و NULL را برمی‌گرداند. exception باید یک کلاس استثنای پایتون باشد. format و پارامترهای بعدی به قالب‌بندی پیام خطا کمک می‌کنند؛ معنا و مقادیر آن‌ها همانند PyUnicode_FromFormat() است. format یک رشته کدگذاری‌شده با اسکی است.

PyObject *PyErr_FormatV(PyObject *exception, const char *format, va_list vargs)¶: مقدار بازگشتی: همیشه NULL. قسمتی از ABI پایدار از نسخه‌ی 3.5.
مانند PyErr_Format() است، اما به‌جای تعداد متغیری از آرگومان‌ها، یک آرگومان va_list می‌گیرد.

اضافه شده در نسخه‌ی 3.5.

void PyErr_SetNone(PyObject *type)¶: قسمتی از ABI پایدار.
این یک شکل مختصر برای PyErr_SetObject(type, Py_None) است.

int PyErr_BadArgument()¶: قسمتی از ABI پایدار.
این شکل کوتاهی برای PyErr_SetString(PyExc_TypeError, message) است، که در آن message نشان می‌دهد که یک عملیات توکار با آرگومانی غیرمجاز فراخوانی شده است. این عمدتاً برای استفاده‌ی داخلی است.

PyObject *PyErr_NoMemory()¶: مقدار بازگشتی: همیشه NULL. قسمتی از ABI پایدار.
این شکل مختصری برای PyErr_SetNone(PyExc_MemoryError) است؛ این تابع NULL را برمی‌گرداند تا یک تابع تخصیص شیء بتواند هنگامی که حافظه‌اش تمام می‌شود، return PyErr_NoMemory(); بنویسد.

PyObject *PyErr_SetFromErrno(PyObject *type)¶: مقدار بازگشتی: همیشه NULL. قسمتی از ABI پایدار.
این تابع برای راحتی کار فراهم شده است تا در زمانی که یک تابع کتابخانه‌ی C خطا برگردانده و متغیر C یعنی errno را تنظیم کرده است، یک استثنا پرتاب کند. این تابع یک شیء تاپل می‌سازد که آیتم نخست آن، مقدار عدد صحیح errno، و آیتم دوم آن، پیام خطای مربوطه (گرفته‌شده از strerror()) است، و سپس PyErr_SetObject(type, object) را فراخوانی می‌کند. در یونیکس، هنگامی که مقدار errno برابر EINTR باشد (که نشان‌دهنده‌ی یک فراخوانی سیستمی مختل‌شده است)، این تابع PyErr_CheckSignals() را فراخوانی می‌کند و اگر آن تابع نشانگر خطا را تنظیم کرده باشد، آن را به همان صورت تنظیم‌شده باقی می‌گذارد. این تابع همیشه NULL را برمی‌گرداند، بنابراین یک تابع پوششی حول یک فراخوانی سیستمی می‌تواند هنگامی که فراخوانی سیستمی خطا برمی‌گرداند، return PyErr_SetFromErrno(type); بنویسد.

PyObject *PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)¶: مقدار بازگشتی: همیشه NULL. قسمتی از ABI پایدار.
مشابه PyErr_SetFromErrno()، با این رفتار اضافی که اگر filenameObject برابر NULL نباشد، به‌عنوان پارامتر سوم به سازنده‌ی type پاس داده می‌شود. در مورد استثنای OSError، از این برای تعریف ویژگی filename نمونه‌ی استثنا استفاده می‌شود.

PyObject *PyErr_SetFromErrnoWithFilenameObjects(PyObject *type, PyObject *filenameObject, PyObject *filenameObject2)¶: مقدار بازگشتی: همیشه NULL. قسمتی از ABI پایدار از نسخه‌ی 3.7.
مشابه PyErr_SetFromErrnoWithFilenameObject() است، اما یک شیء نام پرونده‌ی دوم می‌گیرد تا هنگامی که تابعی که دو نام پرونده می‌گیرد شکست می‌خورد، خطاها برافراشته شوند.

اضافه شده در نسخه‌ی 3.4.

PyObject *PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)¶: مقدار بازگشتی: همیشه NULL. قسمتی از ABI پایدار.
مشابه PyErr_SetFromErrnoWithFilenameObject()، با این تفاوت که نام پرونده به‌صورت یک رشته‌ی C داده می‌شود. filename با استفاده از filesystem encoding and error handler کدگشایی می‌شود.

PyObject *PyErr_SetFromWindowsErr(int ierr)¶: مقدار بازگشتی: همیشه NULL. قسمتی از ABI پایدار on Windows از نسخه‌ی 3.7.
این یک تابع کمکی برای پرتاب OSError است. اگر با مقدار 0 برای ierr فراخوانی شود، به‌جای آن از کد خطایی که فراخوانی GetLastError() برمی‌گرداند استفاده می‌شود. این تابع برای بازیابی توضیح ویندوز برای کد خطای داده‌شده توسط ierr یا GetLastError()، تابع Win32 یعنی FormatMessage() را فراخوانی می‌کند؛ سپس یک شیء OSError می‌سازد که ویژگی winerror آن روی کد خطا و ویژگی strerror آن روی پیام خطای متناظر (گرفته‌شده از FormatMessage()) تنظیم شده‌اند، و سپس PyErr_SetObject(PyExc_OSError, object) را فراخوانی می‌کند. این تابع همیشه NULL را برمی‌گرداند.

دسترس‌پذیری: Windows.

PyObject *PyErr_SetExcFromWindowsErr(PyObject *type, int ierr)¶: مقدار بازگشتی: همیشه NULL. قسمتی از ABI پایدار on Windows از نسخه‌ی 3.7.
مشابه PyErr_SetFromWindowsErr()، با یک پارامتر اضافی برای تعیین نوع استثنایی که باید ایجاد شود.

دسترس‌پذیری: Windows.

PyObject *PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)¶: مقدار بازگشتی: همیشه NULL. قسمتی از ABI پایدار on Windows از نسخه‌ی 3.7.
مشابه PyErr_SetFromWindowsErr()، با این رفتار افزوده که اگر filename برابر NULL نباشد، بر اساس کدگذاری سامانه فایل‌بندی (os.fsdecode()) کدگشایی می‌شود و به‌عنوان پارامتر سوم به سازنده‌ی OSError ارسال می‌شود تا برای تعریف ویژگی filename در نمونه‌ی استثنا استفاده شود.

دسترس‌پذیری: Windows.

PyObject *PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)¶: مقدار بازگشتی: همیشه NULL. قسمتی از ABI پایدار on Windows از نسخه‌ی 3.7.
مشابه PyErr_SetExcFromWindowsErr()، با این رفتار اضافی که اگر filename برابر NULL نباشد، به‌عنوان پارامتر سوم به سازنده‌ی OSError پاس داده می‌شود تا برای تعریف ویژگی filename در نمونه‌ی استثنا استفاده شود.

دسترس‌پذیری: Windows.

PyObject *PyErr_SetExcFromWindowsErrWithFilenameObjects(PyObject *type, int ierr, PyObject *filename, PyObject *filename2)¶: مقدار بازگشتی: همیشه NULL. قسمتی از ABI پایدار on Windows از نسخه‌ی 3.7.
مشابه PyErr_SetExcFromWindowsErrWithFilenameObject() است، اما یک شیء نام پرونده‌ی دوم را می‌پذیرد.

دسترس‌پذیری: Windows.

اضافه شده در نسخه‌ی 3.4.

PyObject *PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)¶: مقدار بازگشتی: همیشه NULL. قسمتی از ABI پایدار on Windows از نسخه‌ی 3.7.
مشابه PyErr_SetFromWindowsErrWithFilename()، با یک پارامتر اضافی برای مشخص کردن نوع استثنایی که باید مطرح (raise) شود.

دسترس‌پذیری: Windows.

PyObject *PyErr_SetImportError(PyObject *msg, PyObject *name, PyObject *path)¶: مقدار بازگشتی: همیشه NULL. قسمتی از ABI پایدار از نسخه‌ی 3.7.
این یک تابع کمکی برای ایجاد استثنای ImportError است. msg به‌عنوان رشته‌ی پیام استثنا تنظیم می‌شود. name و path، که هر دو می‌توانند NULL باشند، به‌ترتیب به‌عنوان ویژگی‌های name و path مربوط به ImportError تنظیم می‌شوند.

اضافه شده در نسخه‌ی 3.3.

PyObject *PyErr_SetImportErrorSubclass(PyObject *exception, PyObject *msg, PyObject *name, PyObject *path)¶: مقدار بازگشتی: همیشه NULL. قسمتی از ABI پایدار از نسخه‌ی 3.6.
بسیار شبیه PyErr_SetImportError() است، اما این تابع به شما امکان می‌دهد زیرکلاسی از ImportError را برای برافکندن مشخص کنید.

اضافه شده در نسخه‌ی 3.6.

void PyErr_SyntaxLocationObject(PyObject *filename, int lineno, int col_offset)¶: اطلاعات پرونده، سطر و آفست را برای استثنای کنونی تنظیم می‌کند. اگر استثنای کنونی SyntaxError نباشد، ویژگی‌های اضافی تنظیم می‌کند که باعث می‌شوند زیرسیستم چاپ استثنا، استثنا را یک SyntaxError تلقی کند.

اضافه شده در نسخه‌ی 3.4.

void PyErr_RangedSyntaxLocationObject(PyObject *filename, int lineno, int col_offset, int end_lineno, int end_col_offset)¶: مشابه PyErr_SyntaxLocationObject()، اما اطلاعات end_lineno و end_col_offset را نیز برای استثنای فعلی تنظیم می‌کند.

اضافه شده در نسخه‌ی 3.10.

void PyErr_SyntaxLocationEx(const char *filename, int lineno, int col_offset)¶: قسمتی از ABI پایدار از نسخه‌ی 3.7.
مانند PyErr_SyntaxLocationObject()، اما filename یک رشته بایتی است که با filesystem encoding and error handler کدگشایی‌شده است.

اضافه شده در نسخه‌ی 3.2.

void PyErr_SyntaxLocation(const char *filename, int lineno)¶: قسمتی از ABI پایدار.
مانند PyErr_SyntaxLocationEx()، اما پارامتر col_offset حذف شده است.

void PyErr_BadInternalCall()¶: قسمتی از ABI پایدار.
این یک شکل مختصر برای PyErr_SetString(PyExc_SystemError, message) است، که در آن message نشان می‌دهد که یک عملیات داخلی (مثلاً یک تابع Python/C API) با آرگومانی نامعتبر فراخوانی شده است. این عمدتاً برای استفاده داخلی است.

PyObject *PyErr_ProgramTextObject(PyObject *filename, int lineno)¶

گرفتن سطر منبع از filename در سطر lineno. filename باید یک شیء str پایتون باشد.

در صورت موفقیت، این تابع یک شیء رشته پایتون حاوی سطر یافت‌شده را برمی‌گرداند. در صورت شکست، این تابع NULL را بدون تنظیم استثنا برمی‌گرداند.

PyObject *PyErr_ProgramText(const char *filename, int lineno)¶: قسمتی از ABI پایدار.
مشابه PyErr_ProgramTextObject()، اما filename به‌جای ارجاع به شیء پایتون، یک const char* است که با filesystem encoding and error handler کدگشایی می‌شود.

صدور هشدارها¶

از این توابع برای صدور هشدار از کد C استفاده کنید. این توابع قرینه‌ی توابع مشابهی هستند که ماژول warnings پایتون اکسپورت می‌کند. این توابع معمولاً یک پیام هشدار را در sys.stderr چاپ می‌کنند؛ با این حال، این امکان نیز وجود دارد که کاربر تعیین کرده باشد که هشدارها به خطا تبدیل شوند، و در این حالت این توابع یک استثنا ایجاد می‌کنند. همچنین این امکان وجود دارد که توابع به دلیل مشکلی در سازوکار هشدار، استثنا ایجاد کنند. مقدار بازگشتی 0 است اگر استثنایی ایجاد نشود، یا -1 اگر استثنایی ایجاد شود. (امکان تعیین اینکه آیا پیام هشدار واقعاً چاپ می‌شود یا اینکه دلیل استثنا چیست وجود ندارد؛ این موضوع عمدی است.) اگر استثنایی ایجاد شود، فراخواننده باید مدیریت استثنای معمول خود را انجام دهد (برای مثال، فراخوانی Py_DECREF() روی ارجاع‌های در مالکیت و برگرداندن یک مقدار خطا).

int PyErr_WarnEx(PyObject *category, const char *message, Py_ssize_t stack_level)¶

قسمتی از ABI پایدار.

یک پیام هشدار صادر می‌کند. آرگومان category یک دسته‌ی هشدار است (در ادامه مراجعه کنید) یا NULL؛ آرگومان message یک رشته‌ی کدگذاری‌شده با UTF-8 است. stack_level یک عدد مثبت است که تعداد فریم‌های پشته را مشخص می‌کند؛ هشدار از سطر کدِ در حال اجرا در آن فریم پشته صادر خواهد شد. stack_level برابر ۱ تابعی است که PyErr_WarnEx() را فراخوانی می‌کند، ۲ تابع بالاتر از آن است، و به همین ترتیب.

دسته‌های هشدار باید زیرکلاس‌هایی از PyExc_Warning باشند؛ PyExc_Warning زیرکلاسی از PyExc_Exception است؛ دسته‌ی پیش‌فرض هشدار، PyExc_RuntimeWarning است. دسته‌های هشدار استاندارد پایتون به‌صورت متغیرهای سراسری در دسترس هستند که نام‌های آن‌ها در انواع هشدار فهرست شده است.

برای کسب اطلاعات درباره‌ی کنترل هشدارها، به مستندات ماژول warnings و گزینه‌ی -W در مستندات خط فرمان مراجعه کنید. برای کنترل هشدارها API زبان C وجود ندارد.

int PyErr_WarnExplicitObject(PyObject *category, PyObject *message, PyObject *filename, int lineno, PyObject *module, PyObject *registry)¶: یک پیام هشدار با کنترل صریح بر تمام ویژگی‌های هشدار صادر می‌کند. این پوششی ساده در اطراف تابع پایتونی warnings.warn_explicit() است؛ برای اطلاعات بیشتر به آنجا مراجعه کنید. آرگومان‌های module و registry می‌توانند روی NULL تنظیم شوند تا اثر پیش‌فرضِ توصیف‌شده در آنجا به دست آید.

اضافه شده در نسخه‌ی 3.4.

int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry)¶: قسمتی از ABI پایدار.
مشابه PyErr_WarnExplicitObject() است، با این تفاوت که message و module رشته‌های کدگذاری‌شده با UTF-8 هستند و filename از filesystem encoding and error handler کدگشایی می‌شود.

int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)¶: قسمتی از ABI پایدار.
تابعی مشابه PyErr_WarnEx() است، اما از PyUnicode_FromFormat() برای قالب‌بندی پیام هشدار استفاده می‌کند. format یک رشته کدگذاری‌شده با اسکی است.

اضافه شده در نسخه‌ی 3.2.

int PyErr_WarnExplicitFormat(PyObject *category, const char *filename, int lineno, const char *module, PyObject *registry, const char *format, ...)¶: مشابه PyErr_WarnExplicit()، اما برای قالب‌بندی پیام هشدار از PyUnicode_FromFormat() استفاده می‌کند. format یک رشته کدگذاری‌شده با اسکی است.

اضافه شده در نسخه‌ی 3.2.

int PyErr_ResourceWarning(PyObject *source, Py_ssize_t stack_level, const char *format, ...)¶: قسمتی از ABI پایدار از نسخه‌ی 3.6.
تابعی مشابه PyErr_WarnFormat()، اما category برابر ResourceWarning است و source را به warnings.WarningMessage پاس می‌دهد.

اضافه شده در نسخه‌ی 3.6.

پرس‌وجو از نشانگر خطا¶

PyObject *PyErr_Occurred()¶

مقدار بازگشتی: مرجع امانتی. قسمتی از ABI پایدار.

بررسی می‌کند که آیا نشانگر خطا تنظیم شده است. اگر تنظیم شده باشد، نوع استثنا را برمی‌گرداند (آرگومان اول آخرین فراخوانی یکی از توابع PyErr_Set* یا PyErr_Restore()). اگر تنظیم نشده باشد، NULL را برمی‌گرداند. شما مالک ارجاع به مقدار بازگشتی نیستید، بنابراین نیازی به Py_DECREF() کردن آن ندارید.

فراخواننده باید attached thread state داشته باشد.

توجه

مقدار بازگشتی را با یک استثنای مشخص مقایسه نکنید؛ در عوض از PyErr_ExceptionMatches() استفاده کنید که در ادامه نشان داده شده است. (این مقایسه به‌راحتی می‌تواند شکست بخورد، زیرا در مورد استثنای کلاسی، استثنا ممکن است به جای کلاس، نمونه‌ای باشد، یا ممکن است زیرکلاسی از استثنای مورد انتظار باشد.)

int PyErr_ExceptionMatches(PyObject *exc)¶: قسمتی از ABI پایدار.
معادل PyErr_GivenExceptionMatches(PyErr_Occurred(), exc) است. این باید تنها زمانی فراخوانی شود که استثنا واقعاً تنظیم شده باشد؛ اگر هیچ استثنایی ایجاد نشده باشد، نقض دسترسی به حافظه (memory access violation) رخ خواهد داد.

int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc)¶: قسمتی از ABI پایدار.
اگر استثنای given با نوع استثنا در exc مطابقت داشته باشد، مقدار true بازگردانده می‌شود. اگر exc یک شیء کلاس باشد، در صورتی که given نمونه‌ای از یک زیرکلاس باشد نیز مقدار true بازگردانده می‌شود. اگر exc یک تاپل باشد، تمام انواع استثنا در تاپل (و به‌صورت بازگشتی در زیرتاپل‌ها) برای یافتن تطبیق جستجو می‌شوند.

PyObject *PyErr_GetRaisedException(void)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار از نسخه‌ی 3.12.

استثنایی که هم‌اکنون در حال raise شدن است را برمی‌گرداند و همزمان نشانگر خطا را پاک می‌کند. اگر نشانگر خطا تنظیم نشده باشد، NULL را برمی‌گرداند.

این تابع توسط کدهایی استفاده می‌شود که نیاز به گرفتن استثناها دارند، یا کدهایی که نیاز دارند نشانگر خطا را به‌طور موقت ذخیره و بازیابی کنند.

برای مثال:

{
   PyObject *exc = PyErr_GetRaisedException();

   /* ... code that might produce other errors ... */

   PyErr_SetRaisedException(exc);
}

همچنین ملاحظه نمائید

PyErr_GetHandledException()، برای ذخیره‌ی استثنایی که در حال حاضر مدیریت می‌شود.

اضافه شده در نسخه‌ی 3.12.

void PyErr_SetRaisedException(PyObject *exc)¶

قسمتی از ABI پایدار از نسخه‌ی 3.12.

exc را به عنوان استثنای در حال رخ دادن تنظیم می‌کند و اگر استثنایی از قبل تنظیم شده باشد، آن را پاک می‌کند. اگر exc برابر NULL باشد، تنها استثنای موجود پاک می‌شود.

exc باید یک استثنای معتبر یا NULL باشد.

این فراخوانی ارجاعی به exc را «می‌دزدد».

اضافه شده در نسخه‌ی 3.12.

void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)¶

قسمتی از ABI پایدار.

منسوخ شده از نسخه‌ی 3.12: به جای آن از PyErr_GetRaisedException() استفاده کنید.

نشانگر خطا را در سه متغیر که آدرس آن‌ها ارسال شده است، بازیابی کنید. اگر نشانگر خطا فعال نباشد، هر سه متغیر را روی NULL تنظیم کنید. اگر فعال باشد، پاک می‌شود و شما مالک یک ارجاع به هر یک از اشیای بازیابی‌شده خواهید بود. شیء مقدار و شیء ردیابی پشته ممکن است حتی زمانی که شیء نوع NULL نیست، NULL باشند.

توجه

این تابع معمولاً تنها توسط کدهای قدیمی‌ای استفاده می‌شود که نیاز دارند استثناها را بگیرند یا نشانگر خطا را به‌طور موقت ذخیره و بازیابی کنند.

برای مثال:

{
   PyObject *type, *value, *traceback;
   PyErr_Fetch(&type, &value, &traceback);

   /* ... code that might produce other errors ... */

   PyErr_Restore(type, value, traceback);
}

void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback)¶: قسمتی از ABI پایدار.

منسوخ شده از نسخه‌ی 3.12: به‌جای آن از PyErr_SetRaisedException() استفاده کنید.

نشانگر خطا را از سه شیء type، value و traceback تنظیم می‌کند و اگر استثنایی از پیش تنظیم شده باشد، استثنای موجود را پاک می‌کند. اگر این اشیاء NULL باشند، نشانگر خطا پاک می‌شود. نوع NULL را همراه با مقدار یا ردگیری غیر NULL ارسال نکنید. نوع استثنا باید یک کلاس باشد. نوع یا مقدار نامعتبر برای استثنا ارسال نکنید. (نقض این قواعد بعداً موجب مشکلات ظریفی خواهد شد.) این فراخوانی یک ارجاع به هر شیء را برمی‌دارد: شما باید پیش از فراخوانی مالک ارجاعی به هر شیء باشید و پس از فراخوانی، دیگر مالک این ارجاع‌ها نخواهید بود. (اگر این را نمی‌فهمید، از این تابع استفاده نکنید. من به شما هشدار دادم.)

توجه

این تابع معمولاً فقط توسط کدهای قدیمی‌ای استفاده می‌شود که نیاز دارند نشانگر خطا را به‌طور موقت ذخیره و بازیابی کنند. برای ذخیره کردن نشانگر خطای فعلی، از PyErr_Fetch() استفاده کنید.

void PyErr_NormalizeException(PyObject **exc, PyObject **val, PyObject **tb)¶

قسمتی از ABI پایدار.

منسوخ شده از نسخه‌ی 3.12: به جای آن از PyErr_GetRaisedException() استفاده کنید تا از هرگونه نرمال‌زدایی (de-normalization) احتمالی جلوگیری شود.

در شرایط خاص، مقادیری که PyErr_Fetch() در ادامه بازمی‌گرداند می‌توانند «نرمال‌نشده» باشند؛ یعنی *exc یک شیء کلاس است اما *val نمونه‌ای از همان کلاس نیست. در این حالت می‌توان از این تابع برای نمونه‌سازی کردن کلاس استفاده کرد. اگر مقادیر از قبل نرمال شده باشند، هیچ اتفاقی نمی‌افتد. نرمال‌سازی معوق برای بهبود کارایی پیاده‌سازی شده است.

توجه

این تابع ویژگی __traceback__ را به‌صورت ضمنی روی مقدار استثنا تنظیم نمی‌کند. اگر مایلید ردگیری به‌نحو مناسب تنظیم شود، قطعه‌کد اضافی زیر لازم است:

if (tb != NULL) {
  PyException_SetTraceback(val, tb);
}

PyObject *PyErr_GetHandledException(void)¶: قسمتی از ABI پایدار از نسخه‌ی 3.11.
نمونه‌ی استثنای فعال را بازیابی می‌کند؛ همان چیزی که sys.exception() برمی‌گرداند. این به استثنایی اشاره دارد که از قبل گرفته‌شده است، نه به استثنایی که به‌تازگی ایجاد (raise) شده است. یک ارجاع جدید به استثنا یا NULL برمی‌گرداند. وضعیت استثنای مفسر را تغییر نمی‌دهد.

توجه

این تابع به‌طور معمول توسط کدهایی که می‌خواهند استثناها را مدیریت کنند استفاده نمی‌شود؛ بلکه می‌توان از آن در مواردی استفاده کرد که کد نیاز دارد وضعیت استثنا را به‌طور موقت ذخیره و بازیابی کند. برای بازیابی یا پاک کردن وضعیت استثنا از PyErr_SetHandledException() استفاده کنید.

اضافه شده در نسخه‌ی 3.11.

void PyErr_SetHandledException(PyObject *exc)¶: قسمتی از ABI پایدار از نسخه‌ی 3.11.
استثنای فعال را، همان‌طور که از sys.exception() شناخته می‌شود، تنظیم کنید. این به استثنایی اشاره دارد که از قبل گرفته‌شده است، نه به استثنایی که به‌تازگی ایجاد (raised) شده است. برای پاک کردن وضعیت استثنا، NULL را ارسال کنید.

توجه

این تابع معمولاً توسط کدی که می‌خواهد استثناها را مدیریت کند استفاده نمی‌شود؛ بلکه زمانی به کار می‌رود که کد نیاز داشته باشد وضعیت استثنا را به‌طور موقت ذخیره و بازیابی کند. برای دریافت وضعیت استثنا از PyErr_GetHandledException() استفاده کنید.

اضافه شده در نسخه‌ی 3.11.

void PyErr_GetExcInfo(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback)¶: قسمتی از ABI پایدار از نسخه‌ی 3.7.
بازنمایی قدیمی اطلاعات استثنا را، همان‌گونه که از sys.exc_info() شناخته می‌شود، بازیابی می‌کند. این به استثنایی اشاره دارد که از پیش گرفته شده است، نه به استثنایی که به‌تازگی مطرح (raise) شده است. ارجاع‌های جدیدی برای سه شیء برمی‌گرداند که هر یک ممکن است NULL باشد. وضعیت اطلاعات استثنا را تغییر نمی‌دهد. این تابع برای سازگاری با نسخه‌های پیشین نگه داشته شده است. ترجیحاً از PyErr_GetHandledException() استفاده کنید.

توجه

این تابع معمولاً توسط کدهایی که می‌خواهند استثناها را مدیریت کنند استفاده نمی‌شود. بلکه می‌توان از آن در مواردی استفاده کرد که کد نیاز دارد وضعیت استثنا را به‌طور موقت ذخیره و بازیابی کند. برای بازیابی یا پاک کردن وضعیت استثنا از PyErr_SetExcInfo() استفاده کنید.

اضافه شده در نسخه‌ی 3.3.

void PyErr_SetExcInfo(PyObject *type, PyObject *value, PyObject *traceback)¶: قسمتی از ABI پایدار از نسخه‌ی 3.7.
اطلاعات استثنا را همان‌طور که از sys.exc_info() شناخته می‌شود تنظیم می‌کند. این به استثنایی اشاره دارد که قبلاً گرفته‌شده است، نه به استثنایی که به‌تازگی ایجاد (raise) شده است. این تابع ارجاع‌های آرگومان‌ها را «می‌دزدد». برای پاک کردن وضعیت استثنا، NULL را برای هر سه آرگومان ارسال کنید. این تابع برای سازگاری با نسخه‌های پیشین نگه داشته شده است. ترجیحاً از PyErr_SetHandledException() استفاده کنید.

توجه

این تابع به‌طور معمول توسط کدی که می‌خواهد استثناها را مدیریت کند، استفاده نمی‌شود. بلکه، زمانی که کد نیاز دارد وضعیت استثنا را به‌طور موقت ذخیره و بازیابی کند، می‌توان از آن استفاده کرد. برای خواندن وضعیت استثنا از PyErr_GetExcInfo() استفاده کنید.

اضافه شده در نسخه‌ی 3.3.

تغییر یافته در نسخه‌ی 3.11: آرگومان‌های type و traceback دیگر استفاده نمی‌شوند و می‌توانند NULL باشند. مفسر اکنون آن‌ها را از نمونه‌ی استثنا (آرگومان value) استخراج می‌کند. این تابع همچنان ارجاع‌های هر سه آرگومان را «می‌دزدد».

مدیریت سیگنال¶

int PyErr_CheckSignals()¶

قسمتی از ABI پایدار.

رسیدگی می‌کند به وقفه‌های خارجی، مانند سیگنال‌ها یا فعال‌سازی اشکال‌زدا، که پردازش آن‌ها به تعویق افتاده است تا زمانی که اجرای کد پایتون و/یا برافراختن استثناها ایمن باشد.

برای مثال، فشردن Ctrl-C باعث می‌شود یک پایانه سیگنال signal.SIGINT را ارسال کند. این تابع هندلر سیگنال متناظر در پایتون را اجرا می‌کند که به‌طور پیش‌فرض استثنای KeyboardInterrupt را ایجاد می‌کند.

PyErr_CheckSignals() باید توسط کد C طولانی‌مدت به‌اندازه‌ای مکرر فراخوانی شود که پاسخ از دید انسان‌ها فوری به‌نظر برسد.

هندلر‌هایی که توسط این تابع فراخوانی می‌شوند، در حال حاضر عبارت‌اند از:

هندلرهای سیگنال، از جمله توابع پایتونی که با استفاده از ماژول signal ثبت شده‌اند.

هندلرهای سیگنال فقط در نخ اصلی مفسر اصلی اجرا می‌شوند.

(این تابع نام خود را از اینجا گرفته است: در اصل، سیگنال‌ها تنها راه برای مقاطعه کردن مفسر بودند.)
اجرای زباله‌روب، در صورت نیاز.
اجرای یک اسکریپت در انتظار اشکال‌زدای راه دور.

اگر هر هندلری استثنایی ایجاد کند، بلافاصله -1 همراه با آن استثنای تنظیم‌شده بازگردانده می‌شود. پردازش هر وقفه‌ی باقی‌مانده، در صورت لزوم، به فراخوانی بعدی PyErr_CheckSignals() موکول می‌شود.

اگر همه‌ی هندلرها با موفقیت پایان یابند، یا هندلری برای اجرا وجود نداشته باشد، 0 را برمی‌گرداند.

تغییر یافته در نسخه‌ی 3.12: این تابع ممکن است اکنون زباله‌روب را فراخوانی کند.

تغییر یافته در نسخه‌ی 3.14: این تابع اکنون ممکن است در صورت فعال بودن اشکال‌زدایی از راه دور، یک اسکریپت اشکال‌زدای از راه دور را اجرا کند.

void PyErr_SetInterrupt()¶: قسمتی از ABI پایدار.
اثر رسیدن سیگنال SIGINT را شبیه‌سازی می‌کند. این معادل PyErr_SetInterruptEx(SIGINT) است.

توجه

این تابع نسبت به سیگنال ناهمگام ایمن است (async-signal-safe). این تابع را می‌توان بدون وضعیت نخ متصل و از یک هندلر سیگنال C فراخوانی کرد.

int PyErr_SetInterruptEx(int signum)¶

قسمتی از ABI پایدار از نسخه‌ی 3.10.

شبیه‌سازی اثر رسیدن یک سیگنال. دفعه بعد که PyErr_CheckSignals() فراخوانی شود، هندلر سیگنال پایتون برای شماره سیگنال داده‌شده فراخوانی خواهد شد.

این تابع را می‌توان از کد C‌ای فراخوانی کرد که مدیریت سیگنال خود را راه‌اندازی می‌کند و می‌خواهد هندلرهای سیگنال پایتون هنگامی که وقفه‌ای درخواست شود، همان‌طور که انتظار می‌رود فراخوانی شوند (برای مثال وقتی کاربر برای قطع کردن یک عملیات، Ctrl-C را فشار می‌دهد).

اگر سیگنال داده‌شده توسط پایتون هندل نشده باشد (روی signal.SIG_DFL یا signal.SIG_IGN تنظیم‌شده باشد)، نادیده گرفته خواهد شد.

اگر signum خارج از بازه‌ی مجاز شماره‌های سیگنال باشد، مقدار -1 بازگردانده می‌شود. در غیر این صورت، مقدار 0 بازگردانده می‌شود. این تابع هرگز نشانگر خطا را تغییر نمی‌دهد.

توجه

این تابع نسبت به سیگنال ناهمگام ایمن است (async-signal-safe). این تابع را می‌توان بدون وضعیت نخ متصل و از یک هندلر سیگنال C فراخوانی کرد.

اضافه شده در نسخه‌ی 3.10.

int PySignal_SetWakeupFd(int fd)¶

این تابع کاربردی، توصیف‌گر پرونده‌ای را مشخص می‌کند که هر زمان سیگنالی دریافت شود، شماره‌ی سیگنال به‌صورت یک بایت منفرد در آن نوشته می‌شود. fd باید غیرمسدود باشد. این تابع توصیف‌گر پرونده‌ی قبلی از این نوع را برمی‌گرداند.

مقدار -1 این قابلیت را غیرفعال می‌کند؛ این وضعیت اولیه است. این معادل signal.set_wakeup_fd() در پایتون است، اما بدون هیچ بررسی خطایی. fd باید یک توصیف‌گر پرونده معتبر باشد. این تابع باید فقط از نخ اصلی فراخوانی شود.

تغییر یافته در نسخه‌ی 3.5: در ویندوز، این تابع اکنون از دسته‌های سوکت نیز پشتیبانی می‌کند.

کلاس‌های استثنا¶

PyObject *PyErr_NewException(const char *name, PyObject *base, PyObject *dict)¶

مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.

این تابع کاربردی یک کلاس استثنای جدید ایجاد می‌کند و آن را برمی‌گرداند. آرگومان name باید نام استثنای جدید باشد؛ یعنی یک رشته‌ی C به شکل module.classname. آرگومان‌های base و dict معمولاً NULL هستند. این یک شیء کلاس مشتق‌شده از Exception ایجاد می‌کند (که در C به صورت PyExc_Exception قابل دسترسی است).

ویژگی __module__ کلاس جدید به بخش اول (تا آخرین نقطه) آرگومان name تنظیم می‌شود و نام کلاس به بخش آخر (پس از آخرین نقطه) تنظیم می‌شود. از آرگومان base می‌توان برای مشخص کردن کلاس‌های پایه‌ی جایگزین استفاده کرد؛ این آرگومان می‌تواند تنها یک کلاس یا یک تاپل از کلاس‌ها باشد. از آرگومان dict می‌توان برای مشخص کردن یک دیکشنری از متغیرهای کلاس و متدها استفاده کرد.

PyObject *PyErr_NewExceptionWithDoc(const char *name, const char *doc, PyObject *base, PyObject *dict)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
مانند PyErr_NewException() است، با این تفاوت که می‌توان به‌راحتی به کلاس استثنای جدید یک رشته مستند داد: اگر doc مقدار NULL نباشد، از آن به‌عنوان رشته مستند کلاس استثنا استفاده خواهد شد.

اضافه شده در نسخه‌ی 3.2.

int PyExceptionClass_Check(PyObject *ob)¶: اگر ob یک کلاس استثنا باشد، مقدار ناصفر و در غیر این صورت صفر برمی‌گرداند. این تابع همیشه با موفقیت اجرا می‌شود.

const char *PyExceptionClass_Name(PyObject *ob)¶: قسمتی از ABI پایدار از نسخه‌ی 3.8.
tp_name کلاس استثنا ob را بازمی‌گرداند.

اشیاء استثنا¶

int PyExceptionInstance_Check(PyObject *op)¶: اگر op نمونه‌ای از BaseException باشد، true برمی‌گرداند و در غیر این صورت false. این تابع همیشه با موفقیت انجام می‌شود.

PyExceptionInstance_Class(op)¶: معادل Py_TYPE(op) است.

PyObject *PyException_GetTraceback(PyObject *ex)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
ردگیری مرتبط با استثنا را به‌عنوان یک ارجاع جدید برمی‌گرداند؛ همان‌طور که از پایتون از طریق ویژگی __traceback__ قابل دسترسی است. اگر هیچ ردگیری مرتبطی وجود نداشته باشد، این تابع NULL را برمی‌گرداند.

int PyException_SetTraceback(PyObject *ex, PyObject *tb)¶: قسمتی از ABI پایدار.
ردگیری مرتبط با استثنا را برابر tb قرار می‌دهد. برای پاک کردن آن از Py_None استفاده کنید.

PyObject *PyException_GetContext(PyObject *ex)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
زمینه (نمونه استثنای دیگری که در حین مدیریت آن، ex پرتاب شده است) مرتبط با استثنا را به‌عنوان یک ارجاع جدید برمی‌گرداند؛ همان‌طور که از پایتون از طریق ویژگی __context__ دسترسی‌پذیر است. اگر زمینه‌ای مرتبط نباشد، این تابع NULL را برمی‌گرداند.

void PyException_SetContext(PyObject *ex, PyObject *ctx)¶: قسمتی از ABI پایدار.
زمینه مرتبط با استثنا را به ctx تنظیم می‌کند. برای پاک‌کردن آن از NULL استفاده کنید. هیچ بررسی نوعی برای اطمینان از این‌که ctx نمونه‌ای از استثنا است انجام نمی‌شود. این تابع ارجاعی به ctx را «می‌دزدد».

PyObject *PyException_GetCause(PyObject *ex)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
بازگرداندن علت مرتبط با استثنا (که یا یک نمونه‌ی استثنا است یا None، و توسط raise ... from ... تنظیم شده است) به‌عنوان یک ارجاع جدید، همان‌طور که در پایتون از طریق ویژگی __cause__ قابل دسترسی است.

void PyException_SetCause(PyObject *ex, PyObject *cause)¶

قسمتی از ABI پایدار.

علت مرتبط با استثنا را برابر cause قرار می‌دهد. برای پاک کردن آن از NULL استفاده کنید. هیچ بررسی نوعی برای اطمینان از اینکه cause یا نمونه‌ای از استثنا است یا None، انجام نمی‌شود. این یک ارجاع به cause را «می‌دزدد».

ویژگی __suppress_context__ به‌طور ضمنی توسط این تابع برابر True قرار می‌گیرد.

PyObject *PyException_GetArgs(PyObject *ex)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار از نسخه‌ی 3.12.
بازگشت args از استثنای ex.

void PyException_SetArgs(PyObject *ex, PyObject *args)¶: قسمتی از ABI پایدار از نسخه‌ی 3.12.
مقدار args استثنای ex را برابر args قرار می‌دهد.

PyObject *PyUnstable_Exc_PrepReraiseStar(PyObject *orig, PyObject *excs)¶: این است API ناپایداراین ممکن است بدون هشدار در نسخه‌های جزئی تغییر کند.

بخشی از پیاده‌سازی except* توسط مفسر را انجام می‌دهد. orig استثنای اصلی است که گرفته شده است، و excs فهرست استثناهایی است که باید مطرح (raise) شوند. این فهرست شامل بخش مدیریت‌نشده‌ی orig (در صورت وجود) و همچنین استثناهایی است که از بندهای except* مطرح شده‌اند (بنابراین ردگیری‌شان با orig متفاوت است) و آن‌هایی که دوباره مطرح شده‌اند (و ردگیری‌شان با orig یکسان است). ExceptionGroup را برمی‌گرداند که در نهایت باید دوباره مطرح شود، یا None را اگر چیزی برای مطرح شدن مجدد وجود ندارد.

اضافه شده در نسخه‌ی 3.12.

اشیاء استثنای یونیکد¶

توابع زیر برای ایجاد و تغییر استثناهای یونیکد از C استفاده می‌شوند.

PyObject *PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
یک شیء UnicodeDecodeError با ویژگی‌های encoding، object، length، start، end و reason ایجاد کنید. encoding و reason رشته‌های کدگذاری‌شده با UTF-8 هستند.

PyObject *PyUnicodeDecodeError_GetEncoding(PyObject *exc)¶
PyObject *PyUnicodeEncodeError_GetEncoding(PyObject *exc)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
ویژگی encoding شیء استثنای داده‌شده را بازمی‌گرداند.

PyObject *PyUnicodeDecodeError_GetObject(PyObject *exc)¶
PyObject *PyUnicodeEncodeError_GetObject(PyObject *exc)¶
PyObject *PyUnicodeTranslateError_GetObject(PyObject *exc)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
ویژگی object شیء استثنای داده‌شده را برمی‌گرداند.

int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start)¶

int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start)¶

int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start)¶

قسمتی از ABI پایدار.

ویژگی start شیء استثنای داده‌شده را می‌گیرد و آن را در *start قرار می‌دهد. start نباید NULL باشد. در صورت موفقیت 0 و در صورت شکست -1 برمی‌گرداند.

اگر UnicodeError.object یک دنباله‌ی خالی باشد، start حاصل 0 است. در غیر این صورت، start به [0, len(object) - 1] محدود می‌شود.

همچنین ملاحظه نمائید

UnicodeError.start

int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start)¶
int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start)¶
int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start)¶: قسمتی از ABI پایدار.
ویژگی start شیء استثنای داده‌شده را برابر start قرار می‌دهد. در صورت موفقیت 0 و در صورت شکست -1 برمی‌گرداند.

توجه

اگرچه گذراندن یک start منفی استثنایی مطرح نمی‌کند، getter‌ها (getters) مربوطه آن را به‌عنوان یک آفست نسبی در نظر نخواهند گرفت.

int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end)¶

int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end)¶

int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end)¶

قسمتی از ABI پایدار.

ویژگی end شیء استثنای داده‌شده را دریافت می‌کند و آن را در *end قرار می‌دهد. end نباید NULL باشد. در صورت موفقیت 0 و در صورت شکست -1 برمی‌گرداند.

اگر UnicodeError.object یک دنباله‌ی خالی باشد، end حاصل 0 است. در غیر این صورت، این مقدار به [1, len(object)] محدود می‌شود.

int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end)¶
int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end)¶
int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end)¶: قسمتی از ABI پایدار.
ویژگی end شیء استثنای داده‌شده را به end تنظیم می‌کند. در صورت موفقیت 0 و در صورت شکست -1 برمی‌گرداند.

همچنین ملاحظه نمائید

UnicodeError.end

PyObject *PyUnicodeDecodeError_GetReason(PyObject *exc)¶
PyObject *PyUnicodeEncodeError_GetReason(PyObject *exc)¶
PyObject *PyUnicodeTranslateError_GetReason(PyObject *exc)¶: مقدار بازگشتی: مرجع جدید. قسمتی از ABI پایدار.
ویژگی reason شیء استثنای داده‌شده را برمی‌گرداند.

int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason)¶
int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason)¶
int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason)¶: قسمتی از ABI پایدار.
ویژگی reason شیء استثنای داده‌شده را برابر reason قرار می‌دهد. در صورت موفقیت 0 و در صورت شکست -1 برمی‌گرداند.

کنترل بازگشتی¶

این دو تابع راهی برای انجام فراخوانی‌های بازگشتی ایمن در سطح C فراهم می‌کنند، هم در هسته و هم در ماژول‌های توسعه‌ای. این توابع زمانی لازم هستند که کد بازگشتی لزوماً کد پایتون را فراخوانی نکند (که عمق بازگشت خود را به‌طور خودکار پیگیری می‌کند). این توابع برای پیاده‌سازی‌های tp_call نیز لازم نیستند، زیرا پروتکل فراخوانی مدیریت بازگشت را بر عهده می‌گیرد.

int Py_EnterRecursiveCall(const char *where)¶

قسمتی از ABI پایدار از نسخه‌ی 3.9.

نقطه‌ای را نشان‌گذاری می‌کند که در آن یک فراخوانی بازگشتی در سطح C در شرف انجام است.

سپس تابع بررسی می‌کند که آیا به حد پشته رسیده است یا خیر. اگر چنین باشد، یک RecursionError تنظیم می‌شود و مقدار غیرصفر بازگردانده می‌شود. در غیر این صورت، صفر بازگردانده می‌شود.

where باید یک رشته‌ی کدگذاری‌شده با UTF-8 مانند " in instance check" باشد تا به پیام RecursionError که ناشی از محدودیت عمق بازگشت است، الحاق شود.

همچنین ملاحظه نمائید

تابع PyUnstable_ThreadState_SetStackProtection().

تغییر یافته در نسخه‌ی 3.9: این تابع اکنون در API محدود نیز در دسترس است.

void Py_LeaveRecursiveCall(void)¶: قسمتی از ABI پایدار از نسخه‌ی 3.9.
یک Py_EnterRecursiveCall() را پایان می‌دهد. باید یک‌بار برای هر فراخوانی موفق Py_EnterRecursiveCall() فراخوانی شود.

تغییر یافته در نسخه‌ی 3.9: این تابع اکنون در API محدود نیز در دسترس است.

پیاده‌سازی صحیح tp_repr برای نوع‌های ظرف نیازمند مدیریت ویژه‌ی بازگشت است. علاوه بر محافظت از پشته، tp_repr باید اشیاء را برای جلوگیری از چرخه‌ها پیگیری کند. دو تابع زیر این عملکرد را تسهیل می‌کنند. در واقع، این‌ها معادل C برای @reprlib.recursive_repr هستند.

int Py_ReprEnter(PyObject *object)¶

قسمتی از ABI پایدار.

در ابتدای پیاده‌سازی tp_repr برای تشخیص چرخه‌ها فراخوانی می‌شود.

اگر شیء قبلاً پردازش شده باشد، تابع یک عدد صحیح مثبت برمی‌گرداند. در این صورت، پیاده‌سازی tp_repr باید یک شیء رشته برگرداند که نشان‌دهنده‌ی یک چرخه است. به عنوان مثال، شیءهای dict {...} و شیءهای list [...] را برمی‌گردانند.

تابع در صورت رسیدن به حد بازگشتی، یک عدد صحیح منفی برمی‌گرداند. در این حالت، پیاده‌سازی tp_repr معمولاً باید NULL برگرداند.

در غیر این صورت، تابع صفر را برمی‌گرداند و پیاده‌سازی tp_repr می‌تواند به‌طور عادی ادامه یابد.

void Py_ReprLeave(PyObject *object)¶: قسمتی از ABI پایدار.
یک Py_ReprEnter() را به پایان می‌رساند. باید یک‌بار برای هر فراخوانی Py_ReprEnter() که صفر را برمی‌گرداند، فراخوانی شود.

int Py_GetRecursionLimit(void)¶

قسمتی از ABI پایدار.

حد بازگشتی مفسر فعلی را برمی‌گرداند. این حد را می‌توان با Py_SetRecursionLimit() تنظیم کرد. حد بازگشتی مانع از رشد بی‌نهایت پشته‌ی مفسر پایتون می‌شود.

این تابع نمی‌تواند شکست بخورد، و فراخوان‌کننده باید یک وضعیت نخ متصل را در اختیار داشته باشد.

همچنین ملاحظه نمائید

sys.getrecursionlimit()

void Py_SetRecursionLimit(int new_limit)¶

قسمتی از ABI پایدار.

حد بازگشتی را برای مفسر فعلی تنظیم کنید.

این تابع نمی‌تواند شکست بخورد، و فراخوان‌کننده باید یک وضعیت نخ متصل را در اختیار داشته باشد.

همچنین ملاحظه نمائید

sys.setrecursionlimit()

نوع‌های استثنا و هشدار¶

تمام استثناهای استاندارد پایتون و دسته‌های هشدار به‌صورت متغیرهای سراسری در دسترس هستند که نام آن‌ها PyExc_ و به دنبال آن نام استثنای پایتون است. این‌ها از نوع PyObject* هستند؛ همگی اشیای کلاس هستند.

برای کامل بودن، همه متغیرها این‌جا آمده‌اند:

نوع‌های استثنا¶

نام C	نام پایتونی
PyObject PyExc_BaseException¶ قسمتی از ABI پایدار.*	`BaseException`
PyObject PyExc_BaseExceptionGroup¶ قسمتی از ABI پایدار از نسخه‌ی 3.11.*	`BaseExceptionGroup`
PyObject PyExc_Exception¶ قسمتی از ABI پایدار.*	`Exception`
PyObject PyExc_ArithmeticError¶ قسمتی از ABI پایدار.*	`ArithmeticError`
PyObject PyExc_AssertionError¶ قسمتی از ABI پایدار.*	`AssertionError`
PyObject PyExc_AttributeError¶ قسمتی از ABI پایدار.*	`AttributeError`
PyObject PyExc_BlockingIOError¶ قسمتی از ABI پایدار از نسخه‌ی 3.7.*	`BlockingIOError`
PyObject PyExc_BrokenPipeError¶ قسمتی از ABI پایدار از نسخه‌ی 3.7.*	`BrokenPipeError`
PyObject PyExc_BufferError¶ قسمتی از ABI پایدار.*	`BufferError`
PyObject PyExc_ChildProcessError¶ قسمتی از ABI پایدار از نسخه‌ی 3.7.*	`ChildProcessError`
PyObject PyExc_ConnectionAbortedError¶ قسمتی از ABI پایدار از نسخه‌ی 3.7.*	`ConnectionAbortedError`
PyObject PyExc_ConnectionError¶ قسمتی از ABI پایدار از نسخه‌ی 3.7.*	`ConnectionError`
PyObject PyExc_ConnectionRefusedError¶ قسمتی از ABI پایدار از نسخه‌ی 3.7.*	`ConnectionRefusedError`
PyObject PyExc_ConnectionResetError¶ قسمتی از ABI پایدار از نسخه‌ی 3.7.*	`ConnectionResetError`
PyObject PyExc_EOFError¶ قسمتی از ABI پایدار.*	`EOFError`
PyObject PyExc_FileExistsError¶ قسمتی از ABI پایدار از نسخه‌ی 3.7.*	`FileExistsError`
PyObject PyExc_FileNotFoundError¶ قسمتی از ABI پایدار از نسخه‌ی 3.7.*	`FileNotFoundError`
PyObject PyExc_FloatingPointError¶ قسمتی از ABI پایدار.*	`FloatingPointError`
PyObject PyExc_GeneratorExit¶ قسمتی از ABI پایدار.*	`GeneratorExit`
PyObject PyExc_ImportError¶ قسمتی از ABI پایدار.*	`ImportError`
PyObject PyExc_IndentationError¶ قسمتی از ABI پایدار.*	`IndentationError`
PyObject PyExc_IndexError¶ قسمتی از ABI پایدار.*	`IndexError`
PyObject PyExc_InterruptedError¶ قسمتی از ABI پایدار از نسخه‌ی 3.7.*	`InterruptedError`
PyObject PyExc_IsADirectoryError¶ قسمتی از ABI پایدار از نسخه‌ی 3.7.*	`IsADirectoryError`
PyObject PyExc_KeyError¶ قسمتی از ABI پایدار.*	`KeyError`
PyObject PyExc_KeyboardInterrupt¶ قسمتی از ABI پایدار.*	`KeyboardInterrupt`
PyObject PyExc_LookupError¶ قسمتی از ABI پایدار.*	`LookupError`
PyObject PyExc_MemoryError¶ قسمتی از ABI پایدار.*	`MemoryError`
PyObject PyExc_ModuleNotFoundError¶ قسمتی از ABI پایدار از نسخه‌ی 3.6.*	`ModuleNotFoundError`
PyObject PyExc_NameError¶ قسمتی از ABI پایدار.*	`NameError`
PyObject PyExc_NotADirectoryError¶ قسمتی از ABI پایدار از نسخه‌ی 3.7.*	`NotADirectoryError`
PyObject PyExc_NotImplementedError¶ قسمتی از ABI پایدار.*	`NotImplementedError`
PyObject PyExc_OSError¶ قسمتی از ABI پایدار.*	`OSError`
PyObject PyExc_OverflowError¶ قسمتی از ABI پایدار.*	`OverflowError`
PyObject PyExc_PermissionError¶ قسمتی از ABI پایدار از نسخه‌ی 3.7.*	`PermissionError`
PyObject PyExc_ProcessLookupError¶ قسمتی از ABI پایدار از نسخه‌ی 3.7.*	`ProcessLookupError`
PyObject *PyExc_PythonFinalizationError¶	`PythonFinalizationError`
PyObject PyExc_RecursionError¶ قسمتی از ABI پایدار از نسخه‌ی 3.7.*	`RecursionError`
PyObject PyExc_ReferenceError¶ قسمتی از ABI پایدار.*	`ReferenceError`
PyObject PyExc_RuntimeError¶ قسمتی از ABI پایدار.*	`RuntimeError`
PyObject PyExc_StopAsyncIteration¶ قسمتی از ABI پایدار از نسخه‌ی 3.7.*	`StopAsyncIteration`
PyObject PyExc_StopIteration¶ قسمتی از ABI پایدار.*	`StopIteration`
PyObject PyExc_SyntaxError¶ قسمتی از ABI پایدار.*	`SyntaxError`
PyObject PyExc_SystemError¶ قسمتی از ABI پایدار.*	`SystemError`
PyObject PyExc_SystemExit¶ قسمتی از ABI پایدار.*	`SystemExit`
PyObject PyExc_TabError¶ قسمتی از ABI پایدار.*	`TabError`
PyObject PyExc_TimeoutError¶ قسمتی از ABI پایدار از نسخه‌ی 3.7.*	`TimeoutError`
PyObject PyExc_TypeError¶ قسمتی از ABI پایدار.*	`TypeError`
PyObject PyExc_UnboundLocalError¶ قسمتی از ABI پایدار.*	`UnboundLocalError`
PyObject PyExc_UnicodeDecodeError¶ قسمتی از ABI پایدار.*	`UnicodeDecodeError`
PyObject PyExc_UnicodeEncodeError¶ قسمتی از ABI پایدار.*	`UnicodeEncodeError`
PyObject PyExc_UnicodeError¶ قسمتی از ABI پایدار.*	`UnicodeError`
PyObject PyExc_UnicodeTranslateError¶ قسمتی از ABI پایدار.*	`UnicodeTranslateError`
PyObject PyExc_ValueError¶ قسمتی از ABI پایدار.*	`ValueError`
PyObject PyExc_ZeroDivisionError¶ قسمتی از ABI پایدار.*	`ZeroDivisionError`

اضافه شده در نسخه‌ی 3.3: PyExc_BlockingIOError، PyExc_BrokenPipeError، PyExc_ChildProcessError، PyExc_ConnectionError، PyExc_ConnectionAbortedError، PyExc_ConnectionRefusedError، PyExc_ConnectionResetError، PyExc_FileExistsError، PyExc_FileNotFoundError، PyExc_InterruptedError، PyExc_IsADirectoryError، PyExc_NotADirectoryError، PyExc_PermissionError، PyExc_ProcessLookupError و PyExc_TimeoutError در پی PEP 3151 معرفی شدند.

اضافه شده در نسخه‌ی 3.5: PyExc_StopAsyncIteration و PyExc_RecursionError.

اضافه شده در نسخه‌ی 3.6: PyExc_ModuleNotFoundError.

اضافه شده در نسخه‌ی 3.11: PyExc_BaseExceptionGroup.

نام‌های مستعار OSError¶

موارد زیر نام‌های مستعار سازگاری برای PyExc_OSError هستند.

تغییر یافته در نسخه‌ی 3.3: این نام‌های مستعار قبلاً نوع‌های استثنای جداگانه بودند.

نام C	نام پایتونی	یادداشت‌ها
PyObject PyExc_EnvironmentError¶ قسمتی از ABI پایدار.*	`OSError`
PyObject PyExc_IOError¶ قسمتی از ABI پایدار.*	`OSError`
PyObject PyExc_WindowsError¶ قسمتی از ABI پایدار on Windows از نسخه‌ی 3.7.*	`OSError`	[win]

یادداشت‌ها:

[win]

PyExc_WindowsError تنها در ویندوز تعریف شده است؛ برای محافظت از کدی که از این استفاده می‌کند، بررسی کنید که ماکروی پیش‌پردازنده MS_WINDOWS تعریف شده باشد.

انواع هشدار¶

نام C	نام پایتونی
PyObject PyExc_Warning¶ قسمتی از ABI پایدار.*	`Warning`
PyObject PyExc_BytesWarning¶ قسمتی از ABI پایدار.*	`BytesWarning`
PyObject PyExc_DeprecationWarning¶ قسمتی از ABI پایدار.*	`DeprecationWarning`
PyObject PyExc_EncodingWarning¶ قسمتی از ABI پایدار از نسخه‌ی 3.10.*	`EncodingWarning`
PyObject PyExc_FutureWarning¶ قسمتی از ABI پایدار.*	`FutureWarning`
PyObject PyExc_ImportWarning¶ قسمتی از ABI پایدار.*	`ImportWarning`
PyObject PyExc_PendingDeprecationWarning¶ قسمتی از ABI پایدار.*	`PendingDeprecationWarning`
PyObject PyExc_ResourceWarning¶ قسمتی از ABI پایدار از نسخه‌ی 3.7.*	`ResourceWarning`
PyObject PyExc_RuntimeWarning¶ قسمتی از ABI پایدار.*	`RuntimeWarning`
PyObject PyExc_SyntaxWarning¶ قسمتی از ABI پایدار.*	`SyntaxWarning`
PyObject PyExc_UnicodeWarning¶ قسمتی از ABI پایدار.*	`UnicodeWarning`
PyObject PyExc_UserWarning¶ قسمتی از ABI پایدار.*	`UserWarning`

اضافه شده در نسخه‌ی 3.2: PyExc_ResourceWarning.

اضافه شده در نسخه‌ی 3.10: PyExc_EncodingWarning.

ردگیری‌ها¶

PyTypeObject PyTraceBack_Type¶: قسمتی از ABI پایدار.
شیء نوع برای اشیاء ردگیری . این به‌صورت types.TracebackType در لایه‌ی پایتون در دسترس است.

int PyTraceBack_Check(PyObject *op)¶: اگر op یک شیء ردگیری باشد، مقدار true را برمی‌گرداند و در غیر این صورت مقدار false را. این تابع زیرنوع‌ها را در نظر نمی‌گیرد.

int PyTraceBack_Here(PyFrameObject *f)¶

قسمتی از ABI پایدار.

ویژگی __traceback__ روی استثنای فعلی را با یک ردگیری جدید که f را به ابتدای زنجیره‌ی موجود می‌افزاید، جایگزین کنید.

فراخوانی این تابع در حالی که استثنایی تنظیم نشده باشد، رفتار تعریف‌نشده است.

این تابع در صورت موفقیت 0 را برمی‌گرداند، و در صورت شکست -1 را همراه با یک استثنای تنظیم‌شده برمی‌گرداند.

int PyTraceBack_Print(PyObject *tb, PyObject *f)¶

قسمتی از ABI پایدار.

ردگیری tb را در پرونده f بنویسید.

این تابع در صورت موفقیت 0 را برمی‌گرداند، و در صورت شکست -1 را همراه با یک استثنای تنظیم‌شده برمی‌گرداند.

مدیریت استثنا¶

چاپ و پاک کردن¶

برخاست دادن استثناها¶

صدور هشدارها¶

پرس‌وجو از نشانگر خطا¶

مدیریت سیگنال¶

کلاس‌های استثنا¶

اشیاء استثنا¶

اشیاء استثنای یونیکد¶

کنترل بازگشتی¶

نوع‌های استثنا و هشدار¶

نوع‌های استثنا¶

نام‌های مستعار OSError¶

انواع هشدار¶

ردگیری‌ها¶

فهرست مطالب

موضوع قبلی

موضوع بعدی

این صفحه