# فصل ۰۸ — خطا دشمن نیست: خواندنِ traceback

<div dir="rtl">

# فصل ۰۸ — خطا دشمن نیست: خواندنِ traceback

## در این فصل چه یاد می‌گیری

هر برنامه‌نویسی، از روزِ اول تا آخرِ عمر، خطا می‌گیرد. چیزی که تازه‌کار را از حرفه‌ای جدا می‌کند این نیست که یکی خطا می‌گیرد و دیگری نه — این است که حرفه‌ای در ده ثانیه می‌فهمد خطا چه می‌گوید. در این فصل یاد می‌گیری آن متنِ قرمزِ چندخطی را از کدام سرش بخوانی، شش خطای پرتکرارِ پایتون را از روی پیامشان بشناسی، و با `try`/`except` خطاهای **قابلِ‌پیش‌بینی** را مدیریت کنی بدونِ اینکه خطاهای واقعی را پنهان کنی.

![یک نردبانِ برش‌خورده که هر پله‌اش یک قابِ خالی است و یک ذره‌بین روی پایین‌ترین پله ایستاده](/lesson-assets/t1-s08-errors/prompt/01-image-traceback-ladder.png)

آخر این فصل می‌توانی:

- یک `traceback` را از پایین به بالا بخوانی و بگویی خطا کجا و چرا رخ داده
- شش خطای رایجِ پایتون را از روی پیامشان تشخیص بدهی
- با `try`/`except` یک خطای پیش‌بینی‌شده را مدیریت کنی
- بگویی چرا `except` بدونِ نامِ خطا یک اشتباهِ جدی است

## قبل از شروع

**از فصل ۷:** تابع، `return`، و اینکه تابع می‌تواند تابعِ دیگری را صدا بزند.

**از فصل ۲ تا ۶:** پیام‌های `TypeError`، `IndexError` و `KeyError` را جسته‌گریخته دیده‌ای؛ اینجا مرتبشان می‌کنیم.

> 📓 **نوت‌بوک:** [نوت‌بوک این فصل را در Colab باز کن](/notebooks/sarnakh/term-1-python-basics/session-08-errors.ipynb) — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

## ۱. یک خطای واقعی، با تابع

اول یک تابعِ سالم بساز:

</div>

```python
def average(numbers):
    """میانگینِ یک فهرست عدد."""
    return sum(numbers) / len(numbers)

print(average([10, 20, 30]))
```

<div dir="rtl">

</div>

```text
20.0
```

<div dir="rtl">

حالا در یک سلولِ **خالی** همین تابع را با فهرستِ خالی صدا بزن:

</div>

```python-broken
print(average([]))
```

<div dir="rtl">

</div>

```text
---------------------------------------------------------------------------
ZeroDivisionError                         Traceback (most recent call last)
Cell In[2], line 1
----> 1 print(average([]))

Cell In[1], line 3, in average(numbers)
      1 def average(numbers):
      2     """میانگینِ یک فهرست عدد."""
----> 3     return sum(numbers) / len(numbers)

ZeroDivisionError: division by zero
```

<div dir="rtl">

این همان چیزی است که **`traceback`** نامیده می‌شود. حجمش ترسناک است ولی ساختارش کاملاً منظم است.

## ۲. از پایین بخوانش

**قاعدهٔ طلایی: `traceback` را از خطِ آخر شروع کن.**

خطِ آخر همیشه دو تکه دارد: **نامِ خطا** و **توضیحش**. اینجا `ZeroDivisionError: division by zero` — تقسیم بر صفر. در نود درصدِ موارد همین یک خط کافی است تا بفهمی چه شده.

اگر نبود، حالا به بالا نگاه کن. آن خط‌های وسط، **مسیرِ صدا زدن** را نشان می‌دهند، از بیرونی‌ترین به درونی‌ترین:

- `Cell In[2], line 1` — تو `print(average([]))` را صدا زدی.
- `Cell In[1], line 3, in average` — و داخلِ تابعِ `average`، خطِ ۳، مشکل رخ داد.

فلشِ `---->` دقیقاً روی خطی است که در هر مرحله مقصر بوده. پس **درونی‌ترین بلوک (پایین‌ترین) جایی است که خطا واقعاً افتاد، و بالاترین بلوک جایی که تو شروعش کردی.**

**قبل از ادامه، جواب بده:** خطای بالا در تابعِ `average` رخ داد. یعنی باگ حتماً در `average` است؟ جواب: نه لزوماً. `average` کارِ خودش را درست انجام داد؛ کسی فهرستِ خالی به آن داد. باگ می‌تواند اینجا باشد یا در صداکننده. **`traceback` می‌گوید کجا منفجر شد، نه اینکه چه کسی فتیله را روشن کرد** — و برای همین است که باید کلِ زنجیره را نگاه کنی، نه فقط خطِ آخر را.

