كيفية إنشاء هيكل المشروع باستخدام Cookiecutter

أنت مثلي في أي شيء، “المماطلة” قد يكون أيضًا اسمك الأوسط. هناك دائمًا هذا التردد المزعج قبل البدء بمشروع جديد. مجرد التفكير في إعداد هيكل المشروع، أو إنشاء الوثائق، أو كتابة ملف README لائق، يكفي لإثارة التثاؤب. يبدو الأمر وكأنك تحدق في صفحة فارغة لمقال مدرسي مخيف. لكن تذكر كم يصبح الأمر أسهل عندما توفر بعض LLM المفيدة (مثل ChatGPT) نموذجًا للبدء؟ يمكن أن ينطبق نفس السحر على مشاريع البرمجة الخاصة بك. هذا هو المكان الذي يتدخل فيه Cookiecutter.

ما هو كوكي كتر؟

Cookiecutter هي أداة مفتوحة المصدر تساعدك على إنشاء قوالب المشروع. إنها لا تعرف اللغة وتعمل مع أي لغة برمجة تقريبًا (أو حتى خارج البرمجة، إذا كنت بحاجة إلى بنية موحدة للمجلدات والملفات). باستخدام Cookiecutter، يمكنك إعداد جميع الملفات النمطية (مثل ملفات README أو Dockerfiles أو أدلة المشروع أو أي شيء آخر)، ثم إنشاء مشاريع جديدة بسرعة بناءً على تلك البنية.

يتكون سير عمل Cookiecutter من ثلاث خطوات رئيسية:

1. يمكنك تحديد قالب المشروع الخاص بك.
2. يقوم المستخدم بإدخال قيم للمتغيرات التي تحددها.
3. يقوم برنامج Cookiecutter بإنشاء مشروع جديد، ويقوم تلقائيًا بملء الملفات والمجلدات والقيم المتغيرة بناءً على مدخلات المستخدم.

الصورة التالية توضح هذه العملية:

1. الإعداد الأساسي للكمبيوتر

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

• في نظام التشغيل Windows، اكتب “cmd” في شريط البحث وافتح “موجه الأوامر”.

• إذا لم تكن قد قمت بذلك بالفعل، قم بتثبيت pipx باستخدام:

pip install pipx

اختبر التثبيت الخاص بك عن طريق تشغيل:

pipx --version

إذا تلقيت خطأ “لم يتم العثور على الأمر”، أضف pipx إلى المسار الخاص بك. أولاً، ابحث عن مكان تثبيت pipx: python -m site –user-base.

قد يُرجع هذا شيئًا مثل /home/username/.local. ابحث عن المجلد الذي يحتوي على pipx.exe (على نظام Windows) أو pipx (على نظام macOS أو Linux). إذا لم تكن لديك حقوق المسؤول، فقد يكون الدليل هو C:\Users\username\AppData\Roaming\Python\Pythonxxx\Scripts.

اضطررت إلى إضافة pipx إلى المسار الخاص بي، وإذا لم تكن لديك حقوق المسؤول، فستحتاج إلى القيام بذلك في كل مرة تبدأ فيها نافذة طرفية جديدة. لذلك يوصى بإضافة الموقع بشكل دائم إلى إعدادات متغيرات البيئة لديك. ومع ذلك، إذا كان هذا الإعداد خلف امتيازات المسؤول، فلا يزال بإمكانك الإضافة

set PATH=C:\Users\username\AppData\Roaming\Python\Pythonxxx\Scripts;%PATH%

أو

set PATH=/home/username/.local/bin;%PATH%

نأمل أن تحصل على استجابة ذات مغزى ل pipx --version الآن.

2. تثبيت وإعداد Cookiecutter

يتم توزيع Cookiecutter كحزمة Python، لذا يمكنك تثبيتها باستخدام pipx:

pipx install cookiecutter

أو ببساطة قم بتشغيله سريعًا باستخدام:

pipx run cookiecutter ...

دعونا نسير عبر إنشاء قالب المشروع. في هذا المثال، سنقوم بإعداد قالب لتطبيقات Streamlit (cookiecutter_streamlit_ml).

3. إنشاء هيكل القالب

داخل مجلد cookiecutter_streamlit_ml الخاص بك، تحتاج إلى هذين المكونين الرئيسيين:

• cookiecutter.json – ملف JSON يحدد المتغيرات التي تريد من المستخدمين ملؤها (اسم المشروع، المؤلف، إصدار Python، وما إلى ذلك).

• {{ cookiecutter.directory_name }} – اسم مجلد نائب محدد باستخدام الأقواس المتعرجة. سيحتوي هذا الدليل على بنية المشروع الخاص بك وملفاته. عندما يقوم المستخدم بإنشاء مشروع جديد من القالب الخاص بك، سيقوم Cookiecutter باستبدال هذا العنصر النائب بالاسم الذي قدمه. احذري من الحفاظ على الأقواس المتعرجة!

