traceback --- چاپ یا بازیابی ردگیری پشته

کد منبع: Lib/traceback.py

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

این ماژول از اشیای ردگیری پشته استفاده می‌کند — این‌ها اشیایی از نوع types.TracebackType هستند که به فیلد __traceback__ در نمونه‌های BaseException اختصاص داده می‌شوند.

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

ماژول faulthandler

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

ماژول pdb

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

API ماژول را می‌توان به دو بخش تقسیم کرد:

  • توابع سطح ماژول که عملکرد پایه‌ای ارائه می‌دهند، برای بررسی تعاملی استثناها و ردگیری‌های پشته مفید هستند.

  • کلاس TracebackException و کلاس‌های کمکی آن StackSummary و FrameSummary. این کلاس‌ها هم انعطاف‌پذیری بیشتر در خروجی تولیدشده و هم توانایی ذخیره‌ی اطلاعات لازم برای قالب‌بندی بعدی را بدون نگه‌داشتن ارجاع به اشیاء واقعی استثنا و ردگیری پشته ارائه می‌دهند.

اضافه شده در نسخه‌ی 3.13: خروجی به‌طور پیش‌فرض رنگی است و می‌توان آن را با استفاده از متغیرهای محیطی کنترل کرد.

توابع سطح ماژول

traceback.print_tb(tb, limit=None, file=None)

اگر limit مثبت باشد، حداکثر limit ورودی از ردگیری پشته را از شیء ردگیری پشته tb (با شروع از فریم فراخواننده) چاپ می‌کند. در غیر این صورت، آخرین abs(limit) ورودی را چاپ می‌کند. اگر limit حذف‌شده باشد یا None باشد، تمام ورودی‌ها چاپ می‌شوند. اگر file حذف‌شده باشد یا None باشد، خروجی به sys.stderr ارسال می‌شود؛ در غیر این صورت، باید یک پرونده باز یا file-like object باشد که خروجی را دریافت کند.

توجه

معنای پارامتر limit با معنای sys.tracebacklimit متفاوت است. مقدار منفی limit متناظر با یک مقدار مثبت از sys.tracebacklimit است، در حالی که نمی‌توان رفتار یک مقدار مثبت limit را با sys.tracebacklimit به دست آورد.

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

traceback.print_exception(exc, /, [value, tb, ]limit=None, file=None, chain=True)

اطلاعات استثنا و ورودی‌های ردگیری پشته را از شیء ردگیری پشته tb در file چاپ می‌کند. این در موارد زیر با print_tb() تفاوت دارد:

  • اگر tb None نباشد، سرآیند Traceback (most recent call last): را چاپ می‌کند

  • نوع استثنا و مقدار را پس از ردگیری پشته چاپ می‌کند

  • اگر type(value) SyntaxError باشد و value قالب مناسبی داشته باشد، سطری را که خطای نحوی در آن رخ داده است، همراه با یک نشانک که موقعیت تقریبی خطا را نشان می‌دهد، چاپ می‌کند.

از پایتون 3.10 به بعد، به جای ارسال value و tb، می‌توان یک شیء استثنا را به‌عنوان اولین آرگومان ارسال کرد. اگر value و tb ارائه شوند، اولین آرگومان نادیده گرفته می‌شود تا سازگاری با نسخه‌های پیشین فراهم شود.

آرگومان اختیاری limit همان معنای مورد استفاده در print_tb() را دارد. اگر chain درست باشد (پیش‌فرض)، استثناهای زنجیره‌ای (ویژگی‌های __cause__ یا __context__ استثنا) نیز چاپ خواهند شد، همان‌گونه که خود مفسر هنگام چاپ یک استثنای مدیریت‌نشده عمل می‌کند.

تغییر یافته در نسخه‌ی 3.5: آرگومان etype نادیده گرفته می‌شود و از روی نوع value استنتاج می‌شود.

