# فصل ۰۲ — از نوت‌بوک به فایلِ `.py`

<div dir="rtl">

# فصل ۰۲ — از نوت‌بوک به فایلِ `.py`

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

نوت‌بوک برای **کشف** عالی است و برای **محصول** بد. در این فصل کدت را از نوت‌بوک بیرون می‌آوری و در یک پوشهٔ پروژهٔ واقعی می‌چینی: چند فایلِ `.py` که همدیگر را `import` می‌کنند، یک نقطهٔ ورودِ مشخص، و یک فهرستِ وابستگی. و در همین مسیر با `class` آشنا می‌شوی — نه چون «باید»، بلکه چون همین‌جا برای اولین بار **واقعاً لازمش داری**.

![چند برگهٔ پراکنده که در یک زونکنِ مرتب با جداکننده‌های برچسب‌خورده جا می‌گیرند](/lesson-assets/t5-s02-notebook-to-script/prompt/01-image-into-folder.png)

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

- بگویی نوت‌بوک کجا کم می‌آورد و پوشهٔ پروژه چه چیزی حل می‌کند
- کدت را به ماژول‌های مستقل تقسیم کنی و `import` کنی
- یک `class` بنویسی و بگویی چه فرقی با چند تابعِ جدا دارد
- `if __name__ == "__main__"` را درست به‌کار ببری

## قبل از شروع

**از فصل ۱:** `random_state`، `joblib`، اثرِ انگشتِ داده.

**از ترمِ ۱:** تابع، `dict`، و `import`.

> 📓 **نوت‌بوک:** [نوت‌بوک این فصل را در Colab باز کن](/notebooks/sarnakh/term-5-shipping/session-02-notebook-to-script.ipynb) — همهٔ کدهای این فصل آماده و به‌ترتیب داخلش هست.

## ۱. نوت‌بوک کجا کم می‌آورد

</div>

| کار | در نوت‌بوک | در فایلِ `.py` |
|---|---|---|
| کشف و آزمایشِ سریع | **عالی** | کند |
| نمایشِ نتیجه با نمودار | **عالی** | جداگانه لازم دارد |
| استفادهٔ دوباره از یک تابع در جای دیگر | copy-paste | `import` |
| اجرا از خطِ فرمان یا سرور | نمی‌شود | **طبیعی** |
| تست خودکار | نمی‌شود | **طبیعی** |
| دیدنِ تغییرات در `git` | آشفته | تمیز |
| ترتیبِ اجرا | دستِ کاربر | همیشه از بالا |

<div dir="rtl">

**هر دو را لازم داری.** الگوی کارِ حرفه‌ای این است: در نوت‌بوک کشف کن، و هر چیزی را که تثبیت شد به فایل منتقل کن — و از آن به بعد نوت‌بوک همان فایل را `import` کند، نه اینکه نسخهٔ دومی از کد داشته باشد.

## ۲. ساختنِ پوشهٔ پروژه

</div>

```python
import shutil
from pathlib import Path

PROJECT = Path("price_tool")
shutil.rmtree(PROJECT, ignore_errors=True)   # تا اجرای دوباره همیشه از صفر شروع کند
PROJECT.mkdir()
(PROJECT / "__init__.py").write_text("", encoding="utf-8")

print("پوشه ساخته شد:", PROJECT.name)
print("فایل‌های پایتون:", sorted(p.name for p in PROJECT.glob("*.py")))
```

<div dir="rtl">

</div>

```text
پوشه ساخته شد: price_tool
فایل‌های پایتون: ['__init__.py']
```

<div dir="rtl">

دو چیزِ تازه در همین چند خط:

**`Path` از کتابخانهٔ `pathlib`** راهِ امروزیِ کار با مسیرِ فایل در پایتون است. به‌جای چسباندنِ رشته‌ها — که روی ویندوز و لینوکس فرق می‌کند — یک شیءِ مسیر می‌سازی و با `.mkdir()` و `.write_text()` رویش کار می‌کنی.

