خواندن پیام‌های خطا

چرا خواندن پیام خطا مهم است؟

پیام‌های خطا (Error Messages) در پایتون شبیه «نقشهٔ گنج» هستند:
به شما می‌گویند کجا و تقریباً چه چیزی اشتباه است.
مبتدی‌ها معمولاً وقتی خطا می‌بینند می‌ترسند و فقط دکمهٔ اجرا را دوباره می‌زنند؛
ولی برنامه‌نویس خوب کسی است که پیام خطا را می‌خواند و تفسیر می‌کند.

در این بخش تمرکز ما روی این است که:

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

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

ساختار کلی پیام خطای پایتون (Traceback)

وقتی برنامه‌ٔ شما در پایتون خطا می‌دهد، معمولاً چیزی شبیه این می‌بینید:

Traceback (most recent call last):
  File "test.py", line 3, in <module>
    x = 10 / 0
ZeroDivisionError: division by zero

تقریباً همهٔ پیام‌های خطا این ساختار را دارند:

1. خط اول: Traceback (most recent call last):
   یعنی «ردیابی (تاریخچه) فراخوانی‌ها از جدیدترین مورد».
2. چند خط «مکان خطا»
• فایل کجاست (File "test.py")
• در کدام خط (line 3)
• در کدام بخش (in <module> یا نام تابع)
• خود خط کد (x = 10 / 0)
3. خط آخر: نوع خطا و توضیح کوتاه
• نوع خطا: ZeroDivisionError
• توضیح: division by zero

مهم‌ترین بخش‌ها برای شما:

• شمارهٔ خط: تا بدانید کجا را باید نگاه کنید.
• نوع خطا: سرنخ اصلی از اینکه چه چیزی «نوعاً» مشکل دارد.
• توضیح کوتاه: معمولاً جمله‌ای انگلیسی که معنی‌اش نسبتاً ساده است.

---

پیدا کردن خط مشکل‌دار از روی پیام خطا

مثال:

Traceback (most recent call last):
  File "main.py", line 5, in <module>
    print("نتیجه:", reslt)
NameError: name 'reslt' is not defined

چطور بخوانیم؟

1. فایل: main.py
2. خط: line 5
3. کد در آن خط: print("نتیجه:", reslt)
4. نوع خطا: NameError
5. توضیح: name 'reslt' is not defined

از این اطلاعات چه نتیجه می‌گیریم؟

• سرنخ ۱: NameError یعنی مشکلی با نام متغیر/چیز استفاده‌شده وجود دارد.
• سرنخ ۲: متن: 'reslt' is not defined
  یعنی متغیر reslt قبلاً تعریف نشده، یا اشتباه تایپی است.

احتمالاً می‌خواستید بنویسید result نه reslt.

مثال‌های رایج و نحوهٔ خواندن آن‌ها

در این بخش چند نمونهٔ رایج از پیام‌های خطا و روش خواندن‌شان را می‌بینید.
هدف این نیست که همهٔ این نوع‌ها را عمیقاً یاد بگیرید،
بلکه یاد بگیرید چطور از خود پیام «سرنخ» بگیرید.

۱. SyntaxError (مشکل در نوشتن دستور)

File "test.py", line 2
    if x > 10
             ^
SyntaxError: invalid syntax

نکات:

• خط: line 2
• نوع: SyntaxError
• علامت ^ زیر‌نویس: جایی را که پایتون «مشکوک» است نشان می‌دهد.
• پیام: invalid syntax یعنی «دستور نوشتاری درست نیست».

این‌جا مشکل: بعد از if x > 10 دو‌نقطه : جا افتاده است.

ترفند: همیشه دنبال ^ (کلاهک) در پیام باشید؛
گاهی دقیقاً همان‌جاست، گاهی یک کاراکتر قبل یا بعدش.

۲. IndentationError (مشکل تورفتگی)

File "test.py", line 3
    print("Hello")
    ^
IndentationError: unexpected indent

• نوع: IndentationError
• پیام: unexpected indent یعنی «تورفتگی غیرمنتظره».

مشخص است که در خط ۳، فاصله/تب اشتباه است.
باید ببینید آیا خطی که تورفته، واقعاً باید داخل یک بلوک (if، for، …) باشد یا نه.

۳. NameError (نام ناشناخته)

File "calc.py", line 4, in <module>
    print(result)
NameError: name 'result' is not defined

• نوع: NameError
• پیام: name 'result' is not defined

به‌طور کلی:

• متغیر را اشتباه نوشته‌اید.
• یا قبل از استفاده، آن را مقداردهی نکرده‌اید.
• یا در محدوده‌ای (scope) هستید که به آن دسترسی ندارید (جزئیات در فصل توابع).

۴. TypeError (نوع داده نامناسب)

File "app.py", line 6, in <module>
    print("جمع:", 5 + "3")
TypeError: unsupported operand type(s) for +: 'int' and 'str'

• نوع: TypeError
• پیام: unsupported operand type(s) for +: 'int' and 'str'
  یعنی عملگر + بین int و str پشتیبانی نمی‌شود.

اینجا 5 عدد است و "3" رشته؛ باید یا تبدیل نوع کنید، یا روش دیگری استفاده کنید.

۵. ValueError (مقدار نامعتبر)

File "app.py", line 3, in <module>
    age = int("abc")
ValueError: invalid literal for int() with base 10: 'abc'

• نوع: ValueError
• پیام: invalid literal for int() ... 'abc'
  یعنی مقدار 'abc' برای تبدیل به عدد صحیح معتبر نیست.

