تنظيم ملفات مشروع بايثون: هيكل عملي للمبتدئين | بايثون بعد الأساسيات 2

عندما يبدأ مشروع بايثون بالتوسع، يصبح وضع كل الكود داخل main.py صعبًا في القراءة والصيانة. الحل ليس إنشاء عشرات المجلدات، بل تقسيم المشروع بحسب وظيفة كل جزء: ملف واضح للتشغيل، ملفات للكود المساعد، ومجلدات للبيانات أو الاختبارات عند الحاجة.

للمبتدئ، يمكن أن يبدأ المشروع المنظم بهذا الشكل البسيط:

my_project/
├── main.py
├── helpers.py
├── data/
│   └── users.txt
└── tests/
    └── test_helpers.py

هذا مجرد هيكل عملي كبداية وليس قاعدة إلزامية لكل مشروع. إذا كان برنامجك صغيرًا جدًا فقد يكفي ملف واحد، ومع نموه تفصل الأجزاء تدريجيًا بدل أن تبني Structure معقدًا من اليوم الأول.

سنطبق الفكرة على ملفات بايثون حقيقية، ونوضح متى تستخدم data/ وtests/ وrequirements.txt بدون الدخول في Packaging أو Architecture متقدمة.

{getToc} $title={محتوى المقال}

{alertInfo} القاعدة المختصرة: نظّم المشروع حسب المسؤولية، لا حسب عدد الملفات. لا تجعل كل دالة في ملف منفصل، ولا تترك كل منطق المشروع داخل main.py.

لماذا تحتاج إلى تنظيم ملفات مشروع بايثون؟

الملف الواحد مناسب للتجارب القصيرة. لكن عندما تبدأ بإضافة دوال، قراءة ملفات، حفظ بيانات، أو اختبارات، يصبح الفصل المنطقي مفيدًا؛ لأنه يجعل كل جزء أسهل في الفهم والتعديل وإعادة الاستخدام.

• يبقى main.py واضحًا كنقطة تشغيل.
• تنتقل الدوال المساعدة إلى ملفات مناسبة.
• تنفصل ملفات البيانات عن ملفات الكود.
• يمكن إضافة الاختبارات بدون خلطها بمنطق البرنامج.
• يصبح الانتقال إلى مشروع أكبر أسهل لاحقًا.

أبسط هيكل لمشروع صغير

إذا بدأ ملف واحد بالكبر، لا تحتاج فورًا إلى src/ أو Packages متعددة. غالبًا يكفي فصل منطق قابل لإعادة الاستخدام عن ملف التشغيل.

calculator_project/
├── main.py
└── calculator.py

داخل calculator.py نضع الوظيفة الحسابية:

def add(a, b):
    return a + b

ثم داخل main.py نستورد الدالة ونستخدمها:

from calculator import add

print(add(3, 5))

الناتج:

8

هنا أصبح main.py مسؤولًا عن تشغيل البرنامج، بينما يحتوي calculator.py على منطق يمكن إعادة استخدامه. وإذا أردت فهم import بتفصيل أكبر، راجع شرح import في بايثون للمبتدئين.

ما وظيفة main.py؟

main.py اسم شائع وواضح لملف تشغيل المشروع، لكنه ليس اسمًا إلزاميًا في بايثون. الأفضل ألا يتحول إلى ملف ضخم يحتوي كل شيء؛ اجعله يربط أجزاء المشروع ويبدأ التنفيذ.

from helpers import show_welcome

def main():
    show_welcome()
    print("البرنامج يعمل الآن")

if __name__ == "__main__":
    main()

فحص __name__ == "__main__" يجعل استدعاء main() يحدث عند تشغيل الملف مباشرة، ولا يجعله يعمل تلقائيًا إذا تم استيراد الملف من مكان آخر.

متى أقسم الكود إلى أكثر من ملف؟

لا يوجد عدد أسطر سحري يفرض عليك التقسيم. ابدأ عندما تلاحظ أن الملف يجمع مسؤوليات مختلفة أو أن جزءًا من الكود يمكن أن يعيش مستقلًا بوضوح.