و آن **`/` بینِ دو مسیر ضرب و تقسیم نیست.** `PROJECT / "__init__.py"` یعنی «فایلِ `__init__.py` **داخلِ** پوشهٔ `PROJECT`». `pathlib` عمداً همین علامت را انتخاب کرده چون شکلش دقیقاً شبیهِ جداکنندهٔ مسیر است، و خودش می‌داند روی هر سیستم‌عاملی چه جداکننده‌ای بگذارد.

`__init__.py` — حتی خالی — به پایتون می‌گوید این پوشه یک **بستهٔ قابلِ `import`** است.

آن `rmtree` هم عمدی است: **سلولی که بارِ دوم نتیجهٔ متفاوتی بدهد، همان دامِ حالتِ پنهانِ ترمِ ۱ فصلِ ۱۰ است.** با پاک کردنِ پوشه در ابتدا، اجرای دوباره همیشه همان چیزی را می‌سازد که اجرای اول ساخت. و `glob("*.py")` هم فقط فایل‌های پایتون را می‌شمارد، تا پوشهٔ `__pycache__` که خودِ پایتون می‌سازد، خروجی را عوض نکند.

> 💡 **نکته:** در Colab دستورِ `%%writefile` هم هست که محتوای یک سلول را در فایل می‌ریزد. اینجا عمداً از `Path.write_text` استفاده می‌کنیم، چون **کدِ معمولیِ پایتون است و همان‌طور که در نوت‌بوک کار می‌کند، در یک فایلِ `.py` هم کار می‌کند** — و همین موضوعِ کلِ فصل است. `encoding="utf-8"` را هم همیشه بنویس: بدونِ آن، روی بعضی سیستم‌ها متنِ فارسیِ داخلِ فایل خراب ذخیره می‌شود.

## ۳. اولین ماژول: داده

</div>

```python
DATA_PY = '''"""خواندن و شناسنامهٔ داده."""
import hashlib

import pandas as pd

FEATURES = ["year", "ram_gb", "brand", "city"]
TARGET = "price"


def load_data(path="laptops_clean.csv"):
    frame = pd.read_csv(path)
    return frame[FEATURES], frame[TARGET]


def fingerprint(frame):
    digest = hashlib.sha256(pd.util.hash_pandas_object(frame, index=True).values.tobytes())
    return digest.hexdigest()[:16]
'''

(PROJECT / "data.py").write_text(DATA_PY, encoding="utf-8")
print("نوشته شد:", sorted(p.name for p in PROJECT.glob("*.py")))
```

<div dir="rtl">

</div>

```text
نوشته شد: ['__init__.py', 'data.py']
```

<div dir="rtl">

سه قاعده در همین فایلِ کوچک رعایت شده و هر سه در فایل‌های بعدی هم تکرار می‌شوند:

- **یک فایل، یک مسئولیت.** `data.py` فقط با داده کار دارد. مدل جای دیگری است.
- **مقدارهای ثابت بالای فایل و با نامِ بزرگ.** `FEATURES` یک بار تعریف می‌شود و همه‌جا از همان استفاده می‌شود — نه اینکه در پنج سلولِ مختلف دوباره تایپ شود.
- **مسیرها `parameter`اند، نه ثابتِ داخلِ کد.** `load_data(path=...)` یعنی همین تابع فردا روی فایلِ دیگری هم کار می‌کند.

## ۴. `class`: داده و رفتارش، در یک جا

در ترمِ ۴ فصلِ ۸ یک `dict` ساختی که وضعیتِ دستیار را نگه می‌داشت، و چند تابع نوشتی که هر کدام آن `dict` را به‌عنوان اولین ورودی می‌گرفتند. **کار می‌کرد، ولی سه ایراد داشت:**

- هیچ‌چیز جلوی این را نمی‌گرفت که کسی یک کلیدِ لازم را جا بیندازد و خطا موقعِ استفاده ظاهر شود، نه موقعِ ساختن.
- تابع‌ها از `dict` جدا بودند؛ هیچ‌جا نوشته نبود که این چهار تابع فقط با این شکل از `dict` کار می‌کنند.
- برای هر تابع باید `bot` را دستی پاس می‌دادی.

**`class` دقیقاً این را حل می‌کند: داده و تابع‌هایی را که رویش کار می‌کنند در یک چیزِ واحد می‌بندد.**

</div>

