بناء مكتبة صغيرة

بناء مكتبة صغيرة — Build a Small Library

وصلنا إلى المختبر. لقد تعلمت ما هي الوحدة وما هي الحزمة وكيف تستورد منهما. الآن حان وقت التفكير كمهندس برمجيات حقيقي: كيف تُقرر ماذا تضع في أي ملف؟ ما الذي تُعيد تصديره؟ وكيف تبني واجهة نظيفة يسعد مستخدموها باستخدامها؟

هذا المختبر يأخذك خلال تصميم mathkit — مكتبة بسيطة للعمليات الحسابية والإحصائية. لن تُنشئ الملفات في هذا المتصفح (Pyodide بيئة ملف واحد)، لكنك ستُطبّق كل المفاهيم بالضبط كما يجري في مشروع حقيقي — فقط عبر تعريف الدوال مباشرة وتجربتها، مع رسم الهيكل أمامك.

السيناريو

تعمل على أداة تحليل درجات طلاب. تريد بناء حزمة mathkit يستطيع زملاؤك استيرادها وقول:

from mathkit import add, subtract, mean, median, variance

دون أن يعرفوا أين يوجد كل دالة داخلياً. هذا هو الهدف: واجهة نظيفة تُخفي التنظيم الداخلي.

هيكل `mathkit`

هكذا سيبدو المشروع الكامل:

my_project/
├── main.py              # البرنامج الذي يستخدم المكتبة — consumer
└── mathkit/             # الحزمة الرئيسية — the package
    ├── __init__.py      # واجهة المكتبة + إعادة التصدير — public API
    ├── arithmetic.py    # دوال الجمع والطرح — basic arithmetic
    └── stats.py         # دوال الإحصاء — statistical functions

ما يوجد في كل ملف

mathkit/arithmetic.py — يحمل العمليات الأساسية:

# mathkit/arithmetic.py

def add(a, b):
    """جمع عددين — Add two numbers."""
    return a + b

def subtract(a, b):
    """طرح عددين — Subtract two numbers."""
    return a - b

بسيط وواضح. هذه الوحدة تعرف شيئاً واحداً: الحساب الأساسي. لا تعرف شيئاً عن الإحصاء أو قواعد البيانات أو واجهة المستخدم.

mathkit/stats.py — يحمل العمليات الإحصائية:

# mathkit/stats.py
import math  # نستخدم math من المكتبة القياسية — use stdlib

def mean(values):
    """المتوسط الحسابي — Arithmetic mean of a list."""
    return sum(values) / len(values)

def median(values):
    """الوسيط — Middle value of a sorted list."""
    sorted_vals = sorted(values)
    n = len(sorted_vals)
    mid = n // 2
    if n % 2 == 1:
        return sorted_vals[mid]          # عدد فردي — odd count
    return (sorted_vals[mid - 1] + sorted_vals[mid]) / 2  # عدد زوجي — even count

def variance(values):
    """تباين المجتمع — Population variance."""
    avg = mean(values)
    return sum((x - avg) ** 2 for x in values) / len(values)

لاحظ كيف تستخدم stats.py دالة mean الموجودة في نفس الوحدة — هذا صحيح تماماً. لكنها لا تستورد من arithmetic.py لأن العمليتين مستقلتان.

mathkit/__init__.py — الواجهة العامة:

# mathkit/__init__.py

# نُعيد تصدير ما يحتاجه المستخدم — re-export the public API
from mathkit.arithmetic import add, subtract
from mathkit.stats import mean, median, variance

# نُعرّف ما يُصدَّر عند import * — define what's exported on star-import
__all__ = ["add", "subtract", "mean", "median", "variance"]

هذا الملف هو بوابة الحزمة. يُقرر ما الذي يراه المستخدم. إذا قررت لاحقاً نقل mean إلى وحدة مختلفة، يكفي تعديل هذا الملف — كل كود المستخدمين يبقى كما هو.

main.py — كيف يستخدم المستخدم الحزمة:

# main.py
from mathkit import add, mean, variance

scores = [75, 82, 91, 68, 95, 73]
print(f"المجموع: {add(75, 82)}")
print(f"المتوسط: {mean(scores):.2f}")
print(f"التباين: {variance(scores):.2f}")

لماذا هذا التقسيم؟

السؤال الحقيقي في تصميم الوحدات ليس “هل يعمل الكود؟” بل “هل سيكون الكود قابلاً للصيانة والتطوير؟”