قد يبدو ملف تعريف الارتباط الخاص بك على النحو التالي:

أولاً، عليك تحديد المتغيرات في ملف cookiecutter.json التي يتم استخدامها خلال المشروع الذي تم إنشاؤه. كحد أدنى، سوف تحتاج إلى متغير لاسم المشروع.

على سبيل المثال، كثيرًا ما أشير إلى مستودع GitHub الخاص بي في الوثائق. بدلاً من إدخاله بشكل متكرر، قمت بتعيين متغير مرة واحدة وأسمح لـ Cookiecutter بملء كل مثيل تلقائيًا. وبالمثل، لا أريد أن أكتب اسمي في كل ملف تمهيدي أو ملف توثيق، لذلك قمت بتعيينه في البداية.

لتجنب مشكلات Docker والتأكد من تحديد إصدار Python الصحيح، أطالب بإصدار Python عند إنشاء المشروع، مع التأكد من استخدامه في ملف Dockerfile الذي تم إنشاؤه.

يمكنك تحديد القيم الافتراضية لكل حقل في cookiecutter.json. سوف يقوم Cookiecutter تلقائيًا باستبدال كل مثيل لـ {{ cookiecutter.variable }} في ملفات القالب الخاصة بك بإدخال المستخدم. يمكنك أيضًا استخدام التحويلات مثل Lower() أو استبدال (‘ ‘, ‘_’) لتجنب المشكلات المتعلقة بالمسافات في أسماء الدليل.

في القالب الخاص بي، أفضل تقديم تعليمات مفصلة للمستخدمين بدلاً من تعيين القيم الافتراضية. يساعد هذا في توجيه أولئك الذين قد يتخطون قراءة الملف التمهيدي (README) وينتقلون مباشرة إلى إنشاء المشروع.

4. بناء القالب الخاص بك

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

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

بمجرد أن تصبح مجلداتك جاهزة، يمكنك ملؤها بالملفات. يمكن أن تكون إما فارغة أو حتى تحتوي على بعض المحتوى الذي قد تقوم بنسخه ولصقه باستمرار من مستندات أخرى. في هذه الملفات، قم بالرجوع إلى متغيرات ملف تعريف الارتباط الخاصة بك حيثما يلزم تعيين شيء ما ديناميكيًا (على سبيل المثال، اسم المشروع أو مستودع GitHub). سوف يقوم Cookiecutter تلقائيًا باستبدال هذه العناصر النائبة بإدخالات المستخدم، والتي سيتم طلبها أثناء إعداد المشروع. وهذا يوفر عليك الكثير من أعمال النسخ واللصق المملة، خاصة في ملفات الوثائق الخاصة بك.

وأخيرًا، قم بإيداع المجلد cookiecutter_py_streamlit بالكامل في حسابك على GitHub، أو قم بضغطه، أو اتركه كما هو. وفي كلتا الحالتين، يمكنك الآن…

5. استخدم القالب الخاص بك

بمجرد أن يصبح القالب الخاص بك جاهزًا، يصبح إنشاء مشروع جديد أمرًا سريعًا:

1. افتح جهازك وانتقل إلى المكان الذي ترغب في إنشاء المشروع فيه.

2. قم بتشغيل أحد الأوامر التالية:

• من جيثب:

pipx run cookiecutter gh:ElenJ/cookiecutter_streamlit_ml  (replace with your repo)

• من مجلد محلي:

pipx run cookiecutter /path/to/template_folder

• من ملف مضغوط:

pipx run cookiecutter /path/to/template.zip

3. سوف يطرح عليك برنامج Cookiecutter الأسئلة المحددة في ملف cookiecutter.json. قم بتوفير الإجابات — أو فقط اضغط على زر الإدخال إذا قمت بتعيين القيم الافتراضية.

4. لقد تم إنشاء مجلد مشروعك الجديد، مكتملًا بالمجلدات والملفات والمراجع المخصصة لمدخلاتك.

يمكنك مزامنة مشروعك الجديد مع GitHub إما عن طريق دفعه مباشرة من وظيفة Git المضمنة في IDE الخاص بك أو عن طريق إنشاء مستودع جديد على GitHub (التأكد من أنه فارغ ولا يتضمن مستندًا تمهيديًا) ثم نقل مجلد المشروع الذي تم إنشاؤه هناك.

وهذا كل شيء! لقد حولت ما كان في السابق عملاً روتينيًا يستغرق يومًا كاملاً إلى عملية سريعة وقمت على الفور بإنشاء الكثير من الملفات التي تنتظر ملؤها بأفكارك. عند النظر إلى المشروع الجديد، يجب أن تشعر بالتأكيد بيوم مثمر. إذا كنت لا تزال تبحث عن إرشادات حول أفضل الممارسات، فاطلع على قوالب Cookiecutter الرسمية هنا.

وكما هو الحال دائما: ترميز سعيد!