الوحدات والحزم — هياكل البيانات

الوحدات والحزم (Modules & Packages)

عندما يكبر البرنامج، وضع كل شيء في ملف واحد يجعله صعب القراءة والتعديل. الحل: تقسيم الكود إلى ملفات، كل ملف مسؤول عن جانب واحد.

الوحدة (Module)

أي ملف .py هو وحدة. إذا كان لديك geometry.py:

# geometry.py
PI = 3.14159

def circle_area(r):
    return PI * r ** 2

يمكنك استخدامه من ملف آخر في نفس المجلد:

# main.py
import geometry
print(geometry.circle_area(2))

from geometry import circle_area
print(circle_area(2))

طرق الاستيراد

| الصيغة | متى |

|---|---|

| import module | الأوضح: تعرف دائماً مصدر الدالة (math.sqrt) |

| from module import name | عندما تستخدم اسماً بكثرة |

| import module as alias | أسماء طويلة أو أعراف شائعة |

| from module import * | تجنبها: تجلب أسماء غير معروفة وقد تستبدل أسماءك |

if __name__ == "__main__"

عند استيراد وحدة، يُنفَّذ كل الكود الموجود في مستواها الأعلى. لكي تكتب كود تجربة لا يعمل إلا عند تشغيل الملف مباشرة:

def main():
    print(circle_area(3))

if __name__ == "__main__":
    main()

المتغير __name__ يساوي "__main__" عند تشغيل الملف مباشرة، ويساوي اسم الوحدة عند استيرادها.

الحزمة (Package)

مجلد يجمع عدة وحدات:

shop/
    __init__.py
    products.py
    cart.py
main.py

ثم: from shop.cart import add_item. ملف __init__.py يحدد أن المجلد حزمة ويمكن أن يكون فارغاً.

المكتبة القياسية

Python تأتي بمئات الوحدات الجاهزة: math, random, datetime, json, csv, pathlib, collections, statistics, re... قبل أن تكتب شيئاً بنفسك، ابحث إن كان موجوداً.

المكتبات الخارجية

مكتبات من مطورين آخرين تُثبَّت بأداة pip (مثل requests و pandas). ستتعلم إدارتها مع البيئات الافتراضية في دورة Python المتقدمة.

أخطاء شائعة

- تسمية ملفك random.py أو json.py: يستورد Python ملفك بدل الوحدة الأصلية.

- الاستيراد الدائري: a.py يستورد b.py و b.py يستورد a.py.

تمرين

قسّم مشروع دفتر الدرجات من دورة الأساسيات إلى وحدتين: grades.py للدوال الحسابية، و main.py لقائمة الأوامر، واستخدم if __name__ == "__main__".

import math
import statistics
import random
from datetime import date, timedelta
from collections import Counter
import json as js   # اسم مستعار (للتوضيح فقط)

# math
print(math.sqrt(16), math.ceil(4.2), math.floor(4.8))

# statistics بدل كتابة الدوال بأنفسنا
scores = [88, 92, 75, 92, 60]
print(statistics.mean(scores), statistics.median(scores), statistics.mode(scores))

# random مع seed للحصول على نتائج قابلة للتكرار
random.seed(7)
print(random.randint(1, 10), random.choice(["أ", "ب", "ج"]))

# datetime
today = date(2026, 1, 15)
print(today + timedelta(days=30))

# Counter
print(Counter("mississippi").most_common(2))

# json عبر الاسم المستعار
print(js.dumps({"lang": "Python"}))

# __name__ يساوي "__main__" لأننا نشغّل الملف مباشرة
def main():
    print("تشغيل مباشر للوحدة")

if __name__ == "__main__":
    main()