दिलचस्प पोस्ट
मैं T-SQL संग्रहीत कार्यविधि में वैकल्पिक पैरामीटर कैसे उपयोग कर सकता हूं? PHP में पीछे वाले शून्य को कैसे पट्टी करना बैच फ़ाइल में उपयोगकर्ता द्वारा प्रदत्त इनपुट के लिए पीछे और अग्रणी व्हाइसेस्पेस को कैसे निकालना है? मेरी बहुत सरल Greasemonkey स्क्रिप्ट नहीं चल रही है? मुझे अपनी बेस क्लास पद्धति तक पहुंचने के लिए "प्रयोग" करने वाले कीवर्ड का उपयोग क्यों करना चाहिए? JQuery में क्लास चयनकर्ता नहीं कैसे एक छवि में डीपीआई जानकारी सेट करने के लिए? $ क्या है? (डॉलर प्रश्न चिह्न) शैल स्क्रिप्टिंग में चर? अजीब प्रयास -अनुरोध-शेष-अंतराल वापसी के साथ व्यवहार जावा कन्स्ट्रक्टर्स एसक्यूएल सर्वर 2005 पिवॉट कॉलम की अज्ञात संख्या पर टेबल नामकरण दुविधा: एकवचन बनाम बहुवचन नाम प्रिंट स्टेटमेंट के बाद मैं नई लाइन को कैसे दबा सकता हूं? क्रोम पैकेज्ड ऐप आईडी को कैसे बदला जाए या हमें मेनिफ़ेस्ट। जेएसन में मुख्य फ़ील्ड की आवश्यकता क्यों है? JQuery के साथ ईवेंट हैंडलर्स के लिए बाध्य कार्यों को एक्सेस करना

मानक पायथन डॉकस्ट्रिंग प्रारूप क्या है?

मैंने पायथन में डॉकस्ट्रिंग लिखने के कुछ अलग-अलग शैलियों को देखा है, क्या कोई आधिकारिक या "सहमति-पर" शैली है?

वेब के समाधान से एकत्रित समाधान "मानक पायथन डॉकस्ट्रिंग प्रारूप क्या है?"

प्रारूप

अन्य पदों के अनुसार पाइथन डॉकस्ट्रिंग को कई प्रारूपों के बाद लिखा जा सकता है हालांकि डिफ़ॉल्ट स्फिंक्स डॉकस्ट्रिंग प्रारूप का उल्लेख नहीं किया गया था और वह पुनर्रचित पाठ्य (रीस्ट) पर आधारित है आप उस टाटू में मुख्य स्वरूपों के बारे में कुछ जानकारी प्राप्त कर सकते हैं।

ध्यान दें कि पीईपी 287 द्वारा आरईटी की सिफारिश की गई है

डॉकस्ट्रिंग के लिए मुख्य प्रयुक्त प्रारूपों का अनुसरण करता है।

– एपीआईटेक्स्ट

ऐतिहासिक रूप से एक जवादाक की तरह शैली प्रचलित थी, इसलिए यह दस्तावेज जेनरेट करने के लिए Epydoc (नामक Epytext प्रारूप के साथ) के आधार के रूप में लिया गया था।

उदाहरण:

 """ This is a javadoc style. @param param1: this is a first param @param param2: this is a second param @return: this is a description of what is returned @raise keyError: raises an exception """ 

– आराम

आजकल, संभवत: अधिक प्रचलित प्रारूप, पुनर्जन्मित पाठ (रीस्ट) प्रारूप है, जिसका उपयोग प्रलेखन के लिए स्फिंक्स द्वारा किया जाता है। नोट: यह JetBrains PyCharm में डिफ़ॉल्ट रूप से उपयोग किया जाता है (एक विधि परिभाषित करने के बाद ट्रिपल कोट्स टाइप करें और हिट करें)। यह भी Pyment में आउटपुट स्वरूप के रूप में डिफ़ॉल्ट रूप से उपयोग किया जाता है।

उदाहरण:

 """ This is a reST style. :param param1: this is a first param :param param2: this is a second param :returns: this is a description of what is returned :raises keyError: raises an exception """ 

– गूगल

Google का अपना प्रारूप है जिसे अक्सर उपयोग किया जाता है यह स्पिंक्स द्वारा भी व्याख्या की जा सकती है

उदाहरण:

 """ This is an example of Google style. Args: param1: This is the first param. param2: This is a second param. Returns: This is a description of what is returned. Raises: KeyError: Raises an exception. """ 

और भी उदाहरण

– Numpydoc

नोट करें कि नप्पी अपने स्वयं के numpydoc Google स्वरूप के आधार पर अनुशंसा करते हैं और स्पिंक्स द्वारा उपयोग करने योग्य हैं

 """ My numpydoc description of a kind of very exhautive numpydoc format docstring. Parameters ---------- first : array_like the 1st param name `first` second : the 2nd param third : {'value', 'other'}, optional the 3rd param, by default 'value' Returns ------- string a value in a string Raises ------ KeyError when a key error OtherError when an other error """ 

परिवर्तित / उत्पन्न

पैमाना जैसे उपकरण को स्वचालित रूप से एक अजगर प्रोजेक्ट में उत्पन्न करने के लिए टूल का उपयोग करना संभव है, जो अभी तक प्रलेखित नहीं है, या किसी प्रारूप से मौजूदा डॉकस्ट्रिंग को परिवर्तित कर सकता है (कई स्वरूपों को मिलाया जा सकता है)

नोट: उदाहरणों को पाइलमेंट दस्तावेज़ीकरण से लिया जाता है

