निर्भरता आंतरिकीकरण रणनीति

नीति

Apothem का स्व-निहित रनटाइम यह अपेक्षा करता है कि इंजन की तृतीय-पक्ष निर्भरताएँ स्रोत वृक्ष से ही आयात-योग्य हों। इसलिए प्रत्येक रनटाइम निर्भरता को तीन में से किसी एक तरीके से संभाला जाता है:

• शुद्ध-Python स्रोत के रूप में आंतरिक की गई — src/apothem/_vendor/ के अंतर्गत। बूटस्ट्रैप उस डायरेक्टरी को site-packages से आगे, sys.path के अग्रभाग में रखता है, जिससे आंतरिक की गई प्रति किसी भी सिस्टम-संस्थापित संस्करण के विरुद्ध आयात समाधान की दौड़ जीत जाती है।
• शुद्ध-Python शिम से प्रतिस्थापित — जब उद्गम वितरण एक संकलित एक्सटेंशन के साथ आता है जो पोर्टेबल स्रोत के रूप में यात्रा नहीं कर सकता।
• एक प्रलेखित सिस्टम पूर्वापेक्षा के रूप में रखी गई — जब आंतरिकीकरण से जितनी बचत हो उससे अधिक सतह उठानी पड़े।

स्थापन नियम कठोर है: केवल शुद्ध-Python वितरण ही _vendor/ में रहते हैं। एक संकलित एक्सटेंशन (C, Rust/PyO3, Cython) प्लेटफ़ॉर्म- और ABI-विशिष्ट होता है और वहाँ कभी नहीं रहता। प्रत्येक आंतरिक किया गया पैकेज अपनी उद्गम लाइसेंस फ़ाइल को स्रोत के साथ-साथ ले चलता है।

क्या आंतरिक किया जाता है

rpds शिम

उद्गम jsonschema, rpds-py पर निर्भर करता है — Rust (PyO3) में कार्यान्वित एक स्थायी-डेटा-संरचना पुस्तकालय जो केवल एक पतले .py रैपर के साथ एक संकलित .pyd/.so भेजता है। प्रतिलिपि करने योग्य कोई पोर्टेबल शुद्ध-Python स्रोत नहीं है, इसलिए इसे आंतरिक नहीं किया जा सकता।

इसके बजाय, src/apothem/_vendor/rpds/ एक शुद्ध-Python शिम है जो ठीक उसी API उपसमुच्चय को पुनः-कार्यान्वित करता है जिसे jsonschema और referencing प्रयोग करते हैं — HashTrieMap, HashTrieSet, और List — अंतर्निर्मित dict / frozenset / tuple द्वारा समर्थित। यह शिम उद्गम स्थायित्व अनुबंध का सम्मान करता है: परिवर्तनकारी विधियाँ एक नया उदाहरण लौटाती हैं और प्राप्तकर्ता को अपरिवर्तित छोड़ती हैं, जिस पर उपभोक्ता तब निर्भर करते हैं जब वे इन संरचनाओं को फ़्रोज़न-क्लास के क्षेत्र-डिफ़ॉल्ट के रूप में संग्रहीत करते हैं। Apothem की स्कीमाएँ छोटी हैं, इसलिए Rust कार्यान्वयन की तुलना में निष्पादन अंतर अप्रासंगिक है।

क्या आंतरिक नहीं किया जाता

• click — CLI फ़्रेमवर्क। यह बड़ा, टर्मिनल-मुखी, और व्यापक रूप से उपलब्ध है, इसलिए यह एक सिस्टम पूर्वापेक्षा बनी रहती है जिसकी जाँच संस्थापक करते हैं।
• rich — टर्मिनल-रेंडरिंग पुस्तकालय, उन्हीं कारणों से एक सिस्टम पूर्वापेक्षा के रूप में रखा गया।
• rpds-py — संकलित; ऊपर के शिम से प्रतिस्थापित।
• libyaml C एक्सटेंशन — वैकल्पिक; आंतरिक किया गया शुद्ध-Python yaml पैकेज इसकी कभी आवश्यकता नहीं रखता।

संस्थापक कुछ भी करने से पहले सत्यापित करते हैं कि चयनित इंटरप्रेटर के अंतर्गत click और rich आयात-योग्य हैं; यदि कोई एक अनुपस्थित हो, तो वे उसका नाम बताते हैं और उसे आपके लिए संस्थापित करने का प्रस्ताव देते हैं — आपकी पुष्टि के साथ, या --yes / APOTHEM_AUTO_INSTALL_DEPS=1 से स्वचालित रूप से।

आंतरिक किए गए पैकेज को ताज़ा करना

किसी आंतरिक किए गए पैकेज को नवीनतर उद्गम संस्करण में अद्यतन करने के लिए:

1. लक्षित संस्करण पर उद्गम स्रोत वितरण प्राप्त करें।
2. शुद्ध-Python पैकेज डायरेक्टरी को src/apothem/_vendor/ में प्रतिलिपि करें, पिछली प्रति को प्रतिस्थापित करते हुए, और निकटवर्ती लाइसेंस फ़ाइल को ताज़ा करें।
3. src/apothem/_vendor/vendor.txt — पिन किया गया क्लोज़र — अद्यतन करें ताकि उसकी उस पैकेज की name==version पंक्ति नए उद्गम संस्करण से मेल खाए, और यदि पैकेज का उद्गम लाइसेंस या कॉपीराइट बदला हो तो मूल REUSE.toml में उस पैकेज का [[annotations]] ब्लॉक अद्यतन करें। दोनों ही प्रतिलिपि के समान परिवर्तन-समुच्चय में आवश्यक हैं (जीवित-निर्भरताएँ अधिदेश); आपूर्ति-शृंखला अंकेक्षक और reuse lint द्वार उन्हें पढ़ते हैं।
4. आयात पथ अछूते छोड़ दें — उपभोक्ता विहित नामों को आयात करते हैं और बूटस्ट्रैप की sys.path अधिमान्यता शेष कार्य कर देती है।
5. परीक्षण सूट और अनुरूपता द्वार चलाएँ; सत्यापन स्टैक का व्यवहार profile और स्कीमा सत्यापन परीक्षणों द्वारा कवर है।

rpds शिम को भिन्न ढंग से ताज़ा किया जाता है: यह उस API उपसमुच्चय का अनुसरण करता है जिसका इसके उपभोक्ता उपयोग करते हैं, इसलिए एक jsonschema/referencing अद्यतन को शिम की कार्यान्वित सतह के विरुद्ध जाँचा जाता है, और शिम केवल तभी बढ़ता है जब कोई नया कॉल-स्थल प्रकट होता है।

अनुशंसित अगला कदम

स्व-निहित रनटाइम पृष्ठ पढ़ें यह देखने के लिए कि आंतरिक किया गया वृक्ष, PYTHONPATH=src आह्वान मॉडल, और प्लगइन-ट्री बूटस्ट्रैप रनटाइम पर कैसे एक साथ जुड़ते हैं।