آموزش ساخت و استفاده از ماژول در پایتون 3
در این مقاله میخوانید
وقتی تعداد خطوط کدتان از حدی میگذرد، پیدا کردن یک تابع ساده در میان انبوهی از کلاسها و متغیرها شبیه به پیدا کردن سوزن در انبار کاه میشود. از طرفی اگر بخواهید بخشی از آن کد را در پروژه دیگری استفاده کنید، چارهای جز کپیکردن ندارید که این کار نیز نگهداری و دیباگ را به شدت سخت میکند. اینجاست که ماژولها (Modules) به کمک شما میآیند. در این مقاله از بخش آموزش پایتون در بلاگ پارسپک، یاد میگیریم که ماژول پایتون چیست و چه انواعی دارد. سپس نحوه ساخت ماژول در پایتون ۳ را مرحلهبهمرحله بررسی میکنیم.
ماژول پایتون چیست؟
ماژول پایتون فایلی با پسوند py. است که مجموعهای از توابع (Functions)، کلاسها (Classes) و متغیرها را در خود نگه میدارد. نام ماژول همان نام فایل بدون پسوند است. برای مثال، فایل hello.py به ماژولی با نام hello تبدیل میشود.
هدف اصلی ماژولها آن است که بهجای کپیکردن یک منطق تکراری در فایلهای مختلف، آن را یک بار در یک ماژول مجزا مینویسید و هر زمان که نیاز بود، با دستور import در سایر بخشهای پروژه فراخوانی میکنید. این ساختار ماژولار، نهتنها کدها را تمیز و خوانا نگه میدارد، بلکه فرایند دیباگ و توسعه پروژه را نیز بسیار سادهتر میکند.
پلتفرم PaaS پایتون پارسپک
هاست پایتون پارسپک یک سرویس کاربردی و پلتفرم هوشمند است که بسیاری از تسکهای تخصصی را به صورت خودکار انجام میدهد. با خرید این سرویس از اتصال به آسان Git، مقیاسپذیری سریع و لحظهای و امنیت بالا بهرهمند میشوید.
انواع ماژول در پایتون
ماژولها را از نظر منبع و نحوهی دسترسی، به سه دستهی اصلی تقسیم میکنند:
ماژولهای داخلی (Built-in) و کتابخانه استاندارد: این کتابخانهها همراه نصب پایتون در اختیار شما قرار میگیرند و نیازی به نصب جداگانه ندارند. مثال: os ، math ، sys و .datetime
ماژولهای شخص ثالث (Third-party): این ماژولها را توسعهدهندگان دیگر نوشتهاند و با ابزار pip نصب میشوند. مثال: requests، pandas و numpy.
ماژولهای اختصاصی (Custom): ماژولهایی که خودتان برای نیاز یک پروژه مینویسید و موضوع اصلی این آموزش هستند.
در پروژههای واقعی معمولا هر سه نوع در کنار هم استفاده میشوند.
اگر با پایتون آشنایی ندارید و ویژگیهای آن را نمیشناسید، مقاله زیر را مطالعه کنید تا با همه نکات درباره آن آشنا شوید:
چرا باید در پایتون ماژول بسازیم؟
نگهداری تمام کدهای یک پروژه در یک فایل واحد تنها برای اسکریپتهای پردازشی بسیار کوچک توجیهپذیر است. با توسعه ساختار برنامه و افزایش خطوط کد، معماری ماژولار به یک الزام مهندسی تبدیل میشود. پیادهسازی منطق پروژه در قالب ماژولهای مجزا، دستاوردهای ساختاری زیر را به همراه دارد:
- خوانایی و جداسازی منطق (Separation of Concerns): تفکیک کدهای مرتبط در فایلهای مستقل، پیچیدگی ساختاری را کاهش داده و فرایند دیباگ و مسیریابی کدها (Code Navigation) را تسریع میکند.
- توسعهپذیری و استفاده مجدد (Reusability): با این معماری، یک قطعه کد (مانند کلاس اتصال به دیتابیس) تنها یک بار نوشته میشود و از طریق دستور import در تمامی بخشهای پروژه یا حتی پروژههای دیگر قابل فراخوانی است.
- تمرکز در نگهداری (Maintainability): در صورت شناسایی باگ یا نیاز به توسعه ساختاری، تغییرات تنها در یک ماژول متمرکز اعمال میشود و بهطور خودکار در تمام بخشهای وابسته منعکس خواهد شد.
- ایزولهسازی فضای نام (Namespace Isolation): هر ماژول Scope اختصاصی خود را در پایتون ایجاد میکند. این ویژگی از تداخل نامها (Name Collision) جلوگیری کرده و امکان استفاده از نامهای مشابه برای توابع را در ماژولهای مختلف و بدون بروز خطا فراهم میکند.
- تستپذیری مستقل (Unit Testing): معماری ماژولار امکان اجرای تستهای واحد را روی هر بخش به صورت کاملا مستقل فراهم میکند؛ رویکردی که برای استقرار پایدار کدهای پایتون روی سرور و چرخه CI/CD مهم است.
آموزش کامل Doctest در پایتون را در مقالهی زیر بخوانید.
ساخت ماژول در پایتون ۳
در ادامه ابتدا پیشنیازها را میبینیم، بعد یک ماژول واقعی میسازیم و در آخر روشهای فراخوانی را بررسی میکنیم:
پیشنیازهای ساخت ماژول
برای ساخت ماژول در پایتون به ابزار پیچیدهای نیاز ندارید، اما چند مورد باید آماده باشد:
- نصب بودن پایتون ۳: با اجرای python3 –version در ترمینال یا python –version در ویندوز مطمئن شوید که نسخهی ۳ روی سیستم نصب است.
- یک ویرایشگر کد: هر ویرایشگری مثل VS Code ، PyCharm یا حتی Nano و Vim کافی است.
- آشنایی با مبانی پایتون: باید تعریف تابع، متغیر و کلاس را بلد باشید.
- نامگذاری درست فایل: نام ماژول باید فقط شامل حروف انگلیسی، عدد و آندرلاین (_) باشد. همچنین با عدد شروع نشود و خط تیره (-) نداشته باشد. چون نام ماژول بعدا در دستور import مثل یک شناسه به کار میرود. نامی مثل my-tools.py را نمیشود import کرد. رسم رایج هم این است که نام ماژول با حروف کوچک نوشته شود.
- پرهیز از همنام شدن با ماژولهای موجود: فایلی با نام random.py ،math.py یا json.py نسازید. در این صورت پایتون ممکن است فایل شما را بهجای ماژول استاندارد import کند و خطاهای عجیبی ببینید.
حالا یک ماژول ساده میسازیم. فایلی به نام math_tools.py بنویسید و کد زیر را داخل آن قرار دهید:
# math_tools.py
"""A small module with a few math helpers."""
PI = 3.14159
def add(a, b):
"""Return the sum of two numbers."""
return a + b
def circle_area(radius):
"""Return the area of a circle."""
return PI * radius ** 2
class Rectangle:
def __init__(self, width, height):
self.width = width
self.height = height
def area(self):
return self.width * self.height
این ساختار پایه نشاندهنده یک ماژول استاندارد است که متغیر، توابع و یک کلاس را در خود کپسوله کرده است. رشتهی سهگانهی ابتدای فایل هم Docstring ماژول است و با math_tools.__doc__ یا help قابلخواندن است.
برای اینکه بدانید چطور اولین برنامه خود را در پایتون ۳ بنویسید و اجرا کنید، مقالهی زیر را بخوانید.
نحوه فراخوانی
برای استفاده از ماژول، فایل دیگری مانند main.py را در پوشه math_tools.py بسازید. پایتون چند روش برای فراخوانی ماژول دارد و هرکدام در شرایط خاصی کاربرد دارد.
روش اول، import کامل ماژول است. در این روش هر بار باید نام ماژول را قبل از نام تابع یا متغیر بنویسید. این رویکرد باعث شفافیت فضای نام (Namespace) و مسیریابی دقیق سورسکد در پروژههای بزرگ میشود:
import math_tools print(math_tools.add(3, 5)) # 8 print(math_tools.circle_area(2)) # 12.56636
روش دوم، import موارد مشخص با from … import است. اینجا مستقیم با نام تابع کار میکنید:
from math_tools import add, Rectangle print(add(10, 20)) # 30 rect = Rectangle(4, 5) print(rect.area()) # 20
روش سوم، استفاده از نام مستعار (Alias) با as است. وقتی نام ماژول طولانی است یا با نام دیگری تداخل دارد، به کار میآید:
import math_tools as mt print(mt.PI) # 3.14159
روش چهارم، با دستور زیر است که همهی نامهای عمومی ماژول را یکجا وارد میکند.
from math_tools import *
نکته:
اگرچه روش چهارم کوتاهترین روش است، توصیه نمیشود. چون خوانایی کد را پایین میآورد و ممکن است نامهای موجود در برنامهتان را بدون اطلاع بازنویسی کند.
دسترسی به ماژولها از دایرکتوری دیگر
اگر قصد دارید از ماژول پایتون در مکانی غیر از دایرکتوری برنامه اصلیتان استفاده کنید، چند گزینه پیش رو دارید. در مثالهای این بخش دستورها هم برای لینوکس و هم برای ویندوز آمده است.
۱. افزودن مسیرها
یکی از گزینهها، افزودن مسیر ماژول به فهرست مسیرهای جستوجوی پایتون در همان فایل برنامه است. این تغییر فقط برای همان اجرای برنامه اعمال میشود و ماژول در سراسر سیستم در دسترس نخواهد بود. بنابراین این روش موقتی است و نمیتوان آن را راهحل دائمی دانست.
برای انجام این کار، ابتدا ماژول sys را در کنار ماژولهایی وارد کنید که میخواهید در فایل برنامه اصلی خود از آنها استفاده کنید. ماژول sys بخشی از کتابخانه استاندارد پایتون است و پارامترها و توابع خاص سیستم را ارائه میدهد.
برای مثال، فرض کنید فایل hello.py را انتقال دادیم و اکنون در پوشه modules کاربر sammy قرار دارد (در لینوکس /home/sammy/modules/ و در ویندوز C:\Users\sammy\modules)، در حالی که فایل main_program.py در دایرکتوری دیگری است.
در فایل main_program.py، ماژول hello را با وارد کردن ماژول sys و سپس ضمیمه کردن این مسیر به فهرست مسیرهای جستوجوی پایتون (sys.path) وارد میکنیم. در لینوکس:
import sys
sys.path.append('/home/sammy/modules/')
import hello
در ویندوز مسیر را بهصورت raw string (با پیشوند r) بنویسید تا بکاسلشها بهعنوان کاراکتر خاص تفسیر نشوند. نوشتن مسیر با اسلش معمولی (C:/Users/sammy/modules) هم در ویندوز کار میکند:
import sys sys.path.append(r'C:\Users\sammy\modules') import hello
دستور append مسیر را به انتهای فهرست اضافه میکند. اگر ماژولی همنام در مسیرهای قبلی وجود داشته باشد، پایتون همان را import میکند. برای اینکه مسیر شما در اولویت باشد، از sys.path.insert(0, …) استفاده کنید.
تا زمانی که مسیر فایل hello.py را بهدرستی تنظیم کرده باشیم، میتوانیم فایل main_program.py را بدون هیچ مشکلی اجرا کنیم. در واقع، اگر همهچیز بهخوبی پیش برود، همان خروجی بالا را دریافت خواهیم کرد.
در هنگام خرید هاست Python باید چه نکاتی را رعایت کنید؟ برای آشنایی با پاسخ این سوال و بررسی همه نکات درباره هاست پایتون مقاله زیر را بخوانید:
۲. افزودن ماژول به مسیر پایتون
گزینه دیگر، قرار دادن ماژول در مسیری است که پایتون ماژولها و بستهها را بهصورت پیشفرض در آن بررسی میکند. این روش در مقایسه با روش قبلی دائمیتر است.
برای اینکه بدانیم پایتون چه مسیرهایی را بررسی میکند، باید Python Interpreter را از طریق محیط برنامهنویسی خود اجرا کنیم. در لینوکس از دستور python3 و در ویندوز از دستور python یا py استفاده کنید:
python3
در مرحله بعد، ماژول sys را وارد میکنیم:
import sys
سپس از پایتون میخواهیم مسیرهای جستوجو را چاپ کند:
print(sys.path)
در مرحله بعد، فهرستی از چند مسیر دریافت خواهیم کرد. اگر محیط مجازی (Virtual Environment) فعال باشد، مسیر site-packages همان محیط هم در این فهرست دیده میشود. در این شرایط، آنچه بهدنبالش هستیم در لینوکس مشابه خط زیر است:
'/home/sammy/my_env/lib/python3.11/site-packages'
و در ویندوز مشابه این خط است. بکاسلشها در خروجی دوتایی نمایش داده میشوند:
'C:\\Users\\sammy\\my_env\\Lib\\site-packages'
حالا میتوانیم فایل hello.py خودمان را به آن Directory منتقل کنیم. پس از تکمیل این کار نیز میتوانیم ماژول hello را مطابق معمول وارد کنیم:
import hello
کپی کردن فایل در site-packages برای آزمایش سریع مناسب است، اما برای نگهداری پروژه روش مناسبی نیست. چون ماژولهای شما با بستههای نصبشده با pip اشتباه میشوند. همچنین در نسخههای جدید توزیعهای لینوکس مثل اوبونتو 24.04 و بالاتر و دبیان 12 و بالاتر، تغییر دادن site-packages مربوط به پایتون سیستم محدود شده است (PEP 668)، پس این کار را فقط داخل محیط مجازی انجام دهید.
دو جایگزین بهتر وجود دارد:
روش اول: افزودن مسیر پوشه ماژولها به متغیر محیطی PYTHONPATH است. در لینوکس:
export PYTHONPATH="$PYTHONPATH:/home/sammy/modules"
برای دائمی شدن، همین خط را به فایل ~/.bashrc اضافه کنید. در ویندوز و در PowerShell، متغیر را برای نشست فعلی اینطور تنظیم میکنید:
env:PYTHONPATH="env:PYTHONPATH;C:\Users\sammy\modules"
برای ذخیرهی دائمی در ویندوز میتوانید از دستور زیر استفاده کنید. این دستور روی پنجرهی فعلی اثر نمیگذارد و باید ترمینال را ببندید و دوباره باز کنید:
setx PYTHONPATH "C:\Users\sammy\modules"
توجه کنید که جداکنندهی مسیرها در لینوکس دونقطه (:) و در ویندوز نقطهویرگول (;) است. دستور setx مقدار قبلی متغیر را بازنویسی میکند؛ اگر از قبل مسیری در PYTHONPATH دارید، آن را از بخش Environment Variables ویندوز ویرایش کنید.
روش دوم: نصب ماژول بهصورت بسته قابل ویرایش (Editable Install) است که در هر دو سیستمعامل یکسان کار میکند. برای این کار در پوشه ماژول فایل pyproject.toml بسازید:
[build-system] requires = ["setuptools>=64"] build-backend = "setuptools.build_meta" [project] name = "hello" version = "0.1.0" [tool.setuptools] py-modules = ["hello"]
سپس در همان پوشه، دستور زیر را اجرا کنید:
pip install -e .
از این به بعد، ماژول hello در همه برنامههای همان محیط قابل import است.
اگر تمام مراحل را بهدرستی انجام داده باشیم، برنامه بدون هیچ مشکلی اجرا خواهد شد؛ اما اگر در اجرای برنامه مشکلی وجود داشت، باید مراحل را از اول مرور کنیم.
آموزش کامل نصب و فعالسازی پایتون ۳٫۸ در centos 7.8 را در مقالهی زیر بخوانید.
خطاهای رایج هنگام ساخت ماژول در پایتون
در فرایند توسعه و ساخت ماژولهای پایتون، برخورد با خطاهای بارگذاری بسیار رایج است. برای اینکه دیباگ (عیبیابی) کدها سریعتر پیش برود، رایجترین خطاها و اصطلاحات آنها را به شکلی کاملا شفاف و ساده بررسی میکنیم:
خطای ModuleNotFoundError: No module named ‘…’
این خطا نشانه آن است که مفسر پایتون نتوانسته ماژول شما را پیدا کند. این مشکل معمولا زمانی رخ میدهد که برنامه را از پوشه اشتباهی اجرا کردهاید یا محیط مجازی (Virtual Environment) شما فعال نیست.
راهکار: بررسی کنید که مسیر اجرای برنامه درست باشد و آن را از پوشه اصلی پروژه (Root) اجرا کرده باشید.
خطای ImportError: cannot import name ‘…’
فایل ماژول پیدا شده است، اما تابع یا متغیری که درخواست کردهاید داخل آن وجود ندارد. اشتباه تایپی در نام تابع، یا گیر افتادن در وابستگی دوری (Circular Import) از دلایل اصلی آن هستند. Circular Import به حالتی گفته میشود که فایل A برای اجرا به فایل B نیاز دارد و فایل B هم همزمان منتظر اجرای فایل A است و در نتیجه مفسر قفل میشود.
راهکار: املای توابع را بررسی کنید و اگر وابستگی دوری دارید، کدهای مشترک را به یک فایل سوم انتقال دهید.
تداخل نام با کتابخانههای پیشفرض (Name Shadowing)
شما نام یک فایل از پروژه خود را مشابه نام یکی از کتابخانههای اصلی پایتون انتخاب کردهاید. در این حالت، پایتون به جای کتابخانه اصلی، فایل شما را میخواند و چون توابع اصلی در آن نیستند، خطا میدهد. به این پدیده سایهاندازی (Shadowing) میگویند.
راهکار: نام فایل خود را تغییر دهید و پوشه __pycache__ را پاک کنید.
نکته:
پوشه pycache جایی است که پایتون کدهای ترجمهشده را به صورت موقت ذخیره میکند تا سرعت اجرای دفعات بعد بیشتر شود.
اجرای ناخواسته کدها هنگام فراخوانی (Import)
پایتون در لحظه فراخوانی یک ماژول، تمام کدهای آزاد داخل آن را یک بار اجرا میکند. اگر کدی مثل دستور print را بیرون از توابع نوشته باشید، با هر بار فراخوانی شدن به صورت خودکار اجرا میشود.
راهکار: کدهای تست خود را همیشه داخل بلوک شرطی if __name__ == “__main__”: قرار دهید. این شرط به پایتون میگوید: «این بخش از کد را فقط در صورتی اجرا کن که فایل به صورت مستقیم باز شده باشد، نه زمانی که در فایل دیگری فراخوانی شده است».
خطای attempted relative import
این ارور زمانی رخ میدهد که شما از مسیردهی نسبی استفاده کرده باشید، یعنی با علامت نقطه مشخص کردهاید که فایل کجاست، اما فایل را به صورت مستقیم اجرا کردهاید. پایتون هنگام اجرای مستقیم، ساختار پوشههای والد (Parent) را تشخیص نمیدهد.
راهکار: برنامه را به عنوان یک ماژول از ریشه پروژه اجرا کنید یا آدرسدهی را با نوشتن نام کامل پوشهها از ابتدا تغییر دهید.
تداخل مفسر و محیط مجازی
علت ایجاد این ارور آن است که یک بسته نرمافزاری را با ابزار pip داخل یک محیط نصب کردهاید، اما برنامه را با مفسر محیط دیگری اجرا میکنید.
راهکار: در محیط ترمینال دستورهای which python و python -m pip –version را وارد کنید تا اطمینان یابید هر دو ابزار به یک مسیر مشترک اشاره میکنند.
اعمال نشدن تغییرات کد در نشست تعاملی
نشست تعاملی (Interactive Session) همان محیط ترمینال پایتون است که کدها را خطبهخط اجرا میکند. پایتون برای صرفهجویی در منابع، ماژولها را در حافظه پنهان (Cache) نگه میدارد. به همین دلیل تغییرات جدید شما در کدهای ماژول، در ترمینال دیده نمیشوند.
راهکار: از دستور reload() از کتابخانه importlib استفاده کنید تا فایل به صورت اجباری دوباره بارگذاری شود یا اینکه محیط ترمینال را ببندید و دوباره باز کنید.
هاست پایتون دقیقاْ چیست و چرا باید هاست مناسب پایتون تهیه کنیم؟
تفاوت ماژول (Module)، پکیج (Package) و کتابخانه (Library) در پایتون چیست؟

