آموزش کامل Traceback در پایتون (خطایابی و دیباگ)

سطح مقدماتی (Beginner Level)

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

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

۱. ساختار کلی Traceback

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

1. خط آخر: نوع خطا (Exception Type) و توضیحات آن را نشان می‌دهد.
2. خطوط بالاتر: مسیری که برنامه طی کرده تا به خطا برسد (Call Stack). فایل‌ها، توابع و شماره خطوط در اینجا لیست می‌شوند.

۲. خطاهای زمان اجرا (Runtime Errors)

این خطاها زمانی رخ می‌دهند که سینتکس کد درست است، اما در زمان اجرا اتفاق غیرممکنی می‌افتد (مثل تقسیم بر صفر).

مثال اول: خطای تقسیم بر صفر (ZeroDivisionError)

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

مثال دوم: خطای نام‌گذاری (NameError)

این خطا زمانی رخ می‌دهد که شما از متغیری استفاده کنید که تعریف نشده است (یا املای آن غلط است).

۳. خطاهای سینتکسی (Syntax Errors)

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

نکته: از آنجا که این کد اصلا اجرا نمی‌شود (Parsable نیست)، از بلوک python (استاتیک) استفاده می‌کنیم.

# Example 3: Missing colon inside a function snippet
def check_positive(number)  # Missing :
    if number > 0:
        return True

# Example 4: Mismatched parentheses
print("Hello World"
# Missing closing parenthesis

سطح پیشرفته (Professional Level)

در سطح حرفه‌ای، Traceback تنها یک گزارش خطا نیست، بلکه ابزاری برای مهندسی نرم‌افزار است. ما باید بدانیم چگونه Stack Trace را در برنامه‌های بزرگ تحلیل کنیم، چگونه با ماژول traceback کار کنیم و چگونه خطاها را بدون متوقف کردن برنامه لاگ (Log) کنیم.

۱. تحلیل Call Stack در توابع تو در تو (Nested Calls)

در برنامه‌های واقعی، خطا ممکن است در عمق چندین تابع رخ دهد. Traceback تمام سلسله مراتب فراخوانی‌ها را نشان می‌دهد. آخرین فریم (Frame) جایی است که خطا رخ داده، اما ممکن است دلیل خطا در فریم‌های بالاتر (داده ورودی غلط) باشد.

۲. مدیریت و چاپ Traceback بدون کرش کردن (ماژول traceback)

گاهی اوقات می‌خواهید برنامه شما به کار خود ادامه دهد، اما همچنان می‌خواهید متن کامل Traceback را برای دیباگ کردن ذخیره یا چاپ کنید. استفاده از print(e) در بلوک try-except فقط پیام خطا را می‌دهد، نه Stack Trace کامل را. برای دسترسی به متن کامل از ماژول traceback استفاده می‌کنیم.

مثال اول: استفاده از traceback.print_exc()

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

مثال دوم: دریافت متن Traceback به صورت رشته با traceback.format_exc()

اگر بخواهید خطا را در دیتابیس ذخیره کنید یا به یک فایل Log بفرستید، نیاز دارید Traceback را به عنوان یک رشته (String) دریافت کنید.

۳. نکات فنی و Best Practiceها

1. خطا را نبلعید (Swallowing Errors): هرگز از except: pass خالی استفاده نکنید. این کار Traceback را مخفی می‌کند و دیباگ کردن را غیرممکن می‌سازد.
2. Custom Exceptions: برای پروژه‌های بزرگ، Exceptionهای اختصاصی بسازید تا Traceback معنای تجاری (Business Logic) بیشتری داشته باشد.

# Example 4: Custom Exception (Static definition)
class InsufficientFundsError(Exception):
    """Raised when the withdrawal amount is more than the balance."""
    pass

def withdraw(amount, balance):
    if amount > balance:
        raise InsufficientFundsError(f"Cannot withdraw {amount} from {balance}")