آموزش ساخت و استفاده از ماژول در پایتون 3
وقتی تعداد خطوط کدتان از حدی میگذرد، پیدا کردن یک تابع ساده در میان انبوهی از کلاسها و متغیرها شبیه به پیدا کردن سوزن در انبار کاه میشود. از طرفی اگر بخواهید بخشی از آن کد را در پروژه دیگری استفاده کنید، چارهای جز کپیکردن ندارید که این کار نیز نگهداری و دیباگ را به شدت سخت میکند. اینجاست که ماژولها (Modules) به کمک شما میآیند. در این مقاله از بخش آموزش پایتون در بلاگ پارسپک، یاد میگیریم که ماژول پایتون چیست و چه انواعی دارد. سپس نحوه ساخت ماژول در پایتون ۳ را مرحلهبهمرحله مرور میکنیم.
ماژول پایتون فایلی با پسوند py. است که مجموعهای از توابع (Functions)، کلاسها (Classes) و متغیرها را در خود نگه میدارد. نام ماژول همان نام فایل بدون پسوند است. برای مثال، فایل hello.py به ماژولی با نام hello تبدیل میشود.
هدف اصلی ماژولها آن است که بهجای کپیکردن یک منطق تکراری در فایلهای مختلف، آن را یک بار در یک ماژول مجزا مینویسید و هر زمان که نیاز بود، با دستور import در سایر بخشهای پروژه فراخوانی میکنید. این ساختار ماژولار، نهتنها کدها را تمیز و خوانا نگه میدارد، بلکه فرایند دیباگ و توسعه پروژه را نیز بسیار سادهتر میکند.
هاست پایتون پارسپک یک سرویس کاربردی و پلتفرم هوشمند است که بسیاری از تسکهای تخصصی را به صورت خودکار انجام میدهد. با تهیه این سرویس از اتصال به آسان Git، مقیاسپذیری با سرعت و لحظهای و امنیت بالا بهرهمند میشوید.
ماژولها را از نظر منبع و نحوهی دسترسی، به سه دستهی اصلی تقسیم میکنند:
ماژولهای داخلی (Built-in) و کتابخانه استاندارد: این کتابخانهها همراه نصب پایتون در اختیار شما قرار میگیرند و نیازی به نصب جداگانه ندارند. مثال: os ، math ، sys و .datetime
ماژولهای شخص ثالث (Third-party): این ماژولها را توسعهدهندگان دیگر نوشتهاند و با ابزار pip نصب میشوند. مثال: requests، pandas و numpy.
ماژولهای اختصاصی (Custom): ماژولهایی که خودتان برای نیاز یک پروژه مینویسید و مبحث اصلی این آموزش هستند.
در پروژههای واقعی معمولا هر سه نوع در کنار هم استفاده میشوند.
اگر با پایتون آشنایی ندارید و خصوصیتهای آن را نمیشناسید، مقاله زیر را مطالعه کنید تا با همه نکات درباره آن آشنا شوید:
پایتون چیست؟
نگهداری تمام کدهای یک پروژه در یک فایل واحد تنها برای اسکریپتهای پردازشی بسیار کوچک توجیهپذیر است. با توسعه ساختار برنامه و بیشتر شدن خطوط کد، معماری ماژولار به یک الزام مهندسی تبدیل میشود. پیادهسازی منطق پروژه در قالب ماژولهای مجزا، دستاوردهای ساختاری زیر را به همراه دارد:
آموزش مفصل Doctest در پایتون را در مقالهی زیر بخوانید.
نوشتن Doctest در پایتون
در ادامه ابتدا پیشنیازها را میبینیم، بعد یک ماژول واقعی میسازیم و در آخر روشهای فراخوانی را مرور میکنیم:
برای ساخت ماژول در پایتون به ابزار پیچیدهای نیاز ندارید، اما چند مورد باید آماده باشد:
حالا یک ماژول ساده میسازیم. فایلی به نام 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 قابلخواندن است.
برای اینکه بدانید چطور اولین برنامه خود را در پایتون ۳ بنویسید و اجرا کنید، مقالهی زیر را بخوانید.
نوشتن اولین برنامه در پایتون 3
برای استفاده از ماژول، فایل دیگری مانند 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:Userssammymodules)، در حالی که فایل 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:Userssammymodules') 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:Userssammymodules"
برای ذخیرهی دائمی در ویندوز میتوانید از دستور زیر استفاده کنید. این دستور روی پنجرهی فعلی اثر نمیگذارد و باید ترمینال را ببندید و دوباره باز کنید:
setx PYTHONPATH "C:Userssammymodules"
توجه کنید که جداکنندهی مسیرها در لینوکس دونقطه (:) و در ویندوز نقطهویرگول (;) است. دستور 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 را در مقالهی زیر بخوانید.
نصب پایتون در CentOS
در فرایند توسعه و ساخت ماژولهای پایتون، برخورد با خطاهای بارگذاری بسیار رایج است. برای اینکه دیباگ (عیبیابی) کدها شتابانتر پیش برود، رایجترین خطاها و اصطلاحات آنها را به شکلی جامعا شفاف و ساده ارزیابی میکنیم:
این خطا نشانه آن است که مفسر پایتون نتوانسته ماژول شما را پیدا کند. این مشکل معمولا زمانی رخ میدهد که برنامه را از پوشه اشتباهی اجرا کردهاید یا محیط مجازی (Virtual Environment) شما فعال نیست.
راهکار: تحلیل کنید که مسیر اجرای برنامه درست باشد و آن را از پوشه اصلی پروژه (Root) اجرا کرده باشید.
فایل ماژول پیدا شده است، اما تابع یا متغیری که درخواست کردهاید داخل آن وجود ندارد. اشتباه تایپی در نام تابع، یا گیر افتادن در وابستگی دوری (Circular Import) از دلایل اصلی آن هستند. Circular Import به حالتی گفته میشود که فایل A برای اجرا به فایل B نیاز دارد و فایل B هم همزمان منتظر اجرای فایل A است و در حاصل مفسر قفل میشود.
راهکار: املای توابع را مرور کنید و اگر وابستگی دوری دارید، کدهای مشترک را به یک فایل سوم انتقال دهید.
شما نام یک فایل از پروژه خود را مشابه نام یکی از کتابخانههای اصلی پایتون انتخاب کردهاید. در این حالت، پایتون به جای کتابخانه اصلی، فایل شما را میخواند و چون توابع اصلی در آن نیستند، خطا میدهد. به این پدیده سایهاندازی (Shadowing) میگویند.
راهکار: نام فایل خود را تغییر دهید و پوشه __pycache__ را پاک کنید.
نکته:
پوشه pycache جایی است که پایتون کدهای ترجمهشده را به صورت موقت ذخیره میکند تا سرعت اجرای دفعات بعد بیشتر شود.
پایتون در لحظه فراخوانی یک ماژول، تمام کدهای آزاد داخل آن را یک بار اجرا میکند. اگر کدی مثل دستور print را بیرون از توابع نوشته باشید، با هر بار فراخوانی شدن به صورت خودکار اجرا میشود.
راهکار: کدهای تست خود را همیشه داخل بلوک شرطی if __name__ == “__main__”: قرار دهید. این شرط به پایتون میگوید: «این بخش از کد را فقط در صورتی اجرا کن که فایل به صورت مستقیم باز شده باشد، نه زمانی که در فایل دیگری فراخوانی شده است».
این ارور زمانی رخ میدهد که شما از مسیردهی نسبی استفاده کرده باشید، یعنی با علامت نقطه مشخص کردهاید که فایل کجاست، اما فایل را به صورت مستقیم اجرا کردهاید. پایتون هنگام اجرای مستقیم، ساختار پوشههای والد (Parent) را تشخیص نمیدهد.
راهکار: برنامه را به عنوان یک ماژول از ریشه پروژه اجرا کنید یا آدرسدهی را با نوشتن نام دقیق پوشهها از ابتدا تغییر دهید.
علت ایجاد این ارور آن است که یک بسته نرمافزاری را با ابزار pip داخل یک محیط نصب کردهاید، اما برنامه را با مفسر محیط دیگری اجرا میکنید.
راهکار: در محیط ترمینال دستورهای which python و python -m pip –version را وارد کنید تا اطمینان یابید هر دو ابزار به یک مسیر مشترک اشاره میکنند.
نشست تعاملی (Interactive Session) همان محیط ترمینال پایتون است که کدها را خطبهخط اجرا میکند. پایتون برای صرفهجویی در منابع، ماژولها را در حافظه پنهان (Cache) نگه میدارد. به همین دلیل دگرگونیها بهروز شما در کدهای ماژول، در ترمینال دیده نمیشوند.
راهکار: از دستور reload() از کتابخانه importlib استفاده کنید تا فایل به صورت اجباری دوباره بارگذاری شود یا اینکه محیط ترمینال را ببندید و دوباره باز کنید.
هاست پایتون دقیقاْ چیست و چرا باید هاست مناسب پایتون تهیه کنیم؟
هاست پایتون چیست؟
این سه اصطلاح در گفتوگوهای برنامهنویسی زیاد بهجای هم به کار میروند و همین باعث سردرگمی میشود. تفاوتشان در سطح سازماندهی کد است: ماژول کوچکترین واحد است، پکیج چند ماژول را کنار هم قرار میدهد و کتابخانه مجموعهی بزرگتری از کد برای یک هدف مشخص است. در ادامه هرکدام را جدا تحلیل میکنیم.
ماژول یک فایل پایتون (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 module کل ماژول را وارد میکنید و باید هنگام استفاده، نام ماژول را قبل از نام تابع بنویسید. با from module import name فقط نام مشخصی را وارد میکنید و مستقیم با همان نام کار میکنید. روش اول وضوح بیشتری دارد و روش دوم کوتاهتر است.
سوالات متداول
آموزش ساخت و استفاده از ماژول در پایتون 3 چیست؟
در این مطلب اطلاعات، جزئیات و نکات مرتبط با آموزش ساخت و استفاده از ماژول در پایتون 3 بررسی شده است.
مهمترین نکات درباره ماژول چیست؟
جزئیات مهم و نکات قابل توجه درباره ماژول در متن مقاله بررسی شده است.
چرا آموزش ساخت و استفاده از ماژول در پایتون 3 اهمیت دارد؟
این موضوع به دلیل اطلاعات و کاربردهای مرتبط، مورد توجه کاربران قرار گرفته است.
