منابع ترجمه · Python Built-ins · فصل ۴

استثناهای درون‌ساخت (مرجع درون‌ساخت‌های پایتون)

۲۷ دقیقه مطالعه · به‌روزرسانی ۳ آبان ۱۴۰۵

منبع اصلی: Python Built-ins, Chapter 4: Built-in Exceptions — Python Software Foundation

💡 این صفحه مثل یک نوت‌بوک Jupyter است: متغیر و تابعی که در یک سلول تعریف شود، در سلول‌های بعدی همین صفحه در دسترس است. سلول‌ها را به ترتیب اجرا کنید، یا با «⏮ تا اینجا» همهٔ سلول‌های قبلیِ اجرانشده را یک‌جا اجرا کنید.

در پایتون، همهٔ استثناها باید نمونه‌ای از کلاسی باشند که از BaseException مشتق شده است. در دستور try با بند except که یک کلاس مشخص را نام می‌برد، آن بند هر کلاس استثنای مشتق‌شده از آن کلاس را هم مدیریت می‌کند (اما کلاس‌های استثنایی را که خود آن از آن‌ها مشتق شده نه). دو کلاس استثنا که از طریق زیرکلاس‌سازی به هم مرتبط نیستند هرگز هم‌ارز نیستند، حتی اگر نام یکسانی داشته باشند.

استثناهای درون‌ساختی که در این فصل فهرست شده‌اند می‌توانند توسط مفسر یا توابع درون‌ساخت تولید شوند. جز در مواردی که ذکر شده، یک «مقدار وابسته (associated value)» دارند که علت دقیق خطا را نشان می‌دهد. این ممکن است یک رشته یا تاپلی از چند قطعه اطلاعات باشد (مثلاً یک کد خطا و رشته‌ای که آن کد را توضیح می‌دهد). مقدار وابسته معمولاً به‌عنوان آرگومان به سازندهٔ کلاس استثنا داده می‌شود.

کد کاربر می‌تواند استثناهای درون‌ساخت را پرتاب کند. این را می‌توان برای آزمودن یک مدیر استثنا یا گزارش یک وضعیت خطا «درست مثل» وضعیتی که مفسر همان استثنا را پرتاب می‌کند به کار برد؛ اما حواستان باشد که چیزی مانع از پرتاب خطای نامناسب توسط کد کاربر نمی‌شود.

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

بافت استثنا (Exception context)

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

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__ در دسترس می‌گذارد.

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

در هر دو حالت، خود استثنا همیشه بعد از هر استثنای زنجیره‌شده نشان داده می‌شود تا آخرین خط traceback همیشه آخرین استثنای پرتاب‌شده را نشان دهد.

ارث‌بری از استثناهای درون‌ساخت

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

جزئیات پیاده‌سازی (CPython): بیشتر استثناهای درون‌ساخت برای کارایی در C پیاده‌سازی شده‌اند، Objects/exceptions.c را ببینید. برخی چیدمان حافظهٔ سفارشی دارند که ساختن زیرکلاسی را که از چند نوع استثنا ارث می‌برد ناممکن می‌کند. چیدمان حافظهٔ یک نوع جزئیات پیاده‌سازی است و ممکن است بین نسخه‌های پایتون تغییر کند و در آینده به تعارض‌های جدید بیانجامد. بنابراین توصیه می‌شود زیرکلاس‌سازی از چند نوع استثنا به‌کلی اجتناب شود.

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

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

`exception BaseException`

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

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

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

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

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

add_note(note) : رشتهٔ note را به یادداشت‌های استثنا که در traceback استاندارد بعد از رشتهٔ استثنا ظاهر می‌شوند اضافه می‌کند. اگر note رشته نباشد TypeError پرتاب می‌شود.

افزوده‌شده در نسخهٔ ۳٫۱۱.

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

افزوده‌شده در نسخهٔ ۳٫۱۱.

`exception Exception`

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

`exception ArithmeticError`

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

`exception BufferError`

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

`exception LookupError`

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

استثناهای مشخص (Concrete exceptions)

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

`exception AssertionError`

وقتی دستور assert شکست بخورد پرتاب می‌شود.

`exception AttributeError`

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

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

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

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

وقتی ممکن باشد، name و obj به‌طور خودکار تنظیم می‌شوند.

تغییر در نسخهٔ ۳٫۱۰: ویژگی‌های name و obj افزوده شدند.