الحالة	ما الأنسب؟
تجربة قصيرة أو سكربت صغير جدًا	ملف واحد قد يكون كافيًا.
بدأت تظهر دوال مساعدة كثيرة	انقلها إلى ملف مثل helpers.py أو اسم أدق حسب وظيفتها.
لديك بيانات CSV أو JSON أو TXT	ضعها في مجلد واضح مثل data/ عند الحاجة.
بدأ المشروع يحتاج اختبارات	أضف مجلد tests/.
ظهرت أجزاء مستقلة مثل مستخدمين وتخزين وتقارير	قسّمها إلى ملفات بأسماء المسؤوليات بدل ملف عام ضخم.

كيف يتغير الهيكل عندما يكبر المشروع؟

مشروع صغير قد يكون بهذه البساطة:

project/
├── main.py
├── helpers.py
└── data.json

أما مشروع بدأ يكبر فيمكن تنظيمه بشكل أوضح:

project/
├── main.py
├── users.py
├── storage.py
├── data/
├── tests/
└── requirements.txt

ليس الهدف استخدام هذه الأسماء حرفيًا؛ استخدم أسماء تصف مشروعك. مثلًا users.py أوضح من file1.py، وstorage.py أوضح من new.py.

تنظيم ملفات البيانات والمسارات

مجلد data/ Convention عملي لفصل ملفات الإدخال أو التخزين مثل CSV وJSON وTXT عن ملفات الكود. لكنه ليس قاعدة تفرضها بايثون.

عند بناء المسارات، انتبه إلى أن كتابة Path("data") وحدها تعتمد على مجلد التشغيل الحالي. إذا شغّلت البرنامج من مكان آخر قد يبحث عن الملف في موقع مختلف. في مشروع بسيط يمكنك تثبيت المسار بالنسبة إلى مكان main.py:

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent
DATA_DIR = BASE_DIR / "data"
DATA_DIR.mkdir(exist_ok=True)

USERS_FILE = DATA_DIR / "users.txt"

بهذا يصبح المسار مرتبطًا بمجلد المشروع نفسه بدل مكان تنفيذ الأمر. وللتوسع في قراءة وكتابة ملفات CSV داخل مشروع منظم، انتقل إلى الدرس التالي عن ملفات CSV داخل المشروع.

مجلد tests وملف requirements.txt

عندما تبدأ بكتابة اختبارات، افصلها داخل tests/ بدل وضع كود الاختبار داخل ملفات البرنامج. لا تحتاج هنا إلى تعلم pytest بالكامل؛ المهم أن تعرف أن الاختبارات لها مكان مستقل. وعندما تصل إلى هذه المرحلة يمكنك متابعة شرح pytest في بايثون للمبتدئين.

project/
├── main.py
├── helpers.py
└── tests/
    └── test_helpers.py

أما requirements.txt فهو مفيد في المشاريع البسيطة التي تعتمد على مكتبات خارجية. إذا كان مشروعك يستخدم المكتبة القياسية فقط، فلا تحتاج إلى إضافته لمجرد اكتمال الشكل.

requests
pandas

ولا يحتاج هذا المقال إلى شرح pip أو venv بالتفصيل؛ فهذه أدوات مستقلة عن هدفنا الأساسي وهو تنظيم الملفات.

مثال عملي كامل: مشروع أسماء بسيط

هذا مثال يجمع الفكرة بدون Structure زائد:

user_project/
├── main.py
├── helpers.py
└── data/
    └── users.txt

داخل helpers.py:

def clean_name(name):
    return name.strip().title()

داخل main.py:

from pathlib import Path
from helpers import clean_name

BASE_DIR = Path(__file__).resolve().parent
DATA_DIR = BASE_DIR / "data"
DATA_DIR.mkdir(exist_ok=True)
USERS_FILE = DATA_DIR / "users.txt"

name = clean_name("   ali   ")

with USERS_FILE.open("a", encoding="utf-8") as file:
    file.write(name + "\n")

print("تم حفظ الاسم:", name)

عند التشغيل تكون النتيجة:

تم حفظ الاسم: Ali

ويمتلك كل جزء مسؤولية واضحة: main.py يبدأ التنفيذ، وhelpers.py يحتوي منطق تنظيف الاسم، وdata/ يحتفظ بالبيانات.

