योगदान गाइड
हम चाहेंगे कि आप पायडेंटिक में अपना योगदान दें!
समस्याएँ¶
चर्चा या मुद्दे के रूप में प्रश्न, फीचर अनुरोध और बग रिपोर्ट सभी का स्वागत है। हालाँकि, सुरक्षा भेद्यता की रिपोर्ट करने के लिए, कृपया हमारी सुरक्षा नीति देखें।
आपकी सहायता करना हमारे लिए यथासंभव सरल बनाने के लिए, कृपया अपने अंक में निम्नलिखित कॉल का आउटपुट शामिल करें:
python -c "import pydantic.version; print(pydantic.version.version_info())"
यदि आप v2.0 से पहले पाइडेंटिक का उपयोग कर रहे हैं तो कृपया इसका उपयोग करें:
python -c "import pydantic.utils; print(pydantic.utils.version_info())"
यदि आप v1.3 (जब संस्करण_इन्फो() जोड़ा गया था) से पहले पाइडेंटिक का उपयोग कर रहे हैं, तो कृपया मैन्युअल रूप से ओएस, पायथन संस्करण और पाइडेंटिक संस्करण शामिल करें।
कृपया उपरोक्त को हमेशा शामिल करने का प्रयास करें जब तक कि आप पाइडेंटिक इंस्टॉल करने में असमर्थ न हों या यह न जानते हों कि यह आपके प्रश्न या सुविधा अनुरोध के लिए प्रासंगिक नहीं है।
अनुरोध खींचें¶
आरंभ करना और पुल अनुरोध बनाना अत्यंत सरल होना चाहिए। पाइडेंटिक नियमित रूप से जारी किया जाता है, इसलिए आपको कुछ ही दिनों या हफ्तों में अपने सुधार जारी होते दिखेंगे।
जब तक आपका परिवर्तन मामूली न हो (टाइपो, डॉक्स ट्विक आदि), कृपया पुल अनुरोध बनाने से पहले परिवर्तन पर चर्चा करने के लिए एक मुद्दा बनाएं।
!!! ध्यान दें "Pydantic V1 रखरखाव मोड में है" Pydantic v1 रखरखाव मोड में है, जिसका अर्थ है कि केवल बग फिक्स और सुरक्षा सुधार स्वीकार किए जाएंगे। नई सुविधाओं को Pydantic v2 पर लक्षित किया जाना चाहिए।
To submit a fix to Pydantic v1, use the `1.10.X-fixes` branch.
यदि आप अपने दाँत लगवाने के लिए किसी चीज़ की तलाश में हैं, तो इसे देखें "मदद अपेक्षित" जीथब पर लेबल।
योगदान को यथासंभव आसान और तेज़ बनाने के लिए, आप स्थानीय स्तर पर परीक्षण और लिंटिंग चलाना चाहेंगे। सौभाग्य से, पाइडेंटिक में कुछ निर्भरताएँ हैं, संकलन की आवश्यकता नहीं है और परीक्षणों को डेटाबेस आदि तक पहुंच की आवश्यकता नहीं है। इस वजह से, परीक्षणों को स्थापित करना और चलाना बहुत सरल होना चाहिए।
!!! बख्शीश tl;dr: फ़ॉर्मेटिंग को ठीक करने, परीक्षण और लाइनिंग चलाने और दस्तावेज़ बनाने के लिए मेक फ़ॉर्मेट का उपयोग करें दस्तावेज़ बनाने के लिए.
आवश्यक शर्तें¶
आपको निम्नलिखित शर्तों की आवश्यकता होगी:
- Python 3.8 और 3.11 के बीच कोई भी Python संस्करण
- वर्चुअलएन्व या अन्य वर्चुअल वातावरण उपकरण
- गिट
- बनाना
- पीडीएम
स्थापना और सेटअप¶
GitHub पर रिपॉजिटरी को फोर्क करें और अपने फोर्क को स्थानीय रूप से क्लोन करें।
# Clone your fork and cd into the repo directory
git clone git@github.com:<your username>/pydantic.git
cd pydantic
# Install PDM and pre-commit
# We use pipx here, for other options see:
# https://pdm.fming.dev/latest/#installation
# https://pre-commit.com/#install
# To get pipx itself:
# https://pypa.github.io/pipx/
pipx install pdm
pipx install pre-commit
# Install pydantic, dependencies, test dependencies and doc dependencies
make install
एक नई शाखा की जाँच करें और अपने परिवर्तन करें¶
अपने परिवर्तनों के लिए एक नई शाखा बनाएँ।
# Checkout a new branch and make your changes
git checkout -b my-new-feature-branch
# Make your changes...
परीक्षण और लाइनिंग चलाएँ¶
यह सुनिश्चित करने के लिए कि सब कुछ अपेक्षा के अनुरूप काम कर रहा है, स्थानीय स्तर पर परीक्षण और लिंटिंग चलाएँ।
# Run automated code formatting and linting
make format
# Pydantic uses ruff, an awesome Python linter written in rust
# https://github.com/astral-sh/ruff
# Run tests and linting
make
# There are a few sub-commands in Makefile like `test`, `testcov` and `lint`
# which you might want to use, but generally just `make` should be all you need.
# You can run `make help` to see more options.
दस्तावेज़ीकरण बनाएँ¶
यदि आपने दस्तावेज़ में कोई बदलाव किया है (फ़ंक्शन हस्ताक्षर, क्लास परिभाषाएँ, या एपीआई दस्तावेज़ में दिखाई देने वाले डॉकस्ट्रिंग्स में परिवर्तन सहित), तो सुनिश्चित करें कि यह सफलतापूर्वक बन गया है।
# Build documentation
make docs
# If you have changed the documentation, make sure it builds successfully.
# You can also use `pdm run mkdocs serve` to serve the documentation at localhost:8000
प्रतिबद्ध रहें और अपने बदलावों को आगे बढ़ाएं¶
अपने परिवर्तन करें, अपनी शाखा को GitHub पर धकेलें, और एक पुल अनुरोध बनाएं।
कृपया पुल अनुरोध टेम्पलेट का पालन करें और यथासंभव अधिक जानकारी भरें। किसी भी प्रासंगिक मुद्दे से लिंक करें और अपने परिवर्तनों का विवरण शामिल करें।
जब आपका पुल अनुरोध समीक्षा के लिए तैयार हो, तो "कृपया समीक्षा करें" संदेश के साथ एक टिप्पणी जोड़ें और हम जितनी जल्दी हो सके इस पर विचार करेंगे।
कोड शैली और आवश्यकताएँ¶
सभी
दस्तावेज़ीकरण शैली¶
दस्तावेज़ीकरण मार्कडाउन में लिखा गया है और MkDocs के लिए सामग्री का उपयोग करके बनाया गया है। एपीआई दस्तावेज़ीकरण mkdocstrings का उपयोग करके डॉकस्ट्रिंग्स से बनाया गया है।
कोड दस्तावेज़ीकरण¶
पाइडेंटिक में योगदान करते समय, कृपया सुनिश्चित करें कि सभी कोड अच्छी तरह से प्रलेखित हैं। उचित रूप से स्वरूपित डॉकस्ट्रिंग्स का उपयोग करके निम्नलिखित को प्रलेखित किया जाना चाहिए:
- मॉड्यूल
- वर्ग परिभाषाएँ
- फ़ंक्शन परिभाषाएँ
- मॉड्यूल-स्तरीय चर
पाइडेंटिक पीईपी 257 दिशानिर्देशों के अनुसार स्वरूपित Google-शैली डॉकस्ट्रिंग्स का उपयोग करता है। (आगे के उदाहरणों के लिए उदाहरण Google स्टाइल पायथन डॉकस्ट्रिंग्स देखें।)
पाइडोकस्टाइल का उपयोग डॉकस्ट्रिंग्स को लाइन करने के लिए किया जाता है। आप अपने डॉकस्ट्रिंग्स की जांच करने के लिए मेक फॉर्मेट चला सकते हैं।
जहां यह Google-शैली डॉकस्ट्रिंग्स और पाइडोकस्टाइल लिंटिंग के बीच विरोधाभास है, वहां पाइडोकस्टाइल लिंटिंग संकेतों का पालन करें।
वर्ग विशेषताओं और फ़ंक्शन तर्कों को "नाम: विवरण" प्रारूप में प्रलेखित किया जाना चाहिए। जब लागू हो, रिटर्न प्रकार को केवल विवरण के साथ प्रलेखित किया जाना चाहिए। हस्ताक्षर से प्रकार का अनुमान लगाया जाता है।
class Foo:
"""A class docstring.
Attributes:
bar: A description of bar. Defaults to "bar".
"""
bar: str = 'bar'
def bar(self, baz: int) -> str:
"""A function docstring.
Args:
baz: A description of `baz`.
Returns:
A description of the return value.
"""
return 'bar'
आप डॉकस्ट्रिंग्स में उदाहरण कोड शामिल कर सकते हैं। यह कोड पूर्ण, स्व-निहित और चलाने योग्य होना चाहिए। डॉकस्ट्रिंग उदाहरणों का परीक्षण डॉक्टेस्ट का उपयोग करके किया जाता है, इसलिए सुनिश्चित करें कि वे सही और पूर्ण हैं। उदाहरण के लिए FieldInfo.from_annotated_attribute() देखें।
!!! नोट "क्लास और इंस्टेंस विशेषताएँ" क्लास विशेषताओं को क्लास डॉकस्ट्रिंग में प्रलेखित किया जाना चाहिए।
Instance attributes should be documented as "Args" in the `__init__` docstring.
दस्तावेज़ीकरण शैली¶
सामान्य तौर पर, दस्तावेज़ीकरण को मैत्रीपूर्ण, सुलभ शैली में लिखा जाना चाहिए। इसे पढ़ना और समझना आसान होना चाहिए, और पूर्ण होते हुए भी यथासंभव संक्षिप्त होना चाहिए।
कोड उदाहरणों को प्रोत्साहित किया जाता है, लेकिन उन्हें संक्षिप्त और सरल रखा जाना चाहिए। हालाँकि, प्रत्येक कोड उदाहरण पूर्ण, स्व-निहित और चलाने योग्य होना चाहिए। (यदि आप निश्चित नहीं हैं कि यह कैसे करना है, तो मदद मांगें!) हम नग्न एसेट की तुलना में प्रिंट आउटपुट को प्राथमिकता देते हैं, लेकिन यदि आप किसी ऐसी चीज़ का परीक्षण कर रहे हैं जिसमें उपयोगी प्रिंट आउटपुट नहीं है, तो एस्टर ठीक हैं।
पाइडेंटिक का यूनिट परीक्षण दस्तावेज़ीकरण में सभी कोड उदाहरणों का परीक्षण करेगा, इसलिए यह महत्वपूर्ण है कि वे सही और पूर्ण हों। नया कोड उदाहरण जोड़ते समय, उदाहरणों का परीक्षण करने और उनके स्वरूपण और आउटपुट को अपडेट करने के लिए निम्नलिखित का उपयोग करें:
# Run tests and update code examples
pytest tests/test_docs.py --update-examples
पायथन और जंग को डीबग करना¶
यदि आप पाइडेंटिक और पाइडेंटिक-कोर के साथ काम कर रहे हैं, तो आपको पायथन और रस्ट कोड को एक साथ डीबग करने में मदद मिल सकती है। यह कैसे करना है इस पर एक त्वरित मार्गदर्शिका यहां दी गई है। यह ट्यूटोरियल VSCode में किया गया है, लेकिन आप अन्य IDE में समान चरणों का उपयोग कर सकते हैं।
बैज¶
पाइडेंटिक के पास एक बैज है जिसका उपयोग आप यह दिखाने के लिए कर सकते हैं कि आपका प्रोजेक्ट पाइडेंटिक का उपयोग करता है। आप इस बैज का उपयोग अपने README.md में कर सकते हैं:
मार्कडाउन के साथ¶
[](https://pydantic.dev)
[](https://pydantic.dev)
पुनः संरचित पाठ के साथ¶
.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v1.json
:target: https://pydantic.dev
:alt: Pydantic
.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json
:target: https://pydantic.dev
:alt: Pydantic
एचटीएमएल के साथ¶
<a href="https://pydantic.dev"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v1.json" alt="Pydantic Version 1" style="max-width:100%;"></a>
<a href="https://pydantic.dev"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json" alt="Pydantic Version 2" style="max-width:100%;"></a>
本文总阅读量次