`exception EOFError`

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

`exception FloatingPointError`

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

`exception GeneratorExit`

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

`exception ImportError`

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

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

name : نام ماژولی که تلاش شد import شود.

path : مسیر هر فایلی که استثنا را برانگیخت.

تغییر در نسخهٔ ۳٫۳: ویژگی‌های name و path افزوده شدند.

`exception ModuleNotFoundError`

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

افزوده‌شده در نسخهٔ ۳٫۶.

`exception ImportCycleError`

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

افزوده‌شده در نسخهٔ ۳٫۱۵.

`exception IndexError`

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

`exception KeyError`

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

`exception KeyboardInterrupt`

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

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

`exception MemoryError`

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

`exception NameError`

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

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

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

تغییر در نسخهٔ ۳٫۱۰: ویژگی name افزوده شد.

`exception NotImplementedError`

این استثنا از RuntimeError مشتق شده است. در کلاس‌های پایهٔ تعریف‌شده توسط کاربر، متدهای انتزاعی (abstract) باید وقتی نیاز دارند کلاس‌های مشتق‌شده متد را بازنویسی کنند، یا در طول توسعهٔ کلاس برای نشان دادن اینکه پیاده‌سازی واقعی هنوز باید افزوده شود، این استثنا را پرتاب کنند.

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

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

`exception OSError([arg])`

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

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

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

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

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

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

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

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

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

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

تغییر در نسخهٔ ۳٫۴: ویژگی filename اکنون نام فایل اصلی داده‌شده به تابع است، به‌جای نامی که به/از رمزگذاری و مدیر خطای سیستم فایل رمزگذاری یا رمزگشایی شده باشد. همچنین آرگومان سازنده و ویژگی filename2 افزوده شد.

`exception OverflowError`

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

`exception PythonFinalizationError`

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

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

ساختن نخ (thread) جدید پایتون.
join کردن یک نخ daemon در حال اجرا.
os.fork().
گرفتن قفلی مانند threading.Lock، وقتی معلوم است که عملیات در غیر این صورت به بن‌بست (deadlock) می‌انجامد.

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

افزوده‌شده در نسخهٔ ۳٫۱۳: پیش‌تر RuntimeError ساده پرتاب می‌شد.

تغییر در نسخهٔ ۳٫۱۴: threading.Thread.join() اکنون می‌تواند این استثنا را پرتاب کند.

تغییر در نسخهٔ ۳٫۱۵: این استثنا ممکن است هنگام گرفتن threading.Lock یا threading.RLock پرتاب شود.

`exception RecursionError`

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

افزوده‌شده در نسخهٔ ۳٫۵: پیش‌تر RuntimeError ساده پرتاب می‌شد.

`exception ReferenceError`

این استثنا وقتی پرتاب می‌شود که از یک پروکسی ارجاع ضعیف (weak reference)، ساخته‌شده با تابع weakref.proxy()، برای دسترسی به ویژگی مرجع (referent) پس از جمع‌آوری آن توسط زباله‌روب (garbage collector) استفاده شود. برای اطلاعات بیشتر دربارهٔ ارجاع‌های ضعیف ماژول weakref را ببینید.

`exception RuntimeError`

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

`exception StopIteration`

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

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

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

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

تغییر در نسخهٔ ۳٫۳: ویژگی value و توانایی استفاده از آن برای بازگرداندن مقدار توسط توابع مولد افزوده شد.

تغییر در نسخهٔ ۳٫۵: تبدیل به RuntimeError از طریق from __future__ import generator_stop معرفی شد؛ PEP 479 را ببینید.

تغییر در نسخهٔ ۳٫۷: PEP 479 برای همهٔ کدها به‌طور پیش‌فرض فعال شد: خطای StopIteration پرتاب‌شده در مولد به RuntimeError تبدیل می‌شود.

`exception StopAsyncIteration`

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

افزوده‌شده در نسخهٔ ۳٫۵.

`exception SyntaxError(message, details)`

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

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

filename : نام فایلی که خطای نحوی در آن رخ داده.

lineno : شمارهٔ خطی در فایل که خطا در آن رخ داده. این از ۱ شروع می‌شود: خط اول فایل lineno برابر ۱ دارد.

offset : ستونی در خط که خطا در آن رخ داده. این از ۱ شروع می‌شود: نویسهٔ اول در خط offset برابر ۱ دارد.