مبدأ المسؤولية الواحدة (Single Responsibility): arithmetic.py تعرف الجمع والطرح. stats.py تعرف الإحصاء. لو أضفت لاحقاً geometry.py للأشكال الهندسية، ستفعل ذلك دون لمس الملفات الموجودة. هذا التصميم يجعل كل تغيير مركّزاً في مكان واضح.

إخفاء التعقيد: مستخدم المكتبة لا يحتاج أن يعرف أن mean في stats.py وadd في arithmetic.py. يكتب فقط from mathkit import mean, add ويمضي. هذا ما يُسمى بـ abstraction — تُخفي التعقيد خلف واجهة بسيطة.

المرونة في إعادة الهيكلة: لو قررت يوماً تقسيم stats.py إلى stats/central_tendency.py وstats/dispersion.py، يكفي تعديل __init__.py ولا شيء آخر. المستخدمون لن يلاحظوا الفرق.

قابلية الاختبار: يمكنك اختبار arithmetic.py بمعزل تام عن stats.py. لو كسر تعديل في الإحصاء، تختبر فقط stats.py. هذا يُقلل وقت التصحيح بشكل كبير.

متى تُقسّم ومتى لا؟

ليس كل وحدتين منفصلتين تستحقان حزمة. قاعدة عملية: إذا كان الكود سيُعاد استخدامه في أكثر من مشروع، أو كانت وحداتك تحمل مسؤوليات واضحة ومختلفة، ضعها في حزمة. إذا كان مشروعك ملفاً أو ملفين، لا داعي للتعقيد.

الأخطاء الشائعة في التنظيم:

مجلد utils يحمل كل شيء: عندما لا تعرف أين تضع الدالة، تضعها في utils. هذا المجلد يكبر حتى يصبح مستنقعاً. الحل: اسأل “ما المسؤولية الوحيدة لهذا الملف؟” ثم سمّه بناءً عليها.
ملف واحد لكل دالة: إنشاء ملف منفصل لكل دالة هو إفراط في التقسيم يُصعّب التنقل. كتلة وظيفية واحدة = ملف واحد.
تصدير كل شيء: ليس كل ما تكتبه يجب أن يكون في __init__.py. صدّر فقط ما تريد مستخدمك أن يعتمد عليه. كل اسم مُصدَّر هو وعد بالاستقرار.

تحديات المختبر

الآن طبّق ما تعلمته. كل تحدٍّ يُطبّق جزءاً من mathkit.

التحدي 1: دالة mean

تحدي — Challenge

# stats.py — وحدة الإحصاء — statistical module

def mean(values):
    # احسب المتوسط الحسابي — calculate arithmetic mean
    # اكتب الكود هنا — write your code here
    pass

# اختبر الدالة — test the function
print(f"متوسط [10, 20, 30]: {mean([10, 20, 30])}")
print(f"متوسط [5, 15]: {mean([5, 15])}")

التحدي 2: دالة median

تحدي — Challenge

# stats.py — دالة الوسيط — median function

def median(values):
    # رتّب القيم أولاً — sort values first
    sorted_vals = sorted(values)
    n = len(sorted_vals)
    mid = n // 2
    # إذا العدد فردي — if count is odd
    if n % 2 == 1:
        return sorted_vals[mid]
    # إذا العدد زوجي — if count is even
    # اكتب هنا متوسط القيمتين الوسطيتين — write average of two middle values
    pass

print(f"وسيط [1, 3, 5]: {median([1, 3, 5])}")
print(f"وسيط [1, 2, 3, 4]: {median([1, 2, 3, 4])}")

التحدي 3: دالة variance

تحدي — Challenge

# stats.py — تباين المجتمع — population variance

def mean(values):
    return sum(values) / len(values)

def variance(values):
    # تباين المجتمع — population variance
    # الخطوات:
    # 1. احسب المتوسط — compute mean
    # 2. لكل قيمة: احسب (x - mean)^2 — compute squared deviation for each value
    # 3. خذ متوسط المربعات — take mean of squared deviations
    # اكتب الكود هنا — write your code here
    pass

# هذه المجموعة تعطي تباين 4.0 بالضبط — this dataset gives exactly 4.0
data = [2, 4, 4, 4, 5, 5, 7, 9]
print(f"تباين {data}: {variance(data)}")

التحدي 4: تصميم الوحدات

هذا التحدي يختبر فهمك لأين تضع كل دالة في mathkit. أكمل الدوال لتُرجع اسم الوحدة الصحيح لكل دالة:

main.go