```python
MODEL_PY = '''"""مدلِ قیمت: داده و رفتارش، در یک جا."""
import joblib
from sklearn.compose import ColumnTransformer
from sklearn.impute import SimpleImputer
from sklearn.linear_model import Ridge
from sklearn.metrics import mean_absolute_error
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import OneHotEncoder, StandardScaler


class PriceModel:
    """یک مدلِ قیمت با هر چیزی که برای به‌کار بردنش لازم است."""

    def __init__(self, alpha=0.1, seed=0):
        self.alpha = alpha
        self.seed = seed
        self.pipeline = Pipeline([
            ("prepare", ColumnTransformer([
                ("num", Pipeline([
                    ("fill", SimpleImputer(strategy="median")),
                    ("scale", StandardScaler()),
                ]), ["year", "ram_gb"]),
                ("cat", OneHotEncoder(handle_unknown="ignore"), ["brand", "city"]),
            ])),
            ("model", Ridge(alpha=alpha)),
        ])

    def fit(self, X, y):
        self.pipeline.fit(X, y)
        return self

    def predict(self, X):
        return self.pipeline.predict(X)

    def score(self, X, y):
        return mean_absolute_error(y, self.predict(X))

    def save(self, path="price_model.joblib"):
        joblib.dump(self, path)
        return path


def load_model(path="price_model.joblib"):
    """بارگذاری بیرونِ کلاس است، چون هنوز شیئی وجود ندارد که متدش را صدا بزنی."""
    return joblib.load(path)
'''

(PROJECT / "model.py").write_text(MODEL_PY, encoding="utf-8")
print("نوشته شد:", sorted(p.name for p in PROJECT.glob("*.py")))
```

<div dir="rtl">

</div>

```text
نوشته شد: ['__init__.py', 'data.py', 'model.py']
```

<div dir="rtl">

سه کلمهٔ تازه، و هر سه ساده‌اند:

- **`class PriceModel:`** یک **نوعِ تازه** تعریف می‌کند. مثلِ نقشهٔ ساختمان — خودش ساختمان نیست، ولی می‌شود از رویش ساخت.
- **`__init__`** وقتی صدا زده می‌شود که یکی از روی نقشه چیزی می‌سازد. کارش پر کردنِ وضعیتِ اولیه است.
- **`self`** یعنی «همین شیءِ مشخص». `self.alpha = alpha` یعنی این عدد را **در خودِ این شیء** نگه دار، نه در یک متغیرِ محلی که با تمام شدنِ تابع از بین می‌رود.

توجه کن که `fit` در آخر `return self` می‌کند. **این یک عادتِ عمدی است** و همان چیزی است که به `scikit-learn` اجازه می‌دهد بنویسی `PriceModel().fit(X, y)` در یک خط — همان الگویی که چهار ترم دیده‌ای، حالا از داخل.

## ۵. `import` کردنِ چیزی که ساختی

</div>

```python
import sys

if "" not in sys.path:
    sys.path.insert(0, "")   # پوشهٔ فعلی را جزو مسیرهای جست‌وجوی پایتون کن

from sklearn.model_selection import train_test_split

from price_tool.data import load_data
from price_tool.model import PriceModel

X, y = load_data()
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=0)
model = PriceModel(alpha=0.1, seed=0).fit(X_train, y_train)

print("نوع شیء:", type(model).__name__)
print("alpha:", model.alpha, "| seed:", model.seed)
print("MAE:", round(model.score(X_test, y_test)))
```

<div dir="rtl">

</div>

```text
نوع شیء: PriceModel
alpha: 0.1 | seed: 0
MAE: 1381886
```

<div dir="rtl">

**همان `1381886` فصلِ ۱** — که خوب است: بازچینیِ کد نباید نتیجه را عوض کند. **اگر عوض شد، بازچینی نکرده‌ای، برنامهٔ دیگری نوشته‌ای.**

> ✅ **چک کن:** اگر `ModuleNotFoundError: No module named 'price_tool'` گرفتی، سه چیز را به‌ترتیب چک کن: پوشه واقعاً کنارِ نوت‌بوکِ توست، `__init__.py` داخلش هست، و سلولِ بخشِ ۲ اجرا شده. و اگر فایلی را عوض کردی ولی رفتار عوض نشد، پایتون نسخهٔ قبلی را در حافظه دارد — **در Colab `Runtime > Restart session` بزن**؛ این یکی از رایج‌ترین سردرگمی‌های همین فصل است.

