زمینه استثنا¶

سه ویژگی در اشیای استثنا اطلاعاتی درباره زمینه‌ای که استثنا در آن پرتاب شده است فراهم می‌کنند:

BaseException.__context__¶

BaseException.__cause__¶

BaseException.__suppress_context__¶

هنگام پرتاب یک استثنای جدید در حالی که استثنای دیگری از قبل در حال رسیدگی است، ویژگی __context__ استثنای جدید به‌طور خودکار به استثنای در حال رسیدگی تنظیم می‌شود. یک استثنا ممکن است زمانی رسیدگی شود که از یک بند except یا finally، یا یک دستور with استفاده شود.

این زمینه‌ی استثنای ضمنی را می‌توان با استفاده از from همراه با raise با یک علت صریح تکمیل کرد:

raise new_exc from original_exc

عبارت پس از from باید یک استثنا یا None باشد. این مقدار به‌عنوان __cause__ روی استثنای پرتاب‌شده تنظیم می‌شود. تنظیم __cause__ همچنین به‌صورت ضمنی ویژگی __suppress_context__ را روی True تنظیم می‌کند، به‌طوری که استفاده از raise new_exc from None عملاً استثنای قدیمی را با استثنای جدید برای اهداف نمایش جایگزین می‌کند (برای مثال تبدیل KeyError به AttributeError)، در حالی که استثنای قدیمی را در __context__ برای درون‌نگری هنگام اشکال‌زدایی در دسترس نگه می‌دارد.

کد پیش‌فرض نمایش ردگیری پشته، این استثناهای زنجیره‌ای را علاوه بر ردگیری پشته خود استثنا نشان می‌دهد. یک استثنای زنجیره‌ای صریح در __cause__ همیشه در صورت وجود نمایش داده می‌شود. یک استثنای زنجیره‌ای ضمنی در __context__ تنها در صورتی نمایش داده می‌شود که __cause__ برابر None و __suppress_context__ نادرست باشد.

در هر صورت، خود استثنا همیشه پس از هرگونه استثنای زنجیره‌ای نمایش داده می‌شود، به‌طوری که خط پایانی ردگیری پشته همیشه آخرین استثنایی را که پرتاب شده است نشان می‌دهد.

ارث‌بری از استثناهای توکار¶

کد کاربر می‌تواند زیرکلاس‌هایی بسازد که از یک نوع استثنا ارث می‌برند. توصیه می‌شود برای جلوگیری از هرگونه تداخل احتمالی در نحوه‌ی مدیریت ویژگی args توسط کلاس‌های پایه، و نیز به دلیل ناسازگاری‌های احتمالی در چیدمان حافظه، در هر زمان فقط از یک نوع استثنا زیرکلاس‌گیری کنید.

کلاس‌های پایه¶

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

exception BaseException¶

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

args¶

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

with_traceback(tb)¶

این متد، tb را به‌عنوان ردگیری پشته‌ی جدید برای استثنا تنظیم می‌کند و شیء استثنا را برمی‌گرداند. پیش از در دسترس قرار گرفتن قابلیت‌های زنجیره‌سازی استثنا در PEP 3134، این متد بیشتر استفاده می‌شد. مثال زیر نشان می‌دهد که چگونه می‌توانیم یک نمونه از SomeException را به یک نمونه از OtherException تبدیل کنیم، در حالی که ردگیری پشته حفظ می‌شود. پس از پرتاب شدن، فریم جاری بر ردگیری پشته‌ی OtherException افزوده می‌شود، همان‌گونه که برای ردگیری پشته‌ی SomeException اصلی رخ می‌داد اگر اجازه می‌دادیم آن به فراخواننده منتشر شود.

try:
    ...
except SomeException:
    tb = sys.exception().__traceback__
    raise OtherException(...).with_traceback(tb)

__traceback__¶

یک فیلد قابل‌نوشتن که شیء ردگیری پشته مرتبط با این استثنا را نگه می‌دارد. همچنین ببینید: پرتاب.

add_note(note)¶

رشته note را به یادداشت‌های استثنا که در ردگیری پشته‌ی استاندارد پس از رشته‌ی استثنا نمایش داده می‌شوند، اضافه کنید. اگر note یک رشته نباشد، یک TypeError پرتاب می‌شود.

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

__notes__¶

فهرستی از یادداشت‌های این استثنا، که با add_note() افزوده شده‌اند. این ویژگی هنگام فراخوانی add_note() ایجاد می‌شود.

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

exception Exception¶

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

exception ArithmeticError¶

کلاس پایه برای آن دسته از استثناهای توکار که برای خطاهای حسابی مختلف پرتاب می‌شوند: OverflowError، ZeroDivisionError، FloatingPointError.

exception BufferError¶

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

exception LookupError¶

کلاس پایه برای استثناهایی که هنگام نامعتبر بودن یک کلید یا اندیس استفاده‌شده در یک نگاشت یا دنباله پرتاب می‌شوند: IndexError، KeyError. این استثنا می‌تواند مستقیماً توسط codecs.lookup() پرتاب شود.

استثناهای مشخص¶

استثناهای زیر، استثناهایی هستند که معمولاً پرتاب می‌شوند.

exception AssertionError¶

هنگامی که دستور assert شکست بخورد، پرتاب می‌شود.

exception AttributeError¶

هنگامی که ارجاع به ویژگی (به ارجاع‌های ویژگی مراجعه کنید) یا انتساب ناموفق باشد، پرتاب می‌شود. (هرگاه یک شیء به‌هیچ‌وجه از ارجاع به ویژگی یا انتساب ویژگی پشتیبانی نکند، TypeError پرتاب می‌شود.)

آرگومان‌های اختیاری name و obj که فقط کلیدواژه‌ای هستند، ویژگی‌های متناظر را تنظیم می‌کنند:

name¶

نام ویژگی‌ای که برای دسترسی به آن تلاش شده است.

obj¶

شیء‌ای که برای ویژگی نام‌برده‌شده به آن دسترسی پیدا شده است.

تغییر یافته در نسخه‌ی 3.10: ویژگی‌های name و obj اضافه شدند.

exception EOFError¶

زمانی پرتاب می‌شود که تابع input() بدون خواندن هیچ داده‌ای به وضعیت پایان پرونده برسد. (توجه: متدهای io.TextIOBase.read() و io.IOBase.readline() هنگام رسیدن به EOF یک رشته‌ی خالی برمی‌گردانند.)

exception FloatingPointError¶

در حال حاضر استفاده نمی‌شود.

exception GeneratorExit¶

هنگامی ایجاد می‌شود که یک تولیدگر یا هم‌روال بسته شود؛ generator.close() و coroutine.close() را ببینید. این استثنا مستقیماً از BaseException به‌جای Exception ارث می‌برد، زیرا از نظر فنی یک خطا نیست.

exception ImportError¶

هنگامی پرتاب می‌شود که دستور import در تلاش برای بارگذاری یک ماژول دچار مشکل شود. همچنین هنگامی پرتاب می‌شود که «فهرست from» در from ... import شامل نامی باشد که نمی‌توان آن را پیدا کرد.

آرگومان‌های اختیاری name و path که فقط کلیدواژه‌ای هستند، ویژگی‌های متناظر را تنظیم می‌کنند:

name¶

نام ماژولی که برای ایمپورت آن تلاش شد.

path¶

مسیر هر پرونده‌ای که باعث پرتاب استثنا شده است.

تغییر یافته در نسخه‌ی 3.3: ویژگی‌های name و path اضافه شدند.

exception ModuleNotFoundError¶

زیرکلاسی از ImportError که توسط import زمانی پرتاب می‌شود که نتوان یک ماژول را یافت. همچنین زمانی که None در sys.modules یافت شود نیز پرتاب می‌شود.

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

exception ImportCycleError¶

یک زیرکلاس از ImportError که وقتی یک ایمپورت تنبل (lazy import) به دلیل تلاش (مستقیم یا غیرمستقیم) برای ایمپورت کردن خودش شکست بخورد، بالا برده می‌شود.

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

exception IndexError¶

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

exception KeyError¶

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

exception KeyboardInterrupt¶

این استثنا زمانی پرتاب می‌شود که کاربر کلید وقفه را فشار دهد (معمولاً Control-C یا Delete). در طول اجرا، بررسی وقفه‌ها به‌طور منظم انجام می‌شود. این استثنا از BaseException ارث می‌برد تا به‌طور تصادفی توسط کدی که Exception را می‌گیرد، گرفته نشود و در نتیجه مانع از خروج مفسر نگردد.

نکته

گرفتن KeyboardInterrupt نیازمند ملاحظه ویژه است. از آنجا که ممکن است در نقاط غیرقابل‌پیش‌بینی پرتاب شود، در برخی شرایط ممکن است برنامه‌ی در حال اجرا را در وضعیتی ناسازگار باقی بگذارد. معمولاً بهتر است اجازه دهید KeyboardInterrupt برنامه را هرچه سریع‌تر پایان دهد یا کلاً از پرتاب آن اجتناب کنید. (به یادداشتی درباره‌ی هندلرهای سیگنال و استثناها مراجعه کنید.)

exception MemoryError¶

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

exception NameError¶

هنگامی پرتاب می‌شود که یک نام محلی یا سراسری یافت نشود. این مورد فقط برای نام‌های فاقد صلاحیت (unqualified) صدق می‌کند. مقدار مرتبط، پیام خطایی است که شامل نامی است که یافت نشد.

آرگومان اختیاری name که فقط به‌صورت کلیدواژه‌ای پذیرفته می‌شود، ویژگی را تنظیم می‌کند:

name¶

نام متغیری که تلاش شد به آن دسترسی پیدا شود.

تغییر یافته در نسخه‌ی 3.10: ویژگی name اضافه شد.

exception NotImplementedError¶

این استثنا از RuntimeError مشتق شده است. در کلاس‌های پایه تعریف‌شده توسط کاربر، متدهای انتزاعی باید این استثنا را زمانی پرتاب کنند که لازم باشد کلاس‌های مشتق‌شده متد را بازنویسی کنند، یا هنگامی که کلاس در حال توسعه است تا نشان دهند پیاده‌سازی واقعی هنوز باید اضافه شود.

نکته

نباید برای نشان دادن اینکه یک عملگر یا متد به‌هیچ‌وجه قرار نیست پشتیبانی شود، استفاده شود — در این حالت یا عملگر / متد را تعریف‌نشده بگذارید یا، اگر یک زیرکلاس است، آن را روی None قرار دهید.

احتیاط

NotImplementedError و NotImplemented قابل تعویض با یکدیگر نیستند. این استثنا باید فقط همان‌طور که در بالا توضیح داده شد استفاده شود؛ برای جزئیات درباره‌ی استفاده‌ی صحیح از ثابت توکار، NotImplemented را ببینید.

exception OSError([arg])¶

exception OSError(errno, strerror[, filename[, winerror[, filename2]]])

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

دومین شکل سازنده، ویژگی‌های متناظر را که در ادامه توضیح داده شده‌اند، تنظیم می‌کند. مقدار پیش‌فرض این ویژگی‌ها در صورتی که مشخص نشده باشند، None است. برای سازگاری با نسخه‌های پیشین، اگر سه آرگومان ارسال شود، ویژگی args فقط شامل یک تاپل دوتایی از دو آرگومان نخست سازنده خواهد بود.

سازنده در واقع اغلب یک زیرکلاس از OSError را برمی‌گرداند، همان‌طور که در OS exceptions در ادامه توضیح داده شده است. زیرکلاس خاص به مقدار نهایی errno بستگی دارد. این رفتار فقط زمانی رخ می‌دهد که OSError مستقیماً یا از طریق یک نام مستعار ساخته شود و هنگام ایجاد زیرکلاس به ارث نمی‌رسد.

errno¶

یک کد خطای عددی از متغیر C با نام errno.

winerror¶

در ویندوز، این به شما کد خطای بومی ویندوز را می‌دهد. در این صورت، ویژگی errno ترجمه‌ای تقریبی، در اصطلاحات POSIX، از آن کد خطای بومی است.

در ویندوز، اگر آرگومان سازنده‌ی winerror یک عدد صحیح باشد، ویژگی errno از کد خطای ویندوز تعیین می‌شود و آرگومان errno نادیده گرفته می‌شود. در سکوهای دیگر، آرگومان winerror نادیده گرفته می‌شود و ویژگی winerror وجود ندارد.

strerror¶

پیام خطای متناظر، همان‌طور که توسط سیستم‌عامل ارائه می‌شود. این پیام توسط توابع C perror() در POSIX و FormatMessage() در ویندوز قالب‌بندی می‌شود.

filename¶

filename2¶

برای استثناهایی که شامل یک مسیر سامانه فایل‌بندی هستند (مانند open() یا os.unlink())، filename نام پرونده‌ای است که به تابع داده شده است. برای توابعی که شامل دو مسیر سامانه فایل‌بندی هستند (مانند os.rename())، filename2 متناظر با دومین نام پرونده داده‌شده به تابع است.

تغییر یافته در نسخه‌ی 3.3: EnvironmentError، IOError، WindowsError، socket.error، select.error و mmap.error در OSError ادغام شده‌اند و سازنده ممکن است یک زیرکلاس برگرداند.

تغییر یافته در نسخه‌ی 3.4: ویژگی filename اکنون نام اصلی پرونده ارسال‌شده به تابع است، به‌جای نامی که به filesystem encoding and error handler کدگذاری یا از آن کدگشایی شده است. همچنین، آرگومان سازنده و ویژگی filename2 افزوده شد.

exception OverflowError¶

زمانی پرتاب می‌شود که نتیجه‌ی یک عملیات حسابی آن‌قدر بزرگ باشد که نتوان آن را نمایش داد. این حالت برای اعداد صحیح رخ نمی‌دهد (که به‌جای تسلیم شدن، MemoryError را پرتاب می‌کنند). با این حال، به دلایل تاریخی، گاهی OverflowError برای اعداد صحیحی که خارج از محدوده‌ی مورد نیاز هستند پرتاب می‌شود. به دلیل نبود استانداردسازی در مدیریت استثناهای ممیز شناور در C، بیشتر عملیات‌های ممیز شناور بررسی نمی‌شوند.

exception PythonFinalizationError¶

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

نمونه‌هایی از عملیات‌هایی که ممکن است در طول نهایی‌سازی پایتون (Python finalization) با PythonFinalizationError مسدود شوند:

• ایجاد یک نخ پایتون جدید.

• پیوستن به یک نخ daemon در حال اجرا.

• os.fork()،

• به‌دست آوردن قفل مانند threading.Lock، هنگامی که مشخص است عملیات در غیر این صورت دچار بن‌بست خواهد شد.

همچنین تابع sys.is_finalizing() را ببینید.

اضافه شده در نسخه‌ی 3.13: پیش از این، یک RuntimeError ساده پرتاب می‌شد.

تغییر یافته در نسخه‌ی 3.14: threading.Thread.join() اکنون می‌تواند این استثنا را پرتاب کند.

تغییر یافته در نسخه‌ی 3.15: این استثنا ممکن است هنگام به‌دست آوردن threading.Lock() یا threading.RLock() بالا برده شود.

exception RecursionError¶

این استثنا از RuntimeError مشتق شده است. این استثنا زمانی پرتاب می‌شود که مفسر تشخیص دهد که از حداکثر عمق بازگشت (به sys.getrecursionlimit() مراجعه کنید) فراتر رفته است.

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

exception ReferenceError¶

این استثنا زمانی پرتاب می‌شود که از یک پراکسی ارجاع ضعیف، که توسط تابع weakref.proxy() ایجاد شده است، برای دسترسی به ویژگی‌ای از شیء مورد ارجاع پس از زباله‌روبی شدن آن استفاده شود. برای اطلاعات بیشتر درباره‌ی ارجاع‌های ضعیف، ماژول weakref را ببینید.

exception RuntimeError¶

زمانی پرتاب می‌شود که خطایی تشخیص داده شود که در هیچ‌یک از دسته‌های دیگر قرار نمی‌گیرد. مقدار مرتبط، رشته‌ای است که نشان می‌دهد دقیقاً چه چیزی اشتباه پیش رفت.

exception StopIteration¶

توسط تابع توکار next() و متد __next__() از یک iterator پرتاب می‌شود تا نشان دهد که دیگر آیتمی از آن تولید نمی‌شود.

value¶

شیء استثنا دارای یک ویژگی واحد به نام value است که به‌عنوان آرگومان هنگام ساخت استثنا داده می‌شود و مقدار پیش‌فرض آن None است.

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

اگر کد یک تولیدگر به‌طور مستقیم یا غیرمستقیم StopIteration را پرتاب کند، این استثنا به RuntimeError تبدیل می‌شود (در حالی که StopIteration به‌عنوان علت استثنای جدید حفظ می‌شود).

تغییر یافته در نسخه‌ی 3.3: ویژگی value و توانایی توابع تولیدگر برای استفاده از آن جهت برگرداندن یک مقدار افزوده شد.

تغییر یافته در نسخه‌ی 3.5: تبدیل RuntimeError از طریق from __future__ import generator_stop معرفی شد، PEP 479 را ببینید.

تغییر یافته در نسخه‌ی 3.7: فعال‌سازی PEP 479 برای تمام کدها به‌صورت پیش‌فرض: خطای StopIteration که در یک تولیدگر پرتاب می‌شود، به RuntimeError تبدیل می‌شود.

exception StopAsyncIteration¶

باید توسط متد __anext__() یک شیء asynchronous iterator پرتاب شود تا تکرار متوقف شود.

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

exception SyntaxError(message, details)¶

زمانی که پارسر با یک خطای نحوی مواجه شود، پرتاب می‌شود. این ممکن است در یک دستور import، در فراخوانی توابع توکار compile()، exec()، یا eval()، یا هنگام خواندن اسکریپت اولیه یا ورودی استاندارد (همچنین به‌صورت تعاملی) رخ دهد.

str() از نمونه‌ی استثنا فقط پیام خطا را برمی‌گرداند. جزئیات یک تاپل است که اعضای آن به‌عنوان ویژگی‌های جداگانه نیز در دسترس هستند.

filename¶

نام پرونده‌ای که خطای سینتکسی در آن رخ داد.

lineno¶

شماره سطری در پرونده که خطا در آن رخ داده است. این اندیس‌گذاری ۱-مبنا است: اولین خط پرونده دارای lineno برابر ۱ است.

offset¶

ستون در سطری که خطا در آن رخ داده است. این مقدار ۱-اندیس‌گذاری‌شده است: اولین نویسه‌ی خط دارای offset برابر با ۱ است.

text¶

متن کد منبعی که در خطا دخیل است.

end_lineno¶

شماره سطری در پرونده که خطای رخ‌داده در آن به پایان می‌رسد. این مقدار از ۱ اندیس‌گذاری شده است: اولین خط پرونده lineno برابر ۱ دارد.

end_offset¶

ستونی در خط پایانی که خطا در آن پایان می‌یابد. این مقدار ۱-اندیس‌دار است: نخستین نویسه‌ی خط دارای offset برابر با ۱ است.

تغییر یافته در نسخه‌ی 3.10: ویژگی‌های end_lineno و end_offset افزوده شدند.

exception IndentationError¶

کلاس پایه برای خطاهای سینتکسی مربوط به تورفتگی نادرست. این یک زیرکلاس از SyntaxError است.

exception TabError¶

هنگامی که تورفتگی شامل استفاده‌ی ناسازگار از تب‌ها و فاصله‌ها باشد، پرتاب می‌شود. این یک زیرکلاس از IndentationError است.

exception SystemError¶

زمانی پرتاب می‌شود که مفسر یک خطای داخلی پیدا کند، اما وضعیت آن‌قدر جدی به نظر نمی‌رسد که باعث شود همه امید را از دست بدهد. مقدار مرتبط، رشته‌ای است که نشان می‌دهد چه مشکلی پیش آمده است (در اصطلاحات سطح پایین). در CPython، این استثنا ممکن است به دلیل استفاده نادرست از C API پایتون پرتاب شود، مانند برگرداندن مقدار NULL بدون تنظیم استثنا.

اگر مطمئن هستید که این استثنا تقصیر شما یا تقصیر بسته‌ای که استفاده می‌کنید نیست، باید آن را به نویسنده یا نگه‌دارنده مفسر پایتون خود گزارش دهید. حتماً نسخه مفسر پایتون (sys.version؛ این نسخه در ابتدای یک نشست تعاملی پایتون نیز چاپ می‌شود)، پیام خطای دقیق (مقدار مرتبط با استثنا) و در صورت امکان کد منبع برنامه‌ای که باعث بروز خطا شده است را گزارش دهید.

exception SystemExit¶

این استثنا توسط تابع sys.exit() پرتاب می‌شود. این استثنا به جای Exception از BaseException ارث می‌برد تا به‌طور تصادفی توسط کدی که Exception را می‌گیرد، گرفته نشود. این امکان را می‌دهد که استثنا به‌درستی به بالا منتشر شود و باعث خروج مفسر شود. هنگامی که این استثنا مدیریت نشود، مفسر پایتون خارج می‌شود؛ هیچ ردگیری پشته‌ای چاپ نمی‌شود. سازنده همان آرگومان اختیاری منتقل‌شده به sys.exit() را می‌پذیرد. اگر مقدار یک عدد صحیح باشد، وضعیت خروج سیستم را مشخص می‌کند (که به تابع exit() در C منتقل می‌شود)؛ اگر None باشد، وضعیت خروج ۰ است؛ اگر نوع دیگری داشته باشد (مانند یک رشته)، مقدار شیء چاپ می‌شود و وضعیت خروج ۱ است.

فراخوانی sys.exit() به یک استثنا تبدیل می‌شود تا هندلرهای پاک‌سازی (بندهای finally از دستورات try) بتوانند اجرا شوند، و تا یک اشکال‌زدا بتواند یک اسکریپت را بدون خطر از دست دادن کنترل اجرا کند. اگر خروج فوری به‌طور مطلق و قطعی ضروری باشد، می‌توان از تابع os._exit() استفاده کرد (برای مثال، در فرایند فرزند پس از فراخوانی os.fork()).

code¶

وضعیت خروج یا پیام خطایی که به سازنده داده می‌شود. (پیش‌فرض None است.)

exception TypeError¶

هنگامی که یک عملیات یا تابع بر شیء‌ای با نوع نامناسب اعمال شود، پرتاب می‌شود. مقدار مرتبط، رشته‌ای است که جزئیاتی درباره‌ی عدم تطابق نوع ارائه می‌دهد.

این استثنا ممکن است توسط کد کاربر پرتاب شود تا نشان دهد که عملیات تلاش‌شده روی یک شیء پشتیبانی نمی‌شود، و قرار نیست پشتیبانی شود. اگر قرار باشد یک شیء از عملیات مشخصی پشتیبانی کند اما هنوز پیاده‌سازی آن را ارائه نکرده باشد، NotImplementedError استثنای مناسب برای پرتاب است.

ارسال آرگومان‌هایی با نوع نادرست (برای مثال، ارسال یک list هنگامی که یک int انتظار می‌رود) باید منجر به TypeError شود، اما ارسال آرگومان‌هایی با مقدار نادرست (برای مثال، عددی خارج از محدوده‌های مورد انتظار) باید منجر به ValueError شود.

exception UnboundLocalError¶

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

exception UnicodeError¶

هنگامی که خطای کدگذاری یا کدگشایی مرتبط با یونیکد رخ می‌دهد، پرتاب می‌شود. این یک زیرکلاس از ValueError است.

UnicodeError دارای ویژگی‌هایی است که خطای کدگذاری یا کدگشایی را توصیف می‌کنند. برای مثال، err.object[err.start:err.end] ورودی نامعتبر خاصی را می‌دهد که کدک در پردازش آن ناموفق بوده است.

encoding¶

نام کدگذاری‌ای که خطا را پرتاب کرد.

reason¶

رشته‌ای که خطای خاص کدک را توصیف می‌کند.

object¶

شیءای که کدک در حال تلاش برای کدگذاری یا کدگشایی آن بود.

start¶

اولین اندیس داده‌های نامعتبر در object.

این مقدار نباید منفی باشد، زیرا به‌عنوان یک آفست مطلق (absolute offset) تفسیر می‌شود، اما این محدودیت در ران‌تایم اعمال نمی‌شود.

end¶

اندیس پس از آخرین داده‌ی نامعتبر در object.

این مقدار نباید منفی باشد، زیرا به‌عنوان یک آفست مطلق (absolute offset) تفسیر می‌شود، اما این محدودیت در ران‌تایم اعمال نمی‌شود.

exception UnicodeEncodeError¶

هنگامی که خطایی مرتبط با Unicode در حین کدگذاری رخ دهد، پرتاب می‌شود. این، زیرکلاسی از UnicodeError است.

exception UnicodeDecodeError¶

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

exception UnicodeTranslateError¶

هنگامی که خطای مرتبط با یونیکد در حین ترجمه رخ می‌دهد، پرتاب می‌شود. این یک زیرکلاس از UnicodeError است.

exception ValueError¶

هنگامی پرتاب می‌شود که یک عملیات یا تابع آرگومانی دریافت کند که نوع آن درست است اما مقدار آن نامناسب است، و این وضعیت با استثنای دقیق‌تری مانند IndexError توصیف نشود.

exception ZeroDivisionError¶

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

استثناهای زیر برای سازگاری با نسخه‌های پیشین حفظ شده‌اند؛ از پایتون 3.3 به بعد، آن‌ها نام‌های مستعارِ OSError هستند.

exception EnvironmentError¶

exception IOError¶

exception WindowsError¶

فقط در ویندوز در دسترس است.

هشدارها¶

استثناهای زیر به‌عنوان دسته‌های هشدار استفاده می‌شوند؛ برای جزئیات بیشتر، مستندات دسته‌های هشدار را ببینید.

exception Warning¶

کلاس پایه برای دسته‌های هشدار.

exception UserWarning¶

کلاس پایه برای هشدارهای تولیدشده توسط کد کاربر.

exception DeprecationWarning¶

کلاس پایه برای هشدارهای مربوط به ویژگی‌های منسوخ، وقتی آن هشدارها برای سایر توسعه‌دهندگان پایتون در نظر گرفته شده‌اند.

توسط فیلترهای هشدار پیش‌فرض نادیده گرفته می‌شود، مگر در ماژول __main__ (PEP 565). فعال‌سازی حالت توسعه پایتون این هشدار را نمایش می‌دهد.

سیاست منسوخ‌سازی در PEP 387 توضیح داده شده است.

exception PendingDeprecationWarning¶

کلاس پایه برای هشدارهای مربوط به قابلیت‌هایی که قدیمی شده‌اند و انتظار می‌رود در آینده منسوخ شوند، اما در حال حاضر منسوخ نیستند.

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

توسط فیلترهای هشدار پیش‌فرض نادیده گرفته می‌شود. فعال‌سازی حالت توسعه پایتون این هشدار را نمایش می‌دهد.

سیاست منسوخ‌سازی در PEP 387 توضیح داده شده است.

exception SyntaxWarning¶

کلاس پایه برای هشدارهای مربوط به سینتکس مشکوک.

این هشدار معمولاً هنگام کامپایل کد منبع پایتون نشان داده می‌شود و معمولاً هنگام اجرای کد از پیش کامپایل‌شده گزارش نمی‌شود.

exception RuntimeWarning¶

کلاس پایه برای هشدارهای مربوط به رفتار مشکوک در ران‌تایم.

exception FutureWarning¶

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

exception ImportWarning¶

کلاس پایه برای هشدارها در مورد اشتباهات احتمالی در ایمپورت ماژول‌ها.

توسط فیلترهای هشدار پیش‌فرض نادیده گرفته می‌شود. فعال‌سازی حالت توسعه پایتون این هشدار را نمایش می‌دهد.

exception UnicodeWarning¶

کلاس پایه برای هشدارهای مرتبط با یونیکد.

exception EncodingWarning¶

کلاس پایه برای هشدارهای مرتبط با کدگذاری‌ها.

برای جزئیات، فعال‌سازی اختیاری هشدار کدگذاری (EncodingWarning) را ببینید.

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

exception BytesWarning¶

کلاس پایه برای هشدارهای مرتبط با bytes و bytearray.

exception ResourceWarning¶

کلاس پایه برای هشدارهای مربوط به مصرف منابع.

توسط فیلترهای هشدار پیش‌فرض نادیده گرفته می‌شود. فعال‌سازی حالت توسعه پایتون این هشدار را نمایش می‌دهد.

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

گروه‌های استثنا¶

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

exception ExceptionGroup(msg, excs)¶

exception BaseExceptionGroup(msg, excs)¶

هر دوی این انواع استثنا، استثناهای موجود در دنباله excs را دربر می‌گیرند. پارامتر msg باید یک رشته باشد. تفاوت این دو کلاس در این است که BaseExceptionGroup از BaseException ارث می‌برد و می‌تواند هر استثنایی را دربر بگیرد، در حالی که ExceptionGroup از Exception ارث می‌برد و فقط می‌تواند زیرکلاس‌های Exception را دربر بگیرد. این طراحی به این منظور است که except Exception ExceptionGroup را بگیرد، اما BaseExceptionGroup را نگیرد.

سازنده‌ی BaseExceptionGroup اگر همه‌ی استثناهای درون آن نمونه‌هایی از Exception باشند، یک ExceptionGroup را به‌جای یک BaseExceptionGroup برمی‌گرداند، بنابراین می‌توان از آن برای خودکار کردن انتخاب استفاده کرد. از سوی دیگر، سازنده‌ی ExceptionGroup اگر یکی از استثناهای درون آن زیرکلاسی از Exception نباشد، یک TypeError را پرتاب می‌کند.

گروه‌های استثنا نسبت به نوع استثناهای درون خود عام هستند.

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

message¶

آرگومان msg برای سازنده. این یک ویژگی فقط‌خواندنی است.

exceptions¶

تاپلی از استثناهای موجود در دنباله‌ی excs که به سازنده داده‌شده است. این ویژگی فقط‌خواندنی است.

subgroup(condition)¶

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

شرط می‌تواند یک نوع استثنا یا تاپلی از انواع استثنا باشد، که در این صورت هر استثنا با استفاده از همان بررسی‌ای که در بند except استفاده می‌شود، برای تطابق بررسی می‌شود. شرط همچنین می‌تواند یک شیء فراخوانی‌پذیر (به‌جز یک شیء نوع) باشد که یک استثنا را به‌عنوان تنها آرگومان خود می‌پذیرد و برای استثناهایی که باید در زیرگروه باشند، مقدار true برمی‌گرداند.

ساختار تودرتوی استثنای جاری در نتیجه حفظ می‌شود؛ مقادیر فیلدهای message، __traceback__، __cause__، __context__ و __notes__ آن نیز حفظ می‌شوند. گروه‌های تودرتوی خالی از نتیجه حذف می‌شوند.

شرط برای تمام استثناهای درون گروه استثنای تودرتو بررسی می‌شود، از جمله گروه استثنای سطح بالا و هر گروه استثنای تودرتویی. اگر شرط برای چنین گروه استثنایی برقرار باشد، آن گروه به‌طور کامل در نتیجه گنجانده می‌شود.

اضافه شده در نسخه‌ی 3.13: condition می‌تواند هر شیء فراخوانی‌پذیر باشد که یک شیء نوع نباشد.

split(condition)¶

مانند subgroup()، اما جفت (match, rest) را برمی‌گرداند که در آن match برابر با subgroup(condition) است و rest بخش باقی‌مانده‌ی غیرمنطبق است.

derive(excs)¶

یک گروه استثنا با همان message برمی‌گرداند، اما استثناهای درون excs را در بر می‌گیرد.

این متد توسط subgroup() و split() استفاده می‌شود، که در زمینه‌های مختلف برای تجزیه یک گروه استثنا به کار می‌روند. یک زیرکلاس باید آن را بازنویسی کند تا subgroup() و split() به‌جای ExceptionGroup نمونه‌هایی از زیرکلاس را برگردانند.

subgroup() و split() ویژگی‌های __traceback__، __cause__، __context__ و __notes__ را از گروه استثنای اصلی به گروهی که derive() آن را برمی‌گرداند کپی می‌کنند، بنابراین نیازی نیست این ویژگی‌ها توسط derive() به‌روزرسانی شوند.

>>> class MyGroup(ExceptionGroup):
...     def derive(self, excs):
...         return MyGroup(self.message, excs)
...
>>> e = MyGroup("eg", [ValueError(1), TypeError(2)])
>>> e.add_note("a note")
>>> e.__context__ = Exception("context")
>>> e.__cause__ = Exception("cause")
>>> try:
...    raise e
... except Exception as e:
...    exc = e
...
>>> match, rest = exc.split(ValueError)
>>> exc, exc.__context__, exc.__cause__, exc.__notes__
(MyGroup('eg', [ValueError(1), TypeError(2)]), Exception('context'), Exception('cause'), ['a note'])
>>> match, match.__context__, match.__cause__, match.__notes__
(MyGroup('eg', [ValueError(1)]), Exception('context'), Exception('cause'), ['a note'])
>>> rest, rest.__context__, rest.__cause__, rest.__notes__
(MyGroup('eg', [TypeError(2)]), Exception('context'), Exception('cause'), ['a note'])
>>> exc.__traceback__ is match.__traceback__ is rest.__traceback__
True

توجه داشته باشید که BaseExceptionGroup، __new__() را تعریف می‌کند، بنابراین زیرکلاس‌هایی که به امضای سازنده‌ای متفاوت نیاز دارند، باید به‌جای __init__()، آن را بازنویسی کنند. برای مثال، کد زیر یک زیرکلاس از گروه استثنا تعریف می‌کند که یک exit_code می‌پذیرد و پیام گروه را از روی آن می‌سازد.

class Errors(ExceptionGroup):
   def __new__(cls, errors, exit_code):
      self = super().__new__(Errors, f"exit code: {exit_code}", errors)
      self.exit_code = exit_code
      return self

   def derive(self, excs):
      return Errors(excs, self.exit_code)

مانند ExceptionGroup، هر زیرکلاسی از BaseExceptionGroup که همچنین زیرکلاسی از Exception باشد، فقط می‌تواند نمونه‌هایی از Exception را در بر بگیرد.

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

سلسله‌مراتب استثنا¶

سلسله‌مراتب کلاس برای استثناهای توکار به صورت زیر است:

BaseException
 ├── BaseExceptionGroup
 ├── GeneratorExit
 ├── KeyboardInterrupt
 ├── SystemExit
 └── Exception
      ├── ArithmeticError
      │    ├── FloatingPointError
      │    ├── OverflowError
      │    └── ZeroDivisionError
      ├── AssertionError
      ├── AttributeError
      ├── BufferError
      ├── EOFError
      ├── ExceptionGroup [BaseExceptionGroup]
      ├── ImportError
      │    └── ImportCycleError
      │    └── ModuleNotFoundError
      ├── LookupError
      │    ├── IndexError
      │    └── KeyError
      ├── MemoryError
      ├── NameError
      │    └── UnboundLocalError
      ├── OSError
      │    ├── BlockingIOError
      │    ├── ChildProcessError
      │    ├── ConnectionError
      │    │    ├── BrokenPipeError
      │    │    ├── ConnectionAbortedError
      │    │    ├── ConnectionRefusedError
      │    │    └── ConnectionResetError
      │    ├── FileExistsError
      │    ├── FileNotFoundError
      │    ├── InterruptedError
      │    ├── IsADirectoryError
      │    ├── NotADirectoryError
      │    ├── PermissionError
      │    ├── ProcessLookupError
      │    └── TimeoutError
      ├── ReferenceError
      ├── RuntimeError
      │    ├── NotImplementedError
      │    ├── PythonFinalizationError
      │    └── RecursionError
      ├── StopAsyncIteration
      ├── StopIteration
      ├── SyntaxError
      │    └── IndentationError
      │         └── TabError
      ├── SystemError
      ├── TypeError
      ├── ValueError
      │    └── UnicodeError
      │         ├── UnicodeDecodeError
      │         ├── UnicodeEncodeError
      │         └── UnicodeTranslateError
      └── Warning
           ├── BytesWarning
           ├── DeprecationWarning
           ├── EncodingWarning
           ├── FutureWarning
           ├── ImportWarning
           ├── PendingDeprecationWarning
           ├── ResourceWarning
           ├── RuntimeWarning
           ├── SyntaxWarning
           ├── UnicodeWarning
           └── UserWarning