لتكوين اكتشاف الحزم لمشروع Python يستخدم تخطيط src على macOS، وجّه setuptools إلى src في pyproject.toml، ثم اضبط عوامل تصفية أسماء الحزم فقط إذا كنت بحاجة إلى التحكم في الحزم التي يتم شحنها. بالنسبة للمشاريع التقليدية، يمكن لـ setuptools غالبًا اكتشاف التخطيط تلقائيًا؛ وتكون إعدادات الاكتشاف الصريحة مفيدة عندما تريد عمليات تضمين أو استبعاد يمكن التنبؤ بها. تنطبق هذه التعليمات على setuptools، وليس على كل خلفية بناء (build backend) في Python.

التحقق من بنية المشروع وخلفية البناء

من Terminal، انتقل إلى المجلد الجذري للمشروع — المجلد الذي يحتوي على pyproject.toml — وافحص الملفات باستخدام غلاف macOS الافتراضي، zsh، أو باستخدام bash إذا كان هو الغلاف المكوّن لديك:

cd '/path/to/project'
find src -maxdepth 3 -type f -print

استبدل المسار الموجود بين علامتي الاقتباس بالموقع الفعلي للمشروع. تمنع علامات الاقتباس المفردة تفسير المسافات والأحرف الوصفية للغلاف (shell metacharacters) في المسار. قد توجد الحزمة النموذجية في src/my_package/__init__.py، مع وجود حزم فرعية في دلائل أسفلها. اسم الاستيراد هو my_package؛ أما الدليل المسمى src فهو مجرد حاوية وليس جزءًا من هذا الاسم.

تحقق من أن pyproject.toml يحدد setuptools أسفل [build-system]، على سبيل المثال باستخدام requires = ["setuptools>=61"] و build-backend = "setuptools.build_meta". تصف وثائق setuptools الاكتشاف التلقائي للتخطيطات الشائعة، بما في ذلك src، عندما لا يتم توفير قوائم الحزم والوحدات النمطية بشكل صريح. تمتلك الخلفيات الأخرى تكويناتها الخاصة، لذا لا تنسخ إعدادات setuptools إلى جدول تكوين خلفية أخرى. Setuptools: Configuring setuptools using pyproject.toml files

تكوين الاكتشاف الصريح في pyproject.toml

إذا كنت تريد أن يكون الاكتشاف متجذرًا على وجه التحديد في src، فأضف تكوين setuptools التالي إلى الملف الحالي:

[tool.setuptools.packages.find]
where = ["src"]

يخبر هذا setuptools بمكان البحث عن الحزم. ولا يغير اسم المشروع أو اسم استيراد الحزمة. إذا كان لديك بالفعل جدول [tool.setuptools.packages.find]، فقم بتعديل ذلك الجدول بدلاً من إضافة جدول ثانٍ. لا يمكن لملفات TOML أن تحتوي على تعريفات مكررة لنفس الجدول.

لتقييد الاكتشاف بحزمة واحدة وحزمها الفرعية، أضف نمط include يطابق اسم الحزمة الكامل المفصول بنقاط:

[tool.setuptools.packages.find]
where = ["src"]
include = ["my_package*"]

استبدل my_package بالاسم الفعلي لحزمة الاستيراد. يسمح الرمز * للنمط بمطابقة الحزم الفرعية مثل my_package.tools؛ حيث تتم مطابقة الأنماط مع أسماء الحزم الكاملة. يمكنك أيضًا استبعاد حزم محددة، على سبيل المثال exclude = ["my_package.tests*"]. توثق Setuptools أنماط التضمين والاستبعاد هذه، بالإضافة إلى where، في دليل اكتشاف الحزم الخاص بها.

اختيار كيفية تعامل الاكتشاف مع حزم مساحة الاسم (namespace packages)

بشكل افتراضي، يقوم اكتشاف pyproject.toml في setuptools بفحص حزم مساحة الاسم الضمنية: يمكن معاملة الدلائل كحزم حتى عندما لا تحتوي على __init__.py. احتفظ بهذا الإعداد الافتراضي إذا كانت حزمتك تستخدم عن قصد حزم مساحة الاسم وفقًا للمعيار PEP 420. وإذا كان يجب أن تحتوي كل حزمة على __init__.py، فيمكنك إيقاف تشغيل فحص مساحة الاسم:

[tool.setuptools.packages.find]
where = ["src"]
namespaces = false

باستخدام هذا الإعداد، لن يتم اكتشاف الدلائل التي لا تحتوي على __init__.py كحزم. وبالتالي، قد يرجع سبب عدم وجود حزمة ما في التوزيع المُنشأ إما إلى موقع البحث، أو نمط include أو exclude، أو إعداد مساحة الاسم. يناقش دليل التحزيم هذا السلوك ويوضح كيفية تقييد الاكتشاف بحزم مساحة اسم محددة. Python Packaging User Guide: Packaging namespace packages

معرفة متى يكون الاكتشاف التلقائي كافيًا

بالنسبة لمشروع بسيط ذي هيكل src/my_package، قد لا تحتاج إلى جدول اكتشاف على الإطلاق. يمكن لـ Setuptools التعرف على التخطيطات الشائعة عندما تُترك packages و py-modules غير محددة. أضف تكوينًا صريحًا عندما تحتاج إلى تضييق نطاق اختيار الحزم، أو التعامل مع بنية شجرية أقل تقليدية، أو جعل دليل المصدر لا لبس فيه. تجنب كتابة قوائم الحزم يدويًا بشكل منفصل إلا إذا كنت تنوي صيانتها كلما تغيرت شجرة الحزم؛ فالقوائم الصريحة قد تجعل من السهل إغفال الحزم الفرعية المضافة حديثًا.

يعني تخطيط src أيضًا أن تشغيل Python من جذر المستودع لا يضع الحزمة تلقائيًا في مسار الاستيراد. هذا أمر متوقع: تشير وثائق setuptools إلى الحاجة إلى تثبيت قابل للتعديل (editable install) لاستخدام الحزمة من النسخة المستخرجة من المصدر بهذه الطريقة. يتحكم تكوين الاكتشاف فيما يتم تضمينه في التوزيع؛ وهو ليس بديلاً عن تثبيت المشروع في بيئة Python التي تستخدمها للتطوير. Setuptools: Package Discovery and Namespace Packages

المصادر