لتثبيت مشروع بايثون محلي في الوضع القابل للتحرير على نظام macOS، افتح Terminal، وانتقل إلى دليل المشروع، وأنشئ بيئة افتراضية وقم بتنشيطها، ثم شغّل python -m pip install -e .. يربط هذا عمليات استيراد بايثون بشجرة المصدر التي تعمل عليها، بحيث تصبح التغييرات التي تطرأ على ملفات بايثون متاحة في جلسات المترجم الفوري الجديدة دون إعادة التثبيت. لا يزال المشروع بحاجة إلى بيانات وصفية للتحزيم، ويعتمد السلوك الدقيق للوضع القابل للتحرير على خلفية البناء (build backend) الخاصة به.

ما يفعله التثبيت القابل للتحرير

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

كذلك، فإن الوضع القابل للتحرير لا يجعل تغييرات التبعيات (dependencies) تختفي تلقائيًا. يقوم pip بتثبيت التبعيات المصرح بها بواسطة المشروع بالطريقة المعتادة، ما لم تقم بتمرير --no-deps. تكون التغييرات التي تطرأ على التعليمات البرمجية المصدرية لبايثون مرئية بشكل عام في عملية التشغيل التالية، ولكن قد يتطلب التغيير في البيانات الوصفية للمشروع، أو البرامج النصية لسطر الأوامر التي تم إنشاؤها، أو الأكواد المترجمة (compiled code) إعادة التثبيت أو إعادة البناء. دليل مستخدم تحزيم بايثون: تحزيم المشاريع وتوزيعها

إعداد بيئة افتراضية على نظام macOS

في تطبيق Terminal، انتقل إلى المجلد الجذري للمشروع، وهو الدليل الذي يحتوي على pyproject.toml أو ملف setup.py القديم المدعوم. يفترض أمر cd أدناه أن المجلد موجود في دليلك الرئيسي؛ ضع المسار بين علامتي اقتباس إذا كان يحتوي على مسافات.

cd "$HOME/path/to/my-project"
python3 --version
python3 -m venv .venv
source .venv/bin/activate
python -m pip --version

تحافظ البيئة الافتراضية على الحزم المثبتة لهذا المشروع منفصلة عن بيئات بايثون الأخرى. بعد التنشيط، يجب أن يشير python إلى المترجم الفوري الخاص بالبيئة، لذا فإن استخدام python -m pip يربط pip بذلك المترجم الفوري. توضح وثائق بايثون أن venv ينشئ بيئات معزولة ويوثق أمر التنشيط لموجهات أوامر POSIX، بما في ذلك موجه الأوامر المستخدم افتراضيًا في إعدادات Terminal الحالية لنظام macOS. وثائق بايثون: venv

إذا تعذر العثور على python3، فقم بتثبيت مترجم بايثون 3 أو تحديد موقعه أولاً؛ فنظام macOS لا يضمن توفر بايثون جاهز للتطوير تحت هذا الأمر. إذا كان المشروع يحدد إصدار بايثون مدعومًا، فاستخدم هذا الإصدار لإنشاء .venv. تجنب تثبيت الحزم في إصدار بايثون المُدار بواسطة النظام عندما تفي بيئة المشروع بالغرض.

تثبيت المشروع في الوضع القابل للتحرير

مع تنشيط البيئة ووجود Terminal في الدليل الجذري للمشروع، شغّل:

python -m pip install -e .

هنا، يعني -e قابل للتحرير (editable) وتعني . الدليل الحالي. يتوقع pip أن يحتوي دليل المشروع المحلي على pyproject.toml أو setup.py. تصرح المشاريع الحديثة عادةً عن خلفية البناء في pyproject.toml؛ ويطلب pip من تلك الخلفية إجراء التثبيت القابل للتحرير. يجب أن تدعم خلفية البناء واجهة التثبيت القابل للتحرير حتى يعمل هذا على النحو المنشود. مرجع pip install، واجهة نظام بناء pip

للتثبيت من دليل مختلف، أدخل مساره بدلاً من .، على سبيل المثال python -m pip install -e "$HOME/path/to/my-project". وضع المسار بين علامتي اقتباس يحمي المسافات والرموز الخاصة بموجه الأوامر. ينطبق التثبيت على بيئة بايثون المرتبطة بأمر python الذي استخدمته.

تأكيد البيئة وتشخيص الأخطاء

تحقق من عرض المشاريع المثبتة في pip للتأكد من أنه يسرد الحزمة وموقع مشروعها القابل للتحرير:

python -m pip list

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

إذا أشار pip إلى أن الدليل غير قابل للتثبيت، فتحقق من أنك في الجذر الصحيح وأنه يحتوي على pyproject.toml أو setup.py. إذا رفضت خلفية البناء الوضع القابل للتحرير، فقم بتحديث خلفية المشروع أو تهيئتها وفقًا لوثائقها؛ فليست كل الخلفيات القديمة أو المخصصة تدعم عمليات التثبيت القابلة للتحرير. بالنسبة لمشروع pyproject.toml حديث، يستخدم pip خطاف PEP 660 القابل للتحرير الخاص بخلفية البناء. واجهة نظام بناء pip

إذا أدى تغيير في المشروع إلى إضافة تبعيات أو نقاط دخول (entry points) أو تغيير البيانات الوصفية، فأعد تشغيل python -m pip install -e .. بالنسبة للامتدادات المترجمة (compiled extensions)، قم بتشغيل خطوات البناء الموثقة للمشروع أيضًا. يلاحظ pip أن عمليات التثبيت القابلة للتحرير والعادية قد تتصرف بشكل مختلف، لذا فإن التثبيت القابل للتحرير مخصص للتطوير المحلي؛ ولا يغني عن التحقق من مسار التثبيت العادي قبل توزيع الحزمة. دليل pip لتثبيت المشاريع المحلية

المصادر