این سه اصطلاح در گفتوگوهای برنامهنویسی زیاد بهجای هم به کار میروند و همین باعث سردرگمی میشود. تفاوتشان در سطح سازماندهی کد است: ماژول کوچکترین واحد است، پکیج چند ماژول را کنار هم قرار میدهد و کتابخانه مجموعهی بزرگتری از کد برای یک هدف مشخص است. در ادامه هرکدام را جدا بررسی میکنیم.
ماژول
ماژول یک فایل پایتون (py.) است که کدهای مرتبط را در خود دارد. سادهترین و کوچکترین واحد سازماندهی کد در پایتون است. فایل math_tools.py که در این مقاله ساختیم، یک ماژول است. از ماژولهای آماده هم json و random نمونهی خوبیاند.
پکیج
پکیج پوشهای است که چند ماژول مرتبط را کنار هم نگه میدارد. پکیجها ساختار سلسلهمراتبی دارند و با نقطه به زیرماژولهایشان دسترسی پیدا میکنید، مثل mypackage.module_a. معمولاً داخل پوشهی پکیج یک فایل __init__.py قرار میدهند. از پایتون ۳٫۳ به بعد، پوشهی بدون این فایل هم بهعنوان پکیج فضای نام (Namespace Package) شناخته میشود، اما برای پکیجهای معمولی (Regular Package) همچنان نوشتن __init__.py توصیه میشود، چون میتوانید کدهای راهاندازی پکیج را در آن بنویسید. ساختار یک پکیج ساده این شکلی است:
shop/ ├── __init__.py ├── cart.py └── payment.py
با این ساختار میتوانید بنویسید from shop import cart یا import shop.payment.
کتابخانه
کتابخانه یک اصطلاح عمومی است و تعریف رسمی و جداگانهای در زبان پایتون ندارد. به مجموعهای از ماژولها و پکیجها گفته میشود که برای انجام کاری مشخص کنار هم قرار گرفتهاند و معمولاً بهصورت یک بستهی قابلنصب منتشر میشوند. NumPy برای محاسبات عددی، Requests برای درخواستهای HTTP و Pandas برای تحلیل داده، نمونههای معروف کتابخانه هستند. کتابخانهی استاندارد (Standard Library) پایتون هم مجموعهی بزرگی از ماژولها و پکیجهاست که همراه خود زبان نصب میشود.
در یک جمله میشود گفت هر کتابخانه از یک یا چند پکیج تشکیل میشود و هر پکیج هم از یک یا چند ماژول.
جمعبندی
حالا میدانید یک فایل سادهی پایتون چطور به ماژولی قابلاستفاده در هر پروژه تبدیل میشود و چرا پایتون گاهی ماژول شما را پیدا نمیکند. این دانستهها کمک میکند کدتان منظم و قابلنگهداری بماند و وقتی پروژه به سرور میرسد، با ساختار درستی کارتان را شروع کنید. اگر قصد دارید پروژههای پایتونیتان را روی بستری آماده اجرا کنید، خرید هاست پایتون از پارسپک گزینهی مناسبی است.
سوالات متداول
ماژول در پایتون چیست؟
ماژول فایلی با پسوند py. است که تابع، کلاس و متغیرهای مرتبط با هم را در خود نگه میدارد. با دستور import میتوانید از محتوای آن در فایلهای دیگر استفاده کنید.
چطور در پایتون ماژول بسازیم؟
کافی است یک فایل با پسوند py. بنویسید و کدهایتان را داخل آن قرار دهید. بعد در فایل دیگری که کنار آن قرار دارد، با import نام_فایل ماژول را فراخوانی کنید. اگر فایلها در پوشههای مختلفاند، باید مسیر ماژول را به sys.path یا PYTHONPATH اضافه کنید.
چرا پایتون ماژولی را که ساختهام پیدا نمیکند؟
معمولاً پوشهی ماژول در sys.path نیست، نام فایل اشتباه نوشته شده یا برنامه را با مفسر یا محیط مجازی دیگری اجرا میکنید. با print(sys.path) مسیرهای جستوجو را ببینید و مطمئن شوید پوشهی درست در آن هست.
تفاوت import ماژول با from … import چیست؟
با import module کل ماژول را وارد میکنید و باید هنگام استفاده، نام ماژول را قبل از نام تابع بنویسید. با from module import name فقط نام مشخصی را وارد میکنید و مستقیم با همان نام کار میکنید. روش اول وضوح بیشتری دارد و روش دوم کوتاهتر است.