## ۳. شش خطایی که بیشترین وقت را از تازه‌کارها می‌گیرند

</div>

| پیام | یعنی چه | معمولاً به‌خاطرِ |
|---|---|---|
| `SyntaxError` | پایتون اصلاً نتوانست جمله را بخواند | پرانتز یا گیومهٔ بسته‌نشده، دونقطهٔ جاافتاده |
| `IndentationError` | تورفتگی سرِ جایش نیست | بعد از دونقطه تورفته ننوشتی، یا Tab و فاصله قاطی شده |
| `NameError` | اسمی به‌کار بردی که تعریف نشده | غلطِ املایی، یا سلولی که هنوز اجرا نکرده‌ای |
| `TypeError` | این کار با این **نوع** تعریف نشده | جمعِ متن و عدد، یا تابعی که `None` برگردانده |
| `IndexError` / `KeyError` | جایگاه یا کلیدی خواستی که وجود ندارد | یکی بیشتر از طولِ فهرست، غلطِ املاییِ کلید |
| `ValueError` | نوع درست است ولی **مقدار** بی‌معناست | `int("سلام")` — متن هست، ولی عدد نیست |

<div dir="rtl">

`NameError` در نوت‌بوک یک دلیلِ مخصوص هم دارد که در هیچ محیطِ دیگری نیست: سلولی که متغیر را می‌سازد هنوز اجرا نشده، یا اجرا شده و بعد پاکش کرده‌ای. فصلِ ۱۰ کاملاً به همین اختصاص دارد.

## ۴. `try` / `except`: خطای پیش‌بینی‌شده را مدیریت کن

بعضی خطاها باگ‌اند و باید رفع شوند. بعضی‌ها **بخشِ عادیِ زندگی**‌اند: دادهٔ واقعی خراب دارد و تو از قبل می‌دانی.

</div>

```python
samples = ["12", "3.5", "سلام", ""]

for text in samples:
    try:
        value = int(text)
        print(f"«{text}» → {value}")
    except ValueError as error:
        print(f"«{text}» → ValueError: {error}")
```

<div dir="rtl">

</div>

```text
«12» → 12
«3.5» → ValueError: invalid literal for int() with base 10: '3.5'
«سلام» → ValueError: invalid literal for int() with base 10: 'سلام'
«» → ValueError: invalid literal for int() with base 10: ''
```

<div dir="rtl">

بلوکِ `try` کدی است که ممکن است بشکند؛ `except ValueError` یعنی «اگر دقیقاً این نوع خطا رخ داد، به‌جای توقف این کار را بکن». آن `as error` خودِ شیء خطا را در دستت می‌گذارد تا بتوانی پیامش را چاپ کنی.

سه چیزِ آموزنده در این خروجی هست. اول اینکه `"3.5"` هم رد شد — `int()` عددِ اعشاریِ نوشته‌شده به‌صورتِ متن را نمی‌پذیرد و این تقریباً همیشه غافلگیرکننده است. دوم اینکه رشتهٔ خالی هم `ValueError` است نه صفر. سوم اینکه حلقه **ادامه پیدا کرد** — بدونِ `try`، همان ردیفِ دوم کلِ اجرا را متوقف می‌کرد.

> ✅ **چک کن:** هر چهار خط باید چاپ شوند. اگر فقط یک خط دیدی و بعدش traceback، یعنی `try` را جا انداخته‌ای یا تورفتگی‌اش داخلِ حلقه نیست.

> 📏 **اندازه بگیر:** حالا سؤالِ مهم: در دادهٔ واقعی، **چند** ردیف این‌طوری رد می‌شود؟ اگر سه ردیف از هزار تا خراب باشد یک چیز است؛ اگر ششصد تا خراب باشد، ستون اصلاً آن چیزی نیست که فکر می‌کردی. عادت کن به‌جای رد کردنِ ساکتِ خطاها، **بشماری‌شان** — و اگر شمارش بزرگ شد، به‌جای مدیریتِ خطا برو داده را نگاه کن. این دقیقاً همان کاری است که در ترمِ ۲ فصلِ ۵ روی دادهٔ کثیفِ واقعی انجام می‌دهیم.

## ۵. `except` بدونِ نام: اشتباهی که گران تمام می‌شود

پایتون اجازه می‌دهد بنویسی `except:` و **هر** خطایی را بگیری. تقریباً همیشه اشتباه است:

</div>

```python
def risky_average(numbers):
    try:
        return sum(numbers) / len(numbers)
    except:
        return None

print(risky_average([10, 20, 30]))
print(risky_average([]))
print(risky_average("متن، نه فهرست"))
```

<div dir="rtl">

</div>

```text
20.0
None
None
```