تغییر یافته در نسخه‌ی 3.10: پارامتر etype به exc تغییر نام یافته است و اکنون فقط جایگاهی است.

traceback.print_exc(limit=None, file=None, chain=True)

این میان‌بری برای print_exception(sys.exception(), limit=limit, file=file, chain=chain) است.

traceback.print_last(limit=None, file=None, chain=True)

این شکل کوتاه‌شده‌ای از print_exception(sys.last_exc, limit=limit, file=file, chain=chain) است. به‌طور کلی، این فقط پس از آن کار خواهد کرد که یک استثنا به اعلان تعاملی رسیده باشد (به sys.last_exc مراجعه کنید).

traceback.print_stack(f=None, limit=None, file=None)

اگر limit مثبت باشد، حداکثر limit ورودی ردگیری پشته (شروع از نقطه فراخوانی) چاپ می‌شود. در غیر این صورت، آخرین abs(limit) ورودی چاپ می‌شود. اگر limit حذف شده باشد یا None باشد، همه ورودی‌ها چاپ می‌شوند. می‌توان از آرگومان اختیاری f برای مشخص کردن یک فریم پشته جایگزین برای شروع استفاده کرد. آرگومان اختیاری file همان معنایی را دارد که در print_tb() دارد.

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

traceback.extract_tb(tb, limit=None)

یک شیء StackSummary بازمی‌گرداند که نشان‌دهنده‌ی فهرستی از آیتم‌های «پیش‌پردازش‌شده» ردگیری پشته است که از شیء ردگیری tb استخراج شده‌اند. این شیء برای قالب‌بندی جایگزین ردگیری‌های پشته مفید است. آرگومان اختیاری limit همان معنای مورد استفاده در print_tb() را دارد. یک آیتم «پیش‌پردازش‌شده» ردگیری پشته، یک شیء FrameSummary با ویژگی‌هایی است که نشان‌دهنده‌ی اطلاعاتی هستند که معمولاً برای یک ردگیری پشته چاپ می‌شود.

traceback.extract_stack(f=None, limit=None)

ردگیری پشته‌ی خام را از فریم پشته فعلی استخراج کنید. مقدار بازگشتی همان قالب extract_tb() را دارد. آرگومان‌های اختیاری f و limit همان معنایی را دارند که در print_stack() دارند.

traceback.print_list(extracted_list, file=None)

فهرستی از تاپل‌ها را که توسط extract_tb() یا extract_stack() برگردانده شده است، به‌صورت یک ردگیری پشته قالب‌بندی‌شده در پرونده داده‌شده چاپ می‌کند. اگر file برابر None باشد، خروجی در sys.stderr نوشته می‌شود.

traceback.format_list(extracted_list)

با دریافت فهرستی از تاپل‌ها یا اشیای FrameSummary که توسط extract_tb() یا extract_stack() بازگردانده شده است، فهرستی از رشته‌ها را که برای چاپ آماده هستند، برمی‌گرداند. هر رشته در فهرست حاصل، با آیتم دارای همان اندیس در فهرست آرگومان متناظر است. هر رشته با یک خط جدید پایان می‌یابد؛ برای آن آیتم‌هایی که خط متن منبع آن‌ها None نیست، رشته‌ها ممکن است حاوی سطرهای جدید داخلی نیز باشند.

traceback.format_exception_only(exc, /, [value, ]*, show_group=False)

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

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

هنگامی که show_group برابر True باشد و استثنا نمونه‌ای از BaseExceptionGroup باشد، استثناهای تودرتو نیز به‌صورت بازگشتی، با تورفتگی متناسب با عمق تودرتوی آن‌ها، گنجانده می‌شوند.

تغییر یافته در نسخه‌ی 3.10: پارامتر etype به exc تغییر نام یافته است و اکنون فقط جایگاهی است.

تغییر یافته در نسخه‌ی 3.11: فهرست برگردانده‌شده اکنون شامل هرگونه notes پیوست‌شده به استثنا می‌شود.