# تصميم mathkit — mathkit design decisions

def where_does_add_go():
    # دالة الجمع تنتمي لأي وحدة؟
    return "arithmetic.py"

def where_does_mean_go():
    # دالة المتوسط تنتمي لأي وحدة؟
    return "stats.py"

def where_does_public_api_go():
    # إعادة التصدير وتحديد الواجهة العامة تكون في أي ملف؟
    return "__init__.py"

def who_calls_which():
    # في main.py، إذا أردت add و mean بدون كتابة اسم الوحدة، ماذا تكتب؟
    return "from mathkit import add, mean"

print(f"add → {where_does_add_go()}")
print(f"mean → {where_does_mean_go()}")
print(f"الواجهة العامة → {where_does_public_api_go()}")
print(f"استيراد في main.py → {who_calls_which()}")

Output:

تحدي — Challenge

# أكمل دوال التصميم — complete the design functions

def where_does_add_go():
    # دالة الجمع في أي وحدة؟ — which module for add?
    return ""  # غيّر هذا — change this

def where_does_mean_go():
    # دالة المتوسط في أي وحدة؟ — which module for mean?
    return ""  # غيّر هذا — change this

def where_does_public_api_go():
    # إعادة التصدير في أي ملف؟ — which file for re-exports?
    return ""  # غيّر هذا — change this

def who_calls_which():
    # جملة الاستيراد في main.py — import statement in main.py
    return ""  # غيّر هذا — change this

print(f"add → {where_does_add_go()}")
print(f"mean → {where_does_mean_go()}")
print(f"الواجهة العامة → {where_does_public_api_go()}")
print(f"استيراد في main.py → {who_calls_which()}")

مكتبتك في العمل

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

main.go

# محاكاة mathkit كاملة في ملف واحد — full mathkit simulation in one file
# (في مشروع حقيقي، كل قسم في ملفه الخاص — in real project, each in its own file)

# === arithmetic.py ===
def add(a, b):
    """جمع عددين — Add two numbers."""
    return a + b

def subtract(a, b):
    """طرح عددين — Subtract two numbers."""
    return a - b

# === stats.py ===
def mean(values):
    """المتوسط الحسابي — Arithmetic mean."""
    return sum(values) / len(values)

def median(values):
    """الوسيط — Median value."""
    sorted_vals = sorted(values)
    n = len(sorted_vals)
    mid = n // 2
    if n % 2 == 1:
        return sorted_vals[mid]
    return (sorted_vals[mid - 1] + sorted_vals[mid]) / 2

def variance(values):
    """تباين المجتمع — Population variance."""
    avg = mean(values)
    return sum((x - avg) ** 2 for x in values) / len(values)

# === main.py — استخدام المكتبة — using the library ===
درجات_الطلاب = [72, 85, 91, 68, 78, 95, 82, 74, 88, 65]

print("=== تحليل درجات الطلاب ===")
print(f"عدد الطلاب: {len(درجات_الطلاب)}")
print(f"المتوسط: {mean(درجات_الطلاب):.1f}")
print(f"الوسيط: {median(درجات_الطلاب):.1f}")
print(f"التباين: {variance(درجات_الطلاب):.2f}")
print(f"الانحراف المعياري: {variance(درجات_الطلاب) ** 0.5:.2f}")
print(f"أعلى درجة: {max(درجات_الطلاب)}")
print(f"أدنى درجة: {min(درجات_الطلاب)}")
print(f"الفرق (max - min): {subtract(max(درجات_الطلاب), min(درجات_الطلاب))}")

Output:

خلاصة المختبر

صممت اليوم حزمة كاملة من الصفر. الأهم ليس حفظ الأوامر، بل فهم الأسئلة التي تطرحها على نفسك عند كل قرار:

قبل إنشاء ملف: ما المسؤولية الواحدة التي سيحملها هذا الملف؟ هل سيظل اسمه واضحاً بعد ستة أشهر؟

قبل تصدير دالة من __init__.py: هل يحتاج مستخدم الحزمة هذه الدالة فعلاً؟ أم أنها تفصيل داخلي؟

قبل كتابة import: هل الاستيراد المطلق أوضح هنا؟ أم أن الاستيراد النسبي يجعل الحزمة أكثر قابلية للنقل؟

هذه الأسئلة هي ما يُفرّق بين مطور يكتب كوداً يعمل، ومطور يكتب كوداً يعمل ويظل قابلاً للصيانة والنمو.

بناء مكتبة صغيرة