معمولاً:

• ورودی کاربر را به عدد تبدیل می‌کنید و او چیزی غیرعددی می‌نویسد.
• باید ورودی را بررسی کنید یا پیام مناسب بدهید.

۶. IndexError و KeyError

IndexError (ایندکس خارج از محدوده)

nums = [1, 2, 3]
print(nums[5])

پیام:

IndexError: list index out of range

• یعنی به اندیس (index) ای دسترسی می‌خواهید که در لیست وجود ندارد.

KeyError (کلید ناموجود در دیکشنری)

user = {"name": "Ali"}
print(user["age"])

پیام:

KeyError: 'age'

• یعنی کلید 'age' در دیکشنری یافت نشده است.

---

خواندن بخش «File» و «line» و «in»

بخش وسط traceback معمولاً شبیه این است:

Traceback (most recent call last):
  File "main.py", line 10, in process_data
    result = calculate(x)
  File "main.py", line 5, in calculate
    return x / y
ZeroDivisionError: division by zero

چطور بخوانیم؟

• ردیف ۱:
  File "main.py", line 10, in process_data
  یعنی در تابع process_data در خط ۱۰ این فایل، تابع calculate صدا زده شده.
• ردیف ۲:
  File "main.py", line 5, in calculate
  یعنی در خود تابع calculate در خط ۵، خط مشکل‌دار وجود دارد.
• در نهایت نوع خطا: ZeroDivisionError

نکته مهم:

• خط واقعی خطا معمولاً در پایین‌ترین بخش لیست (آخرین File ...) است.
• خطوط بالایی فقط «مسیر رسیدن» به آن خط را نشان می‌دهند.

برای مبتدی‌ها معمولاً:

• به پایین‌ترین خط File نگاه کنید
• کد همان خط را در ویرایشگر باز کنید.
• نوع خطا + آن خط را با هم ببینید.

---

خواندن خطاهای حالت تعاملی (REPL / ترمینال پایتون)

اگر در حالت تعاملی (مثلاً در ترمینال پایتون) کد می‌نویسید، پیام خطا ممکن است شبیه این باشد:

>>> 10 / 0
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ZeroDivisionError: division by zero

• File "<stdin>" یعنی این خط مستقیم در ورودی تعاملی (نه در فایل) نوشته شده است.
• line 1 یعنی همان خطی که شما وارد کرده‌اید.

ساختار بقیه همان است.

نکات عملی برای تمرین خواندن پیام خطا

۱. پیام را *کامل* بخوانید

اشتباه رایج: فقط پایین پیام را ببینید و سریع کد را حدسی تغییر دهید.

کار درست:

1. از بالا به پایین بخوانید.
2. فایل و خط اصلی را پیدا کنید.
3. نوع خطا را در نظر بگیرید.
4. متن انگلیسی را تا حد ممکن معنی کنید (معمولاً ساده است).

۲. روی «نوع خطا» حساس باشید

وقتی چند بار این پیام‌ها را ببینید:

• SyntaxError → احتمالاً یک چیز جا افتاده است (:، پرانتز، کوتیشن، …)
• IndentationError → فاصله‌گذاری/تب مشکل دارد.
• NameError → متغیر/نامی تعریف نشده است.
• TypeError → نوع داده‌ها برای عملی که می‌خواهید، مناسب نیست.
• ValueError → مقدار ورودی نامعتبر است.
• IndexError / KeyError → چیزی را از لیست/دیکشنری می‌خواهید که وجود ندارد.

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

۳. استفاده از پیام خطا در جست‌وجو

اگر مشکل را نفهمیدید:

1. متن خطای آخر را انتخاب کنید (مثلاً TypeError: unsupported operand type(s) for +: 'int' and 'str').
2. در گوگل یا چت‌جی‌پی‌تی جست‌وجو کنید (به همراه «python»).
3. نتیجه‌ها معمولاً مثال و توضیح دارند.

نکته: اطلاعات شخصی (مسیرهای عجیب، نام کاربر، API key و…) را در متن نگذارید.

تمرین‌های پیشنهادی (خودآزمایی)

برای تسلط روی خواندن پیام خطا، تمرین‌های زیر را انجام دهید:

1. کد زیر را اجرا کنید و پیام خطا را خط‌به‌خط بخوانید و تفسیر کنید:

   print("شروع برنامه")
   x = 5
   y = "10"
   print(x + y)
   print("پایان برنامه")

• نوع خطا چیست؟
• در کدام خط؟
• پیام چه می‌گوید؟

2. خودتان چند خط کد عمداً اشتباه بنویسید:
• یک if بدون :
• یک for بدون تورفتگی
• استفاده از متغیر اشتباه‌تایپ‌شده
• تقسیم بر صفر

هر بار:

• پیام خطا را بخوانید.
• حدس بزنید مشکل کجاست.
• بعد اصلاح کنید و دوباره اجرا کنید.

3. وقتی در پروژه‌های بعدی این دوره با خطا روبه‌رو می‌شوید،
   همیشه قبل از هر کاری این چهار سؤال را از روی پیام خطا جواب دهید:
• نوع خطا چیست؟
• در کدام فایل؟
• در کدام خط؟
• کدام خط کد واقعاً مشکل‌دار است؟

اگر این عادت را از الان بسازید، مرحلهٔ «اشکال‌زدایی» برایتان خیلی کم‌استرس‌تر خواهد شد.