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

آخر این فصل میتوانی:
- بگویی نوتبوک کجا کم میآورد و پوشهٔ پروژه چه چیزی حل میکند
- کدت را به ماژولهای مستقل تقسیم کنی و
importکنی - یک
classبنویسی و بگویی چه فرقی با چند تابعِ جدا دارد if __name__ == "__main__"را درست بهکار ببری
قبل از شروع#
از فصل ۱: random_state، joblib، اثرِ انگشتِ داده.
از ترمِ ۱: تابع، dict، و import.
📓 نوتبوک: نوتبوک این فصل را در Colab باز کن — همهٔ کدهای این فصل آماده و بهترتیب داخلش هست.
۱. نوتبوک کجا کم میآورد#
| کار | در نوتبوک | در فایلِ .py |
|---|---|---|
| کشف و آزمایشِ سریع | عالی | کند |
| نمایشِ نتیجه با نمودار | عالی | جداگانه لازم دارد |
| استفادهٔ دوباره از یک تابع در جای دیگر | copy-paste | import |
| اجرا از خطِ فرمان یا سرور | نمیشود | طبیعی |
| تست خودکار | نمیشود | طبیعی |
دیدنِ تغییرات در git |
آشفته | تمیز |
| ترتیبِ اجرا | دستِ کاربر | همیشه از بالا |
هر دو را لازم داری. الگوی کارِ حرفهای این است: در نوتبوک کشف کن، و هر چیزی را که تثبیت شد به فایل منتقل کن — و از آن به بعد نوتبوک همان فایل را import کند، نه اینکه نسخهٔ دومی از کد داشته باشد.
۲. ساختنِ پوشهٔ پروژه#
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")))
پوشه ساخته شد: price_tool
فایلهای پایتون: ['__init__.py']
دو چیزِ تازه در همین چند خط:
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"را هم همیشه بنویس: بدونِ آن، روی بعضی سیستمها متنِ فارسیِ داخلِ فایل خراب ذخیره میشود.
۳. اولین ماژول: داده#
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")))
نوشته شد: ['__init__.py', 'data.py']
سه قاعده در همین فایلِ کوچک رعایت شده و هر سه در فایلهای بعدی هم تکرار میشوند:
- یک فایل، یک مسئولیت.
data.pyفقط با داده کار دارد. مدل جای دیگری است. - مقدارهای ثابت بالای فایل و با نامِ بزرگ.
FEATURESیک بار تعریف میشود و همهجا از همان استفاده میشود — نه اینکه در پنج سلولِ مختلف دوباره تایپ شود. - مسیرها
parameterاند، نه ثابتِ داخلِ کد.load_data(path=...)یعنی همین تابع فردا روی فایلِ دیگری هم کار میکند.
۴. class: داده و رفتارش، در یک جا#
در ترمِ ۴ فصلِ ۸ یک dict ساختی که وضعیتِ دستیار را نگه میداشت، و چند تابع نوشتی که هر کدام آن dict را بهعنوان اولین ورودی میگرفتند. کار میکرد، ولی سه ایراد داشت:
- هیچچیز جلوی این را نمیگرفت که کسی یک کلیدِ لازم را جا بیندازد و خطا موقعِ استفاده ظاهر شود، نه موقعِ ساختن.
- تابعها از
dictجدا بودند؛ هیچجا نوشته نبود که این چهار تابع فقط با این شکل ازdictکار میکنند. - برای هر تابع باید
botرا دستی پاس میدادی.
class دقیقاً این را حل میکند: داده و تابعهایی را که رویش کار میکنند در یک چیزِ واحد میبندد.
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")))
نوشته شد: ['__init__.py', 'data.py', 'model.py']
سه کلمهٔ تازه، و هر سه سادهاند:
class PriceModel:یک نوعِ تازه تعریف میکند. مثلِ نقشهٔ ساختمان — خودش ساختمان نیست، ولی میشود از رویش ساخت.__init__وقتی صدا زده میشود که یکی از روی نقشه چیزی میسازد. کارش پر کردنِ وضعیتِ اولیه است.selfیعنی «همین شیءِ مشخص».self.alpha = alphaیعنی این عدد را در خودِ این شیء نگه دار، نه در یک متغیرِ محلی که با تمام شدنِ تابع از بین میرود.
توجه کن که fit در آخر return self میکند. این یک عادتِ عمدی است و همان چیزی است که به scikit-learn اجازه میدهد بنویسی PriceModel().fit(X, y) در یک خط — همان الگویی که چهار ترم دیدهای، حالا از داخل.
۵. import کردنِ چیزی که ساختی#
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)))
نوع شیء: PriceModel
alpha: 0.1 | seed: 0
MAE: 1381886
همان 1381886 فصلِ ۱ — که خوب است: بازچینیِ کد نباید نتیجه را عوض کند. اگر عوض شد، بازچینی نکردهای، برنامهٔ دیگری نوشتهای.
✅ چک کن: اگر
ModuleNotFoundError: No module named 'price_tool'گرفتی، سه چیز را بهترتیب چک کن: پوشه واقعاً کنارِ نوتبوکِ توست،__init__.pyداخلش هست، و سلولِ بخشِ ۲ اجرا شده. و اگر فایلی را عوض کردی ولی رفتار عوض نشد، پایتون نسخهٔ قبلی را در حافظه دارد — در ColabRuntime > Restart sessionبزن؛ این یکی از رایجترین سردرگمیهای همین فصل است.
۶. نقطهٔ ورود#
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()
اثر انگشت داده: 76eb792297525571
MAE روی آزمون : 1381886
مدل ذخیره شد در: price_model.joblib
if __name__ == "__main__": مهمترین دو خطِ این فصل است. معنایش این است: «اینها را فقط وقتی اجرا کن که این فایل مستقیم اجرا شده، نه وقتی که کسی importش کرده.»
بدونِ آن، همین حالا که from price_tool.main import main را نوشتیم، کلِ آموزشِ مدل خودش اجرا میشد — و در یک برنامهٔ بزرگتر یعنی هر import ساده ممکن است ساعتها محاسبه راه بیندازد.
از خطِ فرمان (یا با ! در Colab) همین فایل از پوشهٔ بالاتر، با -m، اینطور اجرا میشود. -m یعنی «این را بهعنوانِ ماژولی از یک بسته اجرا کن»، و price_tool.main همان نامی است که در import نوشتی، با نقطه، نه با /:
python -m price_tool.main
اثر انگشت داده: 76eb792297525571
MAE روی آزمون : 1381886
مدل ذخیره شد در: price_model.joblib
۷. class سرِ جایش میماند#
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])))
نوع شیء بعد از بارگذاری: PriceModel
alpha حفظ شد: 0.1
قیمت پیشنهادی: 30840171
کلِ شیء ذخیره و بازخوانی شد — نه فقط Pipeline، بلکه alpha و seed هم که خودت گذاشته بودی. مدلی که از فایل درآمد، دقیقاً همان چیزی است که ذخیره شده بود، با همان شناسنامه.
⚠️ مواظب باش: همین قابلیت یک قیدِ سفت هم دارد: برای باز کردنِ این فایل، پایتون باید کلاسِ
PriceModelرا پیدا کند. اگر فایلِmodel.pyرا جابهجا کنی یا نامِ کلاس را عوض کنی، فایلِ ذخیرهشده باز نمیشود. فایلِ مدل بدونِ کدش بیفایده است — پس هر دو را با هم و با نسخهٔ یکسان نگه دار.
۸. requirements.txt و شکلِ نهایی#
price_tool/
__init__.py ← این پوشه یک بستهٔ قابلِ import است
data.py ← خواندن داده و اثر انگشت
model.py ← class PriceModel
main.py ← نقطهٔ ورود
requirements.txt ← وابستگیها با نسخه
README.md ← این پروژه چیست و چطور اجرا میشود
🔧 اگر کار نکرد: خطای
ModuleNotFoundError: No module named 'price_tool'موقعِ اجرا یعنی فایل را با مسیرش اجرا کردهای. وقتی مینویسیpython price_tool/main.pyیا داخلِ پوشه میروی وpython main.pyمیزنی، پایتون پوشهٔ خودِ فایل را جستوجو میکند، نه پوشهٔ بالاتر را، پس بستهٔprice_toolرا نمیبیند. همیشه از پوشهٔ بالاتر و باpython -m price_tool.mainاجرا کن.
🤖 از دستیارت بپرس: کلِ
model.pyرا به دستیارت بده و بپرس: «این کلاس چه متدهای دیگری بهتر است داشته باشد؟» جوابش را با معیارِ خودت بسنج، نه با تعدادش: هر متدی که اضافه میکنی باید یا وضعیتِ داخلیِ کلاس را لازم داشته باشد یا رویش اثر بگذارد. اگر تابعی بهselfکاری ندارد، جایش داخلِ کلاس نیست — این سادهترین و مفیدترین معیارِ تصمیم است.
واژههای تازهٔ این فصل#
| کلمه | تلفظ به حروف فارسی | یعنی چه |
|---|---|---|
| pathlib / Path | پثلیب / پث | کار با مسیرِ فایل بهصورتِ شیء؛ / یعنی «داخلِ این پوشه» |
| module | ماژول | یک فایلِ .py که میشود importش کرد |
| package | پکیج | پوشهای با __init__.py که چند ماژول دارد |
| class | کلاس | نوعی تازه: داده + رفتارهایش، با هم |
| instance | اینستنس | یک شیءِ ساختهشده از روی یک کلاس |
| method | متد | تابعی که داخلِ کلاس تعریف شده |
| entry point | انتری پوینت | جایی که اجرای برنامه از آن شروع میشود |
تمرینها
اول خودت فکر کن یا امتحان کن — بعد اینجا را باز کن.
در فصل بعد#
پروژهات حالا چند فایل است. فصلِ بعد سؤالی را جواب میدهد که همینجا ساخته شد: وقتی فردا فایل را عوض کردی و خراب شد، چطور به دیروز برمیگردی؟ جوابش git است — و آن را از داخلِ همین Colab بهکار میبریم.
به آخر این فصل رسیدی!
اگر ساختی و جواب داد، این دکمه مال توست.