<div dir="rtl">

سه بار صدا زدیم و هیچ‌وقت خطایی ندیدیم. ولی موردِ سوم یک **باگِ واقعی** بود: یک متن به‌جای فهرستِ عدد داده شد، `sum` روی آن `TypeError` داد، و `except:` بی‌سروصدا قورتش داد و `None` برگرداند. حالا برنامه‌ات دارد با یک مقدارِ غلط ادامه می‌دهد و تو خبر نداری.

نسخهٔ درست فقط همان خطایی را می‌گیرد که واقعاً انتظارش را داری:

</div>

```python
def safe_average(numbers):
    """میانگین؛ برای فهرستِ خالی None. هر ورودیِ نامعتبرِ دیگری را عمداً رد نمی‌کند."""
    try:
        return sum(numbers) / len(numbers)
    except ZeroDivisionError:
        return None

print(safe_average([10, 20, 30]))
print(safe_average([]))
```

<div dir="rtl">

</div>

```text
20.0
None
```

<div dir="rtl">

حالا فهرستِ خالی مدیریت می‌شود، ولی اگر کسی متن بدهد `TypeError` می‌گیرد و **همان‌جا می‌فهمد**.

> ⚠️ **مواظب باش:** قاعده را حفظ کن: **فقط خطایی را بگیر که می‌دانی چرا رخ می‌دهد و می‌دانی با آن چه کنی.** هر `except`ِ گشاد یک باگ را از امروز به فردا منتقل می‌کند — و فردا پیدا کردنش ده برابر سخت‌تر است، چون دیگر traceback نداری.

> 🤖 **از دستیارت بپرس:** یک traceback واقعی را که خودت گرفته‌ای برایش بگذار و بپرس: «این traceback چه می‌گوید؟ خط به خط توضیح بده، ولی **کد اصلاحی ننویس**.» قیدِ آخر عمدی است. اگر بگذاری کد اصلاح‌شده بدهد، خطا را رفع می‌کنی بدونِ اینکه یاد بگیری؛ دفعهٔ بعد باز هم گیر می‌کنی. هدف این است که خودت بتوانی بخوانی‌اش.

## واژه‌های تازهٔ این فصل

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| traceback | تریس‌بک | گزارشِ چندخطیِ خطا؛ مسیرِ صدا زدن از بیرون تا نقطهٔ انفجار |
| exception | اِکسپشِن | خطای زمانِ اجرا؛ چیزی که برنامه را متوقف می‌کند |
| try / except | ترای / اِکسپت | «این را امتحان کن» / «اگر این خطا شد، این کار را بکن» |
| ValueError | ولیو اِرور | نوع درست است ولی مقدار بی‌معناست |

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: در یک traceback، اول کدام خط را می‌خوانی و چرا؟

**تمرینِ اجباری:** تابعی بنویس که یک `dict` محصول و نامِ یک کلید بگیرد و مقدارش را برگرداند، ولی اگر کلید نبود به‌جای خطا متنِ `"نامشخص"` برگرداند. از `try`/`except KeyError` استفاده کن (نه از `get`). بعد همان تابع را با یک کلیدِ موجود و یک کلیدِ ناموجود امتحان کن.

**تمرینِ ستاره‌دار ⭐:** فهرستی از هشت متن بساز که قرار است قیمت باشند، ولی سه‌تایشان خراب باشند (یکی خالی، یکی با حروف، یکی با ویرگولِ هزارگان مثلِ `"1,200,000"`). حلقه‌ای بنویس که سالم‌ها را جمع بزند، خراب‌ها را در یک فهرستِ جدا نگه دارد، و آخرِ کار **هر دو** را گزارش کند: مجموع، و اینکه چند تا و کدام‌ها رد شدند. این دقیقاً الگویی است که در ترمِ ۲ روی فایلِ واقعی به‌کارش می‌بری — و آن ویرگولِ هزارگان یکی از رایج‌ترین دلیل‌های خرابیِ ستونِ عددی در دادهٔ واقعی است.

## در فصل بعد

حالا می‌توانی خطا را بخوانی. ولی امروز یک ابزارِ دیگر هم داری که تقریباً همه استفاده‌اش می‌کنند: **دستیارِ هوش مصنوعی**. فصلِ بعد صریح دربارهٔ آن حرف می‌زند — نه با انکار و نه با تسلیم. یاد می‌گیری چطور از دستیار برای **یاد گرفتن** استفاده کنی، چه سؤال‌هایی واقعاً کمکت می‌کنند، و چرا کدی که نمی‌توانی خط‌به‌خط توضیحش بدهی، کدِ تو نیست.

</div>

---
Source: https://yaadestan.com/courses/sarnakh/lessons/t1/s08-errors (یادستان, Yaadestan)