تغییر یافته در نسخه‌ی 3.13: پارامتر show_group افزوده شد.

traceback.format_exception(exc, /, [value, tb, ]limit=None, chain=True)

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

تغییر یافته در نسخه‌ی 3.5: آرگومان etype نادیده گرفته می‌شود و از روی نوع value استنتاج می‌شود.

تغییر یافته در نسخه‌ی 3.10: رفتار و امضای این تابع برای مطابقت با print_exception() تغییر کرده‌اند.

traceback.format_exc(limit=None, chain=True)

این مانند print_exc(limit) است، اما به‌جای چاپ در یک پرونده، یک رشته را برمی‌گرداند.

traceback.format_tb(tb, limit=None)

میان‌بری برای format_list(extract_tb(tb, limit)).

traceback.format_stack(f=None, limit=None)

میان‌بری برای format_list(extract_stack(f, limit)).

traceback.clear_frames(tb)

با فراخوانی متد clear() هر شیء فریم، متغیرهای محلی تمام فریم‌های پشته در ردگیری پشته tb را پاک می‌کند.

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

traceback.walk_stack(f)

پشته‌ای را با دنبال کردن f.f_back از فریم داده‌شده می‌پیماید و فریم و شماره‌ی خط هر فریم را تولید می‌کند. اگر f برابر None باشد، از پشته‌ی جاری استفاده می‌شود. این تابع کمکی همراه با StackSummary.extract() استفاده می‌شود.

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

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

traceback.walk_tb(tb)

یک ردگیری پشته را با دنبال کردن tb_next پیمایش می‌کند و برای هر فریم، فریم و شماره خط آن را تولید می‌کند. این تابع کمکی به همراه StackSummary.extract() استفاده می‌شود.

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

اشیای TracebackException

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

اشیای TracebackException از استثناهای واقعی ایجاد می‌شوند تا داده‌ها را برای چاپ در زمان بعدی ثبت کنند. آن‌ها با پرهیز از نگه‌داشتن ارجاع به اشیای traceback و frame، روش سبک‌تری برای ذخیره‌سازی این اطلاعات ارائه می‌دهند. علاوه بر این، در مقایسه با توابع سطح ماژول توصیف‌شده در بالا، گزینه‌های بیشتری برای پیکربندی خروجی در اختیار می‌گذارند.

class traceback.TracebackException(exc_type, exc_value, exc_traceback, *, limit=None, lookup_lines=True, capture_locals=False, compact=False, max_group_width=15, max_group_depth=10)

یک استثنا را برای نمایش بعدی ضبط کنید. معنای limit، lookup_lines و capture_locals همانند کلاس StackSummary است.

اگر compact درست باشد، فقط داده‌های مورد نیاز متد format() از TracebackException در ویژگی‌های کلاس ذخیره می‌شوند. به‌ویژه، فیلد __context__ تنها زمانی محاسبه می‌شود که __cause__ برابر None باشد و __suppress_context__ نادرست باشد.

توجه داشته باشید که هنگامی که متغیرهای محلی ثبت می‌شوند، آن‌ها نیز در ردگیری پشته نمایش داده می‌شوند.

max_group_width و max_group_depth قالب‌بندی گروه‌های استثنا را کنترل می‌کنند (به BaseExceptionGroup مراجعه کنید). عمق به سطح تودرتویی گروه اشاره دارد و عرض به اندازه‌ی آرایه‌ی exceptions یک گروه استثنای واحد اشاره دارد. هرگاه از یکی از این محدودیت‌ها فراتر رود، خروجی قالب‌بندی‌شده بریده می‌شود.

تغییر یافته در نسخه‌ی 3.10: پارامتر compact افزوده شد.

تغییر یافته در نسخه‌ی 3.11: پارامترهای max_group_width و max_group_depth افزوده شدند.

__cause__