## ۶. نقطهٔ ورود

</div>

```python
MAIN_PY = '''"""نقطهٔ ورودِ برنامه."""
from sklearn.model_selection import train_test_split

from price_tool.data import fingerprint, load_data
from price_tool.model import PriceModel

SEED = 0


def main():
    X, y = load_data()
    X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=SEED)
    model = PriceModel(seed=SEED).fit(X_train, y_train)
    path = model.save()
    print("اثر انگشت داده:", fingerprint(X))
    print("MAE روی آزمون :", round(model.score(X_test, y_test)))
    print("مدل ذخیره شد در:", path)


if __name__ == "__main__":
    main()
'''

(PROJECT / "main.py").write_text(MAIN_PY, encoding="utf-8")

from price_tool.main import main
main()
```

<div dir="rtl">

</div>

```text
اثر انگشت داده: 76eb792297525571
MAE روی آزمون : 1381886
مدل ذخیره شد در: price_model.joblib
```

<div dir="rtl">

**`if __name__ == "__main__":` مهم‌ترین دو خطِ این فصل است.** معنایش این است: «این‌ها را فقط وقتی اجرا کن که این فایل **مستقیم** اجرا شده، نه وقتی که کسی `import`ش کرده.»

بدونِ آن، همین حالا که `from price_tool.main import main` را نوشتیم، کلِ آموزشِ مدل **خودش اجرا می‌شد** — و در یک برنامهٔ بزرگ‌تر یعنی هر `import` ساده ممکن است ساعت‌ها محاسبه راه بیندازد.

از خطِ فرمان (یا با `!` در Colab) همین فایل از پوشهٔ بالاتر، با `-m`، این‌طور اجرا می‌شود. `-m` یعنی «این را به‌عنوانِ ماژولی از یک بسته اجرا کن»، و `price_tool.main` همان نامی است که در `import` نوشتی، با نقطه، نه با `/`:

</div>

```bash
python -m price_tool.main
```

<div dir="rtl">

</div>

```text-approx
اثر انگشت داده: 76eb792297525571
MAE روی آزمون : 1381886
مدل ذخیره شد در: price_model.joblib
```

<div dir="rtl">

## ۷. `class` سرِ جایش می‌ماند

</div>

```python
import pandas as pd

from price_tool.model import load_model

loaded = load_model()
new_laptop = pd.DataFrame([{"year": 2022, "ram_gb": 16, "brand": "ایسوس", "city": "تهران"}])

print("نوع شیء بعد از بارگذاری:", type(loaded).__name__)
print("alpha حفظ شد:", loaded.alpha)
print("قیمت پیشنهادی:", round(float(loaded.predict(new_laptop)[0])))
```

<div dir="rtl">

</div>

```text
نوع شیء بعد از بارگذاری: PriceModel
alpha حفظ شد: 0.1
قیمت پیشنهادی: 30840171
```

<div dir="rtl">

**کلِ شیء ذخیره و بازخوانی شد** — نه فقط `Pipeline`، بلکه `alpha` و `seed` هم که خودت گذاشته بودی. مدلی که از فایل درآمد، دقیقاً همان چیزی است که ذخیره شده بود، **با همان شناسنامه**.

> ⚠️ **مواظب باش:** همین قابلیت یک قیدِ سفت هم دارد: برای باز کردنِ این فایل، پایتون باید **کلاسِ `PriceModel` را پیدا کند**. اگر فایلِ `model.py` را جابه‌جا کنی یا نامِ کلاس را عوض کنی، فایلِ ذخیره‌شده باز نمی‌شود. **فایلِ مدل بدونِ کدش بی‌فایده است** — پس هر دو را با هم و با نسخهٔ یکسان نگه دار.

## ۸. `requirements.txt` و شکلِ نهایی

</div>