Google शैली गाइड में एक उत्कृष्ट पायथन शैली गाइड है इसमें पढ़ने योग्य डॉकस्ट्रिंग सिंटैक्स के लिए सम्मेलनों शामिल हैं जो पीईपी -257 से बेहतर मार्गदर्शन प्रदान करता है। उदाहरण के लिए:

 def square_root(n): """Calculate the square root of a number. Args: n: the number to get the square root of. Returns: the square root of n. Raises: TypeError: if n is not a number. ValueError: if n is negative. """ pass 

मैं इस का विस्तार करना चाहता हूं ताकि इस स्पिंक्स प्रलेखन ट्यूटोरियल में वर्णित तर्कों में टाइप जानकारी शामिल हो। उदाहरण के लिए:

 def add_value(self, value): """Add a new value. Args: value (str): the value to add. """ pass 

डॉकस्ट्रिंग सम्मेलन PEP-257 में हैं, जिसमें पीईपी -8 के मुकाबले ज्यादा विस्तार है।

हालांकि, डॉकस्ट्रिंग कोड के अन्य क्षेत्रों की तुलना में कहीं अधिक व्यक्तिगत लगती है। विभिन्न परियोजनाओं के अपने स्वयं के मानक होंगे

मैं हमेशा डॉकस्ट्रिंग को शामिल करता हूं, क्योंकि वे यह दिखाना चाहते हैं कि फ़ंक्शन का उपयोग कैसे किया जाए और यह बहुत जल्दी कैसे करता है।

स्ट्रिंग की लंबाई की परवाह किए बिना, मैं चीजों को संगत रखना पसंद करता हूं। मुझे लगता है कि कोड कैसे दिखता है जब इंडेंटेशन और अंतर समान हो। इसका अर्थ है, मैं इसका उपयोग करता हूं:

 def sq(n): """ Return the square of n. """ return n * n 

ऊपर:

 def sq(n): """Returns the square of n.""" return n * n 

और लंबे समय तक डॉकस्ट्रिंग में पहली पंक्ति पर टिप्पणी करना छोड़ देना है:

 def sq(n): """ Return the square of n, accepting all numeric types: >>> sq(10) 100 >>> sq(10.434) 108.86835599999999 Raises a TypeError when input is invalid: >>> sq(4*'435') Traceback (most recent call last): ... TypeError: can't multiply sequence by non-int of type 'str' """ return n*n 

जिसका अर्थ है कि मुझे डॉकस्ट्रिंग मिलती है जो इस तरह से शुरू होती है कि यह गंदा हो।

 def sq(n): """Return the squared result. ... 

जैसा कि किसी ने भी उल्लेखनीय रूप से इसका उल्लेख नहीं किया है: आप नम्पी डॉकस्ट्रिंग स्टैंडर्ड का भी उपयोग कर सकते हैं। यह व्यापक रूप से वैज्ञानिक समुदाय में प्रयोग किया जाता है

  • एक उदाहरण के साथ एक साथ numpy से प्रारूप का विवरण
  • आपके पास यह रेंडर करने के लिए एक स्फिंक्स एक्सटेंशन है: numpydoc
  • और यह एक उदाहरण है कि कितना सुंदर एक गाया हुआ डॉकस्ट्रिंग ऐसा दिख सकता है: http://docs.scipy.org/doc/numpy/reference/generated/numpy.mean.html

नेपोलियन स्फिंक्स विस्तार Google- शैली के डॉकस्ट्रिंग को विश्लेषित करने के लिए (@ नाथन के उत्तर में अनुशंसित) नंपी-शैली वाले डॉसस्ट्रिंग का भी समर्थन करता है, और दोनों की तुलनात्मक तुलना करता है

और यह विचार देने के लिए एक बुनियादी उदाहरण दिया गया है कि यह कैसा दिखता है:

 def func(arg1, arg2): """Summary line. Extended description of function. Parameters ---------- arg1 : int Description of arg1 arg2 : str Description of arg2 Returns ------- bool Description of return value See Also -------- otherfunc : some related other function Examples -------- These are written in doctest format, and should illustrate how to use the function. >>> a=[1,2,3] >>> print [x + 3 for x in a] [4, 5, 6] """ return True 

पीईपी -8 आधिकारिक अजगर कोडन मानक है। इसमें डॉकस्ट्रिंग पर एक खंड होता है, जो पीईपी -257 को संदर्भित करता है – डॉकस्ट्रिंग के लिए एक पूर्ण विवरण

पायथन की आधिकारिक शैली PEP-8 में सूचीबद्ध हैं।

पैरामीटर, रिटर्न इत्यादि का वर्णन करने के लिए पीपी -257 और नॉर्मली डॉकस्ट्रिंग स्टेंडर्ड के खिलाफ अपने डॉकस्ट्रिंग को देखने के लिए व्लादिमीर केलेशेव के पीईटी 257 पायथन प्रोग्राम का उपयोग करना मेरा सुझाव है।

pep257 आप मानक से बना अंतर की रिपोर्ट करेंगे और pylint और pep8 की तरह कहा जाता है।

यह पायथन है; कुछ भी जाता है अपने दस्तावेज़ों को प्रकाशित करने का तरीका देखें। डॉकस्ट्रिंग आपके स्रोत कोड के पाठकों को छोड़कर अदृश्य हो सकती है।

लोग वास्तव में वेब पर दस्तावेज को ब्राउज़ और खोज करना चाहते हैं। इसे प्राप्त करने के लिए, दस्तावेज़ टूल स्पिंक्स का उपयोग करें यह पायथन परियोजनाओं के दस्तावेजीकरण के लिए डी-फ़ैक्टो मानक है उत्पाद सुंदर है- https://python-guide.readthedocs.org/en/latest/ पर एक नज़र डालें। वेबसाइट पढ़ें डॉक्स आपके डॉक्स को मुफ्त में होस्ट करेगा।