یک TracebackException از __cause__ اصلی.

__context__

یک TracebackException از __context__ اصلی.

exceptions

اگر self نمایانگر یک ExceptionGroup باشد، این فیلد شامل فهرستی از نمونه‌های TracebackException است که استثناهای تودرتو را نشان می‌دهند. در غیر این صورت، None است.

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

__suppress_context__

مقدار __suppress_context__ از استثنای اصلی.

__notes__

مقدار __notes__ از استثنای اصلی، یا None اگر استثنا هیچ یادداشتی نداشته باشد. اگر None نباشد، در ردگیری پشته پس از رشته‌ی استثنا قالب‌بندی می‌شود.

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

stack

یک StackSummary که ردگیری پشته را نشان می‌دهد.

exc_type

کلاس استثنای اصلی.

منسوخ شده از نسخه‌ی 3.13.

exc_type_str

نمایش رشته‌ای کلاس استثنای اصلی.

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

filename

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

lineno

برای خطاهای سینتکسی - شماره‌ی سطری که خطا در آن رخ داده است.

end_lineno

برای خطاهای نحوی - شماره خط پایانی که خطا در آن رخ داده است. اگر موجود نباشد، می‌تواند None باشد.

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

text

برای خطاهای سینتکسی — متنی که خطا در آن رخ داده است.

offset

برای خطاهای نحوی - آفست در متنی که خطا در آن رخ داده است.

end_offset

برای خطاهای سینتکسی - آفست انتهایی در متنی که خطا در آن رخ داده است. اگر موجود نباشد، می‌تواند None باشد.

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

msg

برای خطاهای سینتکسی - پیام خطای کامپایلر.

classmethod from_exception(exc, *, limit=None, lookup_lines=True, capture_locals=False, compact=False, max_group_width=15, max_group_depth=10)

یک استثنا را برای نمایش (rendering) بعدی ثبت می‌کند. limit، lookup_lines و capture_locals همانند کلاس StackSummary هستند.

توجه داشته باشید که هنگامی که متغیرهای محلی ثبت می‌شوند، آن‌ها نیز در ردگیری پشته نمایش داده می‌شوند.

print(*, file=None, chain=True)

اطلاعات استثنا برگردانده‌شده توسط format() را در file (پیش‌فرض sys.stderr) چاپ می‌کند.

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

format(*, chain=True)

استثنا را قالب‌بندی کنید.

اگر chain برابر True نباشد، __cause__ و __context__ قالب‌بندی نمی‌شوند.

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

format_exception_only(*, show_group=False)

بخش استثنا از ردگیری پشته را قالب‌بندی کنید.

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

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

هنگامی که show_group برابر True باشد و استثنا نمونه‌ای از BaseExceptionGroup باشد، استثناهای تودرتو نیز به‌صورت بازگشتی، با تورفتگی متناسب با عمق تودرتوی آن‌ها، گنجانده می‌شوند.

تغییر یافته در نسخه‌ی 3.11: اکنون notes مربوط به استثنا در خروجی گنجانده شده‌اند.

تغییر یافته در نسخه‌ی 3.13: پارامتر show_group اضافه شد.

اشیای StackSummary

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

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

class traceback.StackSummary
classmethod extract(frame_gen, *, limit=None, lookup_lines=True, capture_locals=False)

یک شیء StackSummary را از یک تولیدگر فریم بسازید (مانند آنچه توسط walk_stack() یا walk_tb() بازگردانده می‌شود).

اگر limit ارائه شود، تنها همین تعداد فریم از frame_gen گرفته می‌شود. اگر lookup_lines برابر False باشد، اشیای FrameSummary برگردانده‌شده هنوز سطرهای خود را نخوانده‌اند؛ این امر هزینه‌ی ایجاد StackSummary را کمتر می‌کند (که اگر ممکن است خود آن واقعاً قالب‌بندی نشود، ممکن است ارزشمند باشد). اگر capture_locals برابر True باشد، متغیرهای محلی در هر FrameSummary به‌صورت بازنمایی‌های شیء گرفته می‌شوند.