text : متن کد منبع مرتبط با خطا.

end_lineno : شمارهٔ خطی در فایل که خطا در آن پایان می‌یابد. این از ۱ شروع می‌شود: خط اول فایل lineno برابر ۱ دارد.

end_offset : ستون در خط پایانی که خطا در آن پایان می‌یابد. این از ۱ شروع می‌شود: نویسهٔ اول در خط offset برابر ۱ دارد.

برای خطاها در فیلدهای f-string، پیام با «f-string: » پیشوند می‌گیرد و offsetها، offsetهایی در متنی هستند که از عبارت جایگزین ساخته شده است. برای مثال، کامپایل f'Bad {a b} field' این ویژگی args را می‌دهد: ('f-string: ...', ('', 1, 2, '(a b)\n', 1, 5)).

تغییر در نسخهٔ ۳٫۱۰: ویژگی‌های end_lineno و end_offset افزوده شدند.

`exception IndentationError`

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

`exception TabError`

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

`exception SystemError`

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

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

`exception SystemExit`

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

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

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

`exception TypeError`

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

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

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

`exception UnboundLocalError`

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

`exception UnicodeError`

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

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

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

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

object : شیئی که codec تلاش می‌کرد آن را رمزگذاری یا رمزگشایی کند.

start : اولین اندیس دادهٔ نامعتبر در object.

این مقدار نباید منفی باشد چون به‌عنوان offset مطلق تفسیر می‌شود، اما این محدودیت در زمان اجرا اعمال نمی‌شود.

end : اندیس بعد از آخرین دادهٔ نامعتبر در object.

این مقدار نباید منفی باشد چون به‌عنوان offset مطلق تفسیر می‌شود، اما این محدودیت در زمان اجرا اعمال نمی‌شود.

`exception UnicodeEncodeError`

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

`exception UnicodeDecodeError`

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

`exception UnicodeTranslateError`

وقتی خطای مرتبط با یونیکد در طول ترجمه (translating) رخ دهد پرتاب می‌شود. این زیرکلاسی از UnicodeError است.

`exception ValueError`

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

`exception ZeroDivisionError`

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

استثناهای زیر برای سازگاری با نسخه‌های پیشین نگه داشته شده‌اند؛ از پایتون ۳٫۳ به بعد، نام‌های مستعار OSError هستند.

`exception EnvironmentError`

`exception IOError`

`exception WindowsError`

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

استثناهای OS (OS exceptions)

استثناهای زیر زیرکلاس‌های OSError هستند؛ بسته به کد خطای سیستم پرتاب می‌شوند.

`exception BlockingIOError`

وقتی عملیاتی روی شیئی (مثلاً سوکت) که برای عملیات غیرمسدودکننده (non-blocking) تنظیم شده مسدود می‌شد پرتاب می‌شود. متناظر با errnoهای EAGAIN، EALREADY، EWOULDBLOCK و EINPROGRESS.

علاوه بر ویژگی‌های OSError، BlockingIOError می‌تواند یک ویژگی بیشتر داشته باشد:

characters_written : عدد صحیحی که تعداد بایت‌های نوشته‌شده در جریان پیش از مسدود شدن را دارد. این ویژگی هنگام استفاده از کلاس‌های I/O بافردار ماژول io در دسترس است.

`exception ChildProcessError`

وقتی عملیاتی روی فرایند فرزند شکست بخورد پرتاب می‌شود. متناظر با errno برابر ECHILD.

`exception ConnectionError`

کلاس پایه برای مسائل مرتبط با اتصال.

زیرکلاس‌ها BrokenPipeError، ConnectionAbortedError، ConnectionRefusedError و ConnectionResetError هستند.

`exception BrokenPipeError`

زیرکلاسی از ConnectionError، وقتی تلاش برای نوشتن روی لوله (pipe) پرتاب می‌شود که انتهای دیگر آن بسته شده، یا تلاش برای نوشتن روی سوکتی که برای نوشتن خاموش (shutdown) شده است. متناظر با errnoهای EPIPE و ESHUTDOWN.

`exception ConnectionAbortedError`

زیرکلاسی از ConnectionError، وقتی تلاش اتصال توسط طرف مقابل لغو (abort) شود پرتاب می‌شود. متناظر با errno برابر ECONNABORTED.

`exception ConnectionRefusedError`