```text-file
price_tool/
    __init__.py        ← این پوشه یک بستهٔ قابلِ import است
    data.py            ← خواندن داده و اثر انگشت
    model.py           ← class PriceModel
    main.py            ← نقطهٔ ورود
requirements.txt       ← وابستگی‌ها با نسخه
README.md              ← این پروژه چیست و چطور اجرا می‌شود
```

<div dir="rtl">

> 🔧 **اگر کار نکرد:** خطای `ModuleNotFoundError: No module named 'price_tool'` موقعِ اجرا یعنی فایل را با مسیرش اجرا کرده‌ای. وقتی می‌نویسی `python price_tool/main.py` یا داخلِ پوشه می‌روی و `python main.py` می‌زنی، پایتون پوشهٔ **خودِ فایل** را جست‌وجو می‌کند، نه پوشهٔ بالاتر را، پس بستهٔ `price_tool` را نمی‌بیند. **همیشه از پوشهٔ بالاتر و با `python -m price_tool.main` اجرا کن.**

> 🤖 **از دستیارت بپرس:** کلِ `model.py` را به دستیارت بده و بپرس: «این کلاس چه متدهای دیگری بهتر است داشته باشد؟» جوابش را **با معیارِ خودت بسنج، نه با تعدادش**: هر متدی که اضافه می‌کنی باید یا وضعیتِ داخلیِ کلاس را لازم داشته باشد یا رویش اثر بگذارد. **اگر تابعی به `self` کاری ندارد، جایش داخلِ کلاس نیست** — این ساده‌ترین و مفیدترین معیارِ تصمیم است.

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

</div>

| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| pathlib / Path | پث‌لیب / پث | کار با مسیرِ فایل به‌صورتِ شیء؛ `/` یعنی «داخلِ این پوشه» |
| module | ماژول | یک فایلِ `.py` که می‌شود `import`ش کرد |
| package | پکیج | پوشه‌ای با `__init__.py` که چند ماژول دارد |
| class | کلاس | نوعی تازه: داده + رفتارهایش، با هم |
| instance | اینستنس | یک شیءِ ساخته‌شده از روی یک کلاس |
| method | متد | تابعی که داخلِ کلاس تعریف شده |
| entry point | انتری پوینت | جایی که اجرای برنامه از آن شروع می‌شود |

<div dir="rtl">

## تمرین‌ها

قبل از تمرین، بدونِ نگاه به بالا جواب بده: اگر `if __name__ == "__main__":` را برداری، `from price_tool.main import main` چه اتفاقی می‌افتد؟

**تمرینِ اجباری:** یک ماژولِ چهارم به نامِ `report.py` بساز با تابعِ `summary(model, X_test, y_test)` که یک `dict` برگرداند شاملِ `MAE`، تعدادِ نمونهٔ آزمون، و `alpha` مدل. آن را در `main.py` به‌کار ببر و خروجی را چاپ کن. **دقت کن `report.py` نباید هیچ‌چیزی را دوباره آموزش بدهد** — فقط از چیزی که به آن داده می‌شود گزارش می‌سازد.

**تمرینِ ستاره‌دار ⭐:** دستیارِ فصلِ ۸ ترمِ ۴ را به یک `class` تبدیل کن: `Assistant` با `__init__` که ایندکس را می‌سازد، و متدهای `retrieve`، `ask` و `stats`. حالا این سؤال را جواب بده: **کدام بخش‌های آن `dict` باید `self.` شوند و کدام باید `parameter` بمانند؟** (راهنمایی: چیزی که در طولِ عمرِ شیء ثابت است در برابر چیزی که در هر فراخوانی فرق می‌کند.) این تمایز، همان چیزی است که یک کلاسِ خوب را از یک کلاسِ شلوغ جدا می‌کند.

## در فصل بعد

پروژه‌ات حالا چند فایل است. فصلِ بعد سؤالی را جواب می‌دهد که همین‌جا ساخته شد: **وقتی فردا فایل را عوض کردی و خراب شد، چطور به دیروز برمی‌گردی؟** جوابش `git` است — و آن را از داخلِ همین Colab به‌کار می‌بریم.

</div>

---
Source: https://yaadestan.com/courses/sarnakh/lessons/t5/s02-notebook-to-script (یادستان, Yaadestan)