تغییر یافته در نسخه‌ی 3.12: استثناهای پرتاب‌شده از repr() روی یک متغیر محلی (هنگامی که capture_locals برابر True است) دیگر به فراخواننده منتقل نمی‌شوند.

classmethod from_list(a_list)

یک شیء StackSummary را از یک فهرست ارائه‌شده از اشیای FrameSummary یا فهرستی از تاپل‌ها به‌سبک قدیمی بسازید. هر تاپل باید یک تاپل با ۴ عضو باشد که عناصر آن filename، lineno، name و line هستند.

format()

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

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

تغییر یافته در نسخه‌ی 3.6: دنباله‌های طولانی از فریم‌های تکراری اکنون خلاصه می‌شوند.

format_frame_summary(frame_summary)

رشته‌ای برای چاپ یکی از فریم‌های درگیر در پشته برمی‌گرداند. این متد برای هر شیء FrameSummary که قرار است توسط StackSummary.format() چاپ شود، فراخوانی می‌شود. اگر None را برگرداند، آن فریم از خروجی حذف می‌شود.

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

اشیاء FrameSummary

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

یک شیء FrameSummary نشان‌دهنده‌ی یک فریم در یک ردگیری است.

class traceback.FrameSummary(filename, lineno, name, *, lookup_line=True, locals=None, line=None, end_lineno=None, colno=None, end_colno=None)

نمایانگر یک فریم واحد در ردگیری پشته یا پشته‌ای است که در حال قالب‌بندی یا چاپ است. ممکن است به‌صورت اختیاری یک نسخه‌ی رشته‌ای‌شده از متغیرهای محلی فریم در آن گنجانده شده باشد. اگر lookup_line برابر False باشد، تا زمانی که به ویژگی line شیء FrameSummary دسترسی پیدا نشود، کد منبع جستجو نمی‌شود (که این اتفاق هنگام تبدیل آن به یک tuple نیز رخ می‌دهد). می‌توان line را مستقیماً ارائه کرد، که این کار به‌طور کلی از جستجوی خط جلوگیری می‌کند. locals یک نگاشت اختیاری از متغیرهای محلی است، و در صورت ارائه، بازنمایی‌های متغیرها برای نمایش بعدی در خلاصه ذخیره می‌شوند.

نمونه‌های FrameSummary دارای ویژگی‌های زیر هستند:

filename

نام پرونده کد منبع برای این فریم. معادل دسترسی به f.f_code.co_filename در یک شیء فریم f است.

lineno

شماره‌ی خط کد منبع برای این فریم .

name

معادل با دسترسی به f.f_code.co_name روی یک شیء فریم f.

line

رشته‌ای که کد منبع این فریم را نشان می‌دهد، که فضای سفید ابتدا و انتهای آن حذف شده است. اگر کد منبع در دسترس نباشد، مقدار آن None است.

end_lineno

آخرین شماره خط کد منبع این فریم. به‌طور پیش‌فرض، این مقدار روی lineno تنظیم می‌شود و اندیس‌گذاری از ۱ آغاز می‌شود.

تغییر یافته در نسخه‌ی 3.13: مقدار پیش‌فرض از None به lineno تغییر کرد.

colno

شماره‌ی ستون کد منبع این فریم. به‌طور پیش‌فرض، مقدار آن None است و اندیس‌گذاری از ۰ شروع می‌شود.

end_colno

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

نمونه‌هایی از استفاده از توابع سطح ماژول

این مثال ساده یک حلقه خواندن-ارزیابی-چاپ (read-eval-print loop) پایه را پیاده‌سازی می‌کند، شبیه به (اما کمتر مفید از) حلقه مفسر تعاملی استاندارد پایتون. برای پیاده‌سازی کامل‌تر حلقه مفسر، به ماژول code مراجعه کنید.