أخطاء شائعة في تنظيم مشروع بايثون

• وضع كل شيء في main.py: افصل المسؤوليات عندما يبدأ الملف بجمع أجزاء مختلفة.
• تقسيم المشروع أكثر من اللازم: ليس كل Function بحاجة إلى ملف مستقل.
• أسماء غامضة: تجنب file1.py وnew.py واستخدم أسماء تصف الوظيفة.
• تسمية ملف باسم مكتبة: مثل json.py أو random.py أو pandas.py؛ فقد يحاول Python استيراد ملفك بدل المكتبة المقصودة.
• الاعتماد على Working Directory في المسارات: قد يعمل الكود من مجلد ويفشل من آخر.
• Circular Import: مثل أن يستورد a.py من b.py بينما يستورد b.py من a.py. إذا ظهر هذا النمط، راجع توزيع المسؤوليات بدل زيادة الاستيرادات المتبادلة.

هل كل مشروع يحتاج src أو Package؟

لا. المشروع التعليمي أو التطبيق الصغير لا يحتاج src/ أو Package كامل لمجرد أنه “منظم”. هذه الهياكل تصبح مفيدة في أنواع معينة من المشاريع الأكبر أو القابلة للتوزيع، لكن فرضها على المبتدئ قد يزيد التعقيد قبل الحاجة إليه.

وبالمثل، لا تحتاج إلى __init__.py في المثال البسيط الذي يفصل ملفين في المجلد نفسه. عندما تبدأ ببناء Packages فعلية، يصبح الموضوع أكثر ارتباطًا بنظام الاستيراد وPackaging ويستحق درسًا مستقلًا.

كيف تعرف أن Structure المشروع مناسب؟

• تستطيع معرفة وظيفة كل ملف من اسمه.
• main.py لا يحمل كل منطق البرنامج.
• الكود المرتبط بنفس المسؤولية موجود معًا.
• البيانات والاختبارات منفصلة عند الحاجة.
• لا توجد مجلدات أضفتها فقط لأنك رأيتها في مشروع كبير.

{alertSuccess} الخلاصة العملية: ابدأ بأبسط Structure يحافظ على الوضوح، ثم أضف ملفات ومجلدات عندما تظهر مسؤوليات جديدة فعلية، لا قبل ذلك.

الخطوة التالية

إذا كنت تريد الاستمرار داخل نفس المسار، راجع سلسلة بايثون بعد الأساسيات. وبعد فهم فصل الملفات والاستيراد، يمكنك تطبيق نفس الفكرة لاحقًا في برنامج CLI ببايثون.

أسئلة شائعة

كيف أنظم ملفات مشروع بايثون؟

ابدأ بملف تشغيل واضح مثل main.py، وانقل الوظائف المستقلة إلى ملفات بأسماء واضحة، وضع البيانات والاختبارات في مجلدات منفصلة عندما يحتاج المشروع ذلك.

هل يجب أن يكون لدي main.py؟

لا. main.py اسم شائع ومفهوم لملف التشغيل، لكنه ليس اسمًا إلزاميًا في بايثون.

متى أقسم الكود إلى أكثر من ملف؟

عندما يبدأ الملف بجمع مسؤوليات مختلفة، أو عندما يصبح لديك منطق تريد إعادة استخدامه أو اختباره بصورة مستقلة.

هل كل مشروع يحتاج مجلد src؟

لا. المشاريع الصغيرة والتعليمية يمكن أن تستخدم Structure أبسط بكثير. src Layout مفيد في بعض المشاريع الأكبر والقابلة للتوزيع، لكنه ليس قاعدة لكل مشروع.

أين أضع ملفات CSV وJSON؟

يمكن وضعها داخل مجلد مثل data/ إذا كان ذلك يجعل المشروع أوضح. الاسم Convention عملي وليس شرطًا من بايثون.

ما فائدة مجلد tests؟

يفصل كود الاختبارات عن كود البرنامج، ويصبح أكثر فائدة كلما بدأ المشروع يحتوي وظائف تحتاج إلى تحقق مستمر.