macOS पर src लेआउट का उपयोग करने वाले Python प्रोजेक्ट के लिए पैकेज डिस्कवरी कॉन्फ़िगर करने के लिए, pyproject.toml में setuptools को src पर इंगित करें, फिर पैकेज-नाम फ़िल्टर केवल तभी सेट करें जब आपको यह नियंत्रित करने की आवश्यकता हो कि कौन से पैकेज शिप होने हैं। एक पारंपरिक प्रोजेक्ट के लिए, setuptools अक्सर लेआउट का स्वचालित रूप से पता लगा सकता है; स्पष्ट (explicit) डिस्कवरी सेटिंग्स तब उपयोगी होती हैं जब आप पूर्वानुमेय समावेशन (inclusions) या बहिष्करण (exclusions) चाहते हैं। ये निर्देश setuptools पर लागू होते हैं, प्रत्येक Python बिल्ड बैकएंड पर नहीं।

प्रोजेक्ट संरचना और बिल्ड बैकएंड की जाँच करें

टर्मिनल से, प्रोजेक्ट रूट—pyproject.toml वाली फ़ोल्डर—पर जाएँ और macOS के डिफ़ॉल्ट शेल, zsh, या यदि bash आपका कॉन्फ़िगर किया गया शेल है, तो bash के साथ फ़ाइलों का निरीक्षण करें:

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

उद्धृत पथ (quoted path) को वास्तविक प्रोजेक्ट स्थान से बदलें। एकल उद्धरण (single quotes) किसी पथ में रिक्त स्थान और शेल मेटाकैरेक्टर को इंटरप्रेट होने से रोकते हैं। एक सामान्य पैकेज src/my_package/__init__.py पर स्थित हो सकता है, जिसके नीचे की डायरेक्टरीज़ में सबपैकेज होते हैं। आयात (import) नाम my_package है; src नाम की डायरेक्टरी केवल एक कंटेनर है और उस नाम का हिस्सा नहीं है।

जाँचें कि pyproject.toml, [build-system] के अंतर्गत setuptools का चयन करता है, उदाहरण के लिए 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 को बताता है कि पैकेज कहाँ ढूँढने हैं। यह प्रोजेक्ट का नाम या पैकेज का आयात (import) नाम नहीं बदलता है। यदि आपके पास पहले से ही [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 इन include और exclude पैटर्न के साथ-साथ where को अपने package discovery guide में प्रलेखित करता है।

चुनें कि डिस्कवरी नेमस्पेस पैकेजों को कैसे संभालती है

डिफ़ॉल्ट रूप से, setuptools की pyproject.toml डिस्कवरी अंतर्निहित (implicit) नेमस्पेस पैकेजों को स्कैन करती है: डायरेक्टरीज़ को पैकेज माना जा सकता है, भले ही उनमें __init__.py न हो। यदि आपका पैकेज जानबूझकर PEP 420 नेमस्पेस पैकेजों का उपयोग करता है, तो इस डिफ़ॉल्ट को बनाए रखें। यदि प्रत्येक पैकेज में __init__.py होना चाहिए, तो आप नेमस्पेस स्कैनिंग को बंद कर सकते हैं:

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

इस सेटिंग के साथ, बिना __init__.py वाली डायरेक्टरीज़ को पैकेज के रूप में नहीं खोजा जाता है। इसलिए बिल्ट डिस्ट्रीब्यूशन में किसी पैकेज के गायब होने की व्याख्या खोज स्थान (search location), किसी include या exclude पैटर्न, या नेमस्पेस सेटिंग द्वारा की जा सकती है। पैकेजिंग गाइड इस व्यवहार पर चर्चा करता है और दिखाता है कि डिस्कवरी को चयनित नेमस्पेस पैकेजों तक कैसे सीमित किया जा सकता है। Python Packaging User Guide: Packaging namespace packages

जानें कि स्वचालित डिस्कवरी कब पर्याप्त है

एक सीधे src/my_package प्रोजेक्ट के लिए, आपको डिस्कवरी टेबल की बिल्कुल भी आवश्यकता नहीं हो सकती है। जब packages और py-modules अनिर्दिष्ट छोड़ दिए जाते हैं, तो setuptools सामान्य लेआउट को पहचान सकता है। जब आपको पैकेज चयन को सीमित करने, कम पारंपरिक ट्री को संभालने, या स्रोत डायरेक्टरी को असंदिग्ध बनाने की आवश्यकता हो, तब स्पष्ट कॉन्फ़िगरेशन जोड़ें। पैकेज सूचियों को अलग से हार्ड-कोड करने से बचें, जब तक कि आप पैकेज ट्री में बदलाव के साथ उन्हें बनाए रखने का इरादा न रखते हों; स्पष्ट सूचियों के कारण नए जोड़े गए सबपैकेजों के छूट जाने की संभावना बढ़ जाती है।

एक src लेआउट का यह भी अर्थ है कि रिपॉजिटरी रूट से Python चलाने पर पैकेज स्वचालित रूप से इंपोर्ट पाथ पर नहीं आता है। यह अपेक्षित है: setuptools के दस्तावेज़ में उल्लेख किया गया है कि इस तरह से सोर्स चेकआउट से पैकेज का उपयोग करने के लिए एक संपादन योग्य इंस्टॉलेशन (editable install) की आवश्यकता होती है। डिस्कवरी कॉन्फ़िगरेशन यह नियंत्रित करता है कि डिस्ट्रीब्यूशन में क्या शामिल किया जाए; यह विकास के लिए आपके द्वारा उपयोग किए जाने वाले Python परिवेश में प्रोजेक्ट को स्थापित करने का विकल्प नहीं है। Setuptools: Package Discovery and Namespace Packages

स्रोत