import sys, traceback

def run_user_code(envdir):
    source = input(">>> ")
    try:
        exec(source, envdir)
    except Exception:
        print("Exception in user code:")
        print("-"*60)
        traceback.print_exc(file=sys.stdout)
        print("-"*60)

envdir = {}
while True:
    run_user_code(envdir)

مثال زیر روش‌های مختلف برای چاپ و قالب‌بندی استثنا و ردگیری را نشان می‌دهد:

import sys, traceback

def lumberjack():
    bright_side_of_life()

def bright_side_of_life():
    return tuple()[0]

try:
    lumberjack()
except IndexError as exc:
    print("*** print_tb:")
    traceback.print_tb(exc.__traceback__, limit=1, file=sys.stdout)
    print("*** print_exception:")
    traceback.print_exception(exc, limit=2, file=sys.stdout)
    print("*** print_exc:")
    traceback.print_exc(limit=2, file=sys.stdout)
    print("*** format_exc, first and last line:")
    formatted_lines = traceback.format_exc().splitlines()
    print(formatted_lines[0])
    print(formatted_lines[-1])
    print("*** format_exception:")
    print(repr(traceback.format_exception(exc)))
    print("*** extract_tb:")
    print(repr(traceback.extract_tb(exc.__traceback__)))
    print("*** format_tb:")
    print(repr(traceback.format_tb(exc.__traceback__)))
    print("*** tb_lineno:", exc.__traceback__.tb_lineno)

خروجی این مثال به چیزی شبیه به این خواهد بود:

*** print_tb:
  File "<doctest...>", line 10, in <module>
    lumberjack()
    ~~~~~~~~~~^^
*** print_exception:
Traceback (most recent call last):
  File "<doctest...>", line 10, in <module>
    lumberjack()
    ~~~~~~~~~~^^
  File "<doctest...>", line 4, in lumberjack
    bright_side_of_life()
    ~~~~~~~~~~~~~~~~~~~^^
IndexError: tuple index out of range
*** print_exc:
Traceback (most recent call last):
  File "<doctest...>", line 10, in <module>
    lumberjack()
    ~~~~~~~~~~^^
  File "<doctest...>", line 4, in lumberjack
    bright_side_of_life()
    ~~~~~~~~~~~~~~~~~~~^^
IndexError: tuple index out of range
*** format_exc, first and last line:
Traceback (most recent call last):
IndexError: tuple index out of range
*** format_exception:
['Traceback (most recent call last):\n',
 '  File "<doctest default[0]>", line 10, in <module>\n    lumberjack()\n    ~~~~~~~~~~^^\n',
 '  File "<doctest default[0]>", line 4, in lumberjack\n    bright_side_of_life()\n    ~~~~~~~~~~~~~~~~~~~^^\n',
 '  File "<doctest default[0]>", line 7, in bright_side_of_life\n    return tuple()[0]\n           ~~~~~~~^^^\n',
 'IndexError: tuple index out of range\n']
*** extract_tb:
[<FrameSummary file <doctest...>, line 10 in <module>>,
 <FrameSummary file <doctest...>, line 4 in lumberjack>,
 <FrameSummary file <doctest...>, line 7 in bright_side_of_life>]
*** format_tb:
['  File "<doctest default[0]>", line 10, in <module>\n    lumberjack()\n    ~~~~~~~~~~^^\n',
 '  File "<doctest default[0]>", line 4, in lumberjack\n    bright_side_of_life()\n    ~~~~~~~~~~~~~~~~~~~^^\n',
 '  File "<doctest default[0]>", line 7, in bright_side_of_life\n    return tuple()[0]\n           ~~~~~~~^^^\n']
*** tb_lineno: 10

مثال زیر روش‌های مختلف چاپ و قالب‌بندی ردگیری پشته را نشان می‌دهد:

>>> import traceback
>>> def another_function():
...     lumberstack()
...
>>> def lumberstack():
...     traceback.print_stack()
...     print(repr(traceback.extract_stack()))
...     print(repr(traceback.format_stack()))
...
>>> another_function()
  File "<doctest>", line 10, in <module>
    another_function()
  File "<doctest>", line 3, in another_function
    lumberstack()
  File "<doctest>", line 6, in lumberstack
    traceback.print_stack()
[('<doctest>', 10, '<module>', 'another_function()'),
 ('<doctest>', 3, 'another_function', 'lumberstack()'),
 ('<doctest>', 7, 'lumberstack', 'print(repr(traceback.extract_stack()))')]
['  File "<doctest>", line 10, in <module>\n    another_function()\n',
 '  File "<doctest>", line 3, in another_function\n    lumberstack()\n',
 '  File "<doctest>", line 8, in lumberstack\n    print(repr(traceback.format_stack()))\n']

این آخرین مثال، چند تابع قالب‌بندی پایانی را نشان می‌دهد:

>>> import traceback
>>> traceback.format_list([('spam.py', 3, '<module>', 'spam.eggs()'),
...                        ('eggs.py', 42, 'eggs', 'return "bacon"')])
['  File "spam.py", line 3, in <module>\n    spam.eggs()\n',
 '  File "eggs.py", line 42, in eggs\n    return "bacon"\n']
>>> an_error = IndexError('tuple index out of range')
>>> traceback.format_exception_only(an_error)
['IndexError: tuple index out of range\n']

نمونه‌هایی از استفاده از TracebackException

با کلاس کمکی، گزینه‌های بیشتری در اختیار داریم:

>>> import sys
>>> from traceback import TracebackException
>>>
>>> def lumberjack():
...     bright_side_of_life()
...
>>> def bright_side_of_life():
...     t = "bright", "side", "of", "life"
...     return t[5]
...
>>> try:
...     lumberjack()
... except IndexError as e:
...     exc = e
...
>>> try:
...     try:
...         lumberjack()
...     except:
...         1/0
... except Exception as e:
...     chained_exc = e
...
>>> # limit works as with the module-level functions
>>> TracebackException.from_exception(exc, limit=-2).print()
Traceback (most recent call last):
  File "<python-input-1>", line 6, in lumberjack
    bright_side_of_life()
    ~~~~~~~~~~~~~~~~~~~^^
  File "<python-input-1>", line 10, in bright_side_of_life
    return t[5]
           ~^^^
IndexError: tuple index out of range

>>> # capture_locals adds local variables in frames
>>> TracebackException.from_exception(exc, limit=-2, capture_locals=True).print()
Traceback (most recent call last):
  File "<python-input-1>", line 6, in lumberjack
    bright_side_of_life()
    ~~~~~~~~~~~~~~~~~~~^^
  File "<python-input-1>", line 10, in bright_side_of_life
    return t[5]
           ~^^^
    t = ("bright", "side", "of", "life")
IndexError: tuple index out of range

>>> # The *chain* kwarg to print() controls whether chained
>>> # exceptions are displayed
>>> TracebackException.from_exception(chained_exc).print()
Traceback (most recent call last):
  File "<python-input-19>", line 4, in <module>
    lumberjack()
    ~~~~~~~~~~^^
  File "<python-input-8>", line 7, in lumberjack
    bright_side_of_life()
    ~~~~~~~~~~~~~~~~~~~^^
  File "<python-input-8>", line 11, in bright_side_of_life
    return t[5]
           ~^^^
IndexError: tuple index out of range

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "<python-input-19>", line 6, in <module>
    1/0
    ~^~
ZeroDivisionError: division by zero

>>> TracebackException.from_exception(chained_exc).print(chain=False)
Traceback (most recent call last):
  File "<python-input-19>", line 6, in <module>
    1/0
    ~^~
ZeroDivisionError: division by zero