زیرکلاسی از ConnectionError، وقتی تلاش اتصال توسط طرف مقابل رد شود پرتاب می‌شود. متناظر با errno برابر ECONNREFUSED.

`exception ConnectionResetError`

زیرکلاسی از ConnectionError، وقتی اتصال توسط طرف مقابل بازنشانی (reset) شود پرتاب می‌شود. متناظر با errno برابر ECONNRESET.

`exception FileExistsError`

وقتی تلاش برای ساختن فایل یا پوشه‌ای شود که از قبل وجود دارد پرتاب می‌شود. متناظر با errno برابر EEXIST.

`exception FileNotFoundError`

وقتی فایل یا پوشه‌ای درخواست شود اما وجود نداشته باشد پرتاب می‌شود. متناظر با errno برابر ENOENT.

`exception InterruptedError`

وقتی فراخوانی سیستمی توسط سیگنال ورودی قطع شود پرتاب می‌شود. متناظر با errno برابر EINTR.

تغییر در نسخهٔ ۳٫۵: پایتون اکنون وقتی فراخوانی سیستمی توسط سیگنال قطع شود، به‌جای پرتاب InterruptedError آن را دوباره تلاش می‌کند، مگر اینکه مدیر سیگنال استثنا پرتاب کند (برای دلیل آن PEP 475 را ببینید).

`exception IsADirectoryError`

وقتی عملیات فایل (مانند os.remove()) روی یک پوشه درخواست شود پرتاب می‌شود. متناظر با errno برابر EISDIR.

`exception NotADirectoryError`

وقتی عملیات پوشه (مانند os.listdir()) روی چیزی که پوشه نیست درخواست شود پرتاب می‌شود. در بیشتر پلتفرم‌های POSIX، ممکن است وقتی عملیاتی تلاش می‌کند فایلی غیر از پوشه را طوری باز کند یا پیمایش کند که گویی پوشه است نیز پرتاب شود. متناظر با errno برابر ENOTDIR.

`exception PermissionError`

وقتی تلاش می‌شود عملیاتی بدون حقوق دسترسی کافی — مثلاً مجوزهای سیستم فایل — اجرا شود پرتاب می‌شود. متناظر با errnoهای EACCES، EPERM و ENOTCAPABLE.

تغییر در نسخهٔ ۳٫۱۱٫۱: ENOTCAPABLE در WASI اکنون به PermissionError نگاشت می‌شود.

`exception ProcessLookupError`

وقتی فرایند داده‌شده وجود نداشته باشد پرتاب می‌شود. متناظر با errno برابر ESRCH.

`exception TimeoutError`

وقتی تابع سیستمی در سطح سیستم زمان‌بندی‌اش تمام شود (timeout) پرتاب می‌شود. متناظر با errno برابر ETIMEDOUT.

افزوده‌شده در نسخهٔ ۳٫۳: همهٔ زیرکلاس‌های OSError بالا افزوده شدند.

همچنین ببینید: PEP 3151 - بازطراحی سلسله‌مراتب استثناهای OS و IO

هشدارها (Warnings)

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

`exception Warning`

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

`exception UserWarning`

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

`exception DeprecationWarning`

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

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

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

`exception PendingDeprecationWarning`

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

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

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

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

`exception SyntaxWarning`

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

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

`exception RuntimeWarning`

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

`exception FutureWarning`

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

`exception ImportWarning`

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

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

`exception UnicodeWarning`

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

`exception EncodingWarning`

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

برای جزئیات هشدار رمزگذاری را ببینید.

افزوده‌شده در نسخهٔ ۳٫۱۰.

`exception BytesWarning`

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

`exception ResourceWarning`

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

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

افزوده‌شده در نسخهٔ ۳٫۲.

گروه‌های استثنا (Exception groups)

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

`exception ExceptionGroup(msg, excs)`

`exception BaseExceptionGroup(msg, excs)`

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

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

گروه‌های استثنا نسبت به نوع استثناهای موجود در خود جنریک (generic) هستند.

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

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

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

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

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

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

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

افزوده‌شده در نسخهٔ ۳٫۱۳: condition می‌تواند هر callableی باشد که شیء نوع نیست.

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 را بپوشاند.

افزوده‌شده در نسخهٔ ۳٫۱۱.

سلسله‌مراتب استثنا (Exception hierarchy)

سلسله‌مراتب کلاس‌های استثناهای درون‌ساخت این است:

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