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

Question

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

Comments

python.org/dev/peps/pep-0008 डॉक्यूमेंटेशन स्ट्रिंग्स के लिए समर्पित एक पूरा खंड है

— यांत्रिक_

मुझे लगता है कि यह प्रश्न पर्याप्त नहीं था क्योंकि PEP-257 और PEP-8 केवल डॉकस्ट्रिंग के लिए आधार स्थापित कर रहे हैं, लेकिन कैसे epydoc, के बारे doxygenमें sphinx? क्या किसी के पास कोई आँकड़े हैं, क्या उनमें से कोई अन्य को प्रतिस्थापित करने जा रहा है, इस तरह के मामलों में बहुत अधिक विकल्प नुकसान पहुंचा सकते हैं।

— १२:१२ तक

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

— पूली

PyCharm एक दिलचस्प तरीके से ऑटोकंप्लीट करता है, जो मुझे लगता है कि इसे चलाने के लिए आवश्यक निर्देशों का एक अच्छा कार्यान्वयन है:def foo(self, other):\n\t"""\n\t(blank line)\n\t:param other: \n\t:return:\n\t"""

— Matteo Ferla

इनमें से कौन सा उत्तर वह है जो डिफ़ॉल्ट रूप से VS कोड प्रलेखन पार्सर के साथ काम करता है?

— विलियम एंट्रिएन

Answer 1

प्रारूप

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

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

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

- एपिक्टेक्स

ऐतिहासिक रूप से एक जावाडॉक जैसी शैली प्रचलित थी, इसलिए इसे दस्तावेज़ीकरण उत्पन्न करने के लिए एपिडोक (बुलाया 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
"""

- आराम

आजकल, शायद अधिक प्रचलित प्रारूप reStructuredText (reST) प्रारूप है जो Sphinx द्वारा प्रलेखन उत्पन्न करने के लिए उपयोग किया जाता है । नोट: यह 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.
"""

और भी उदाहरण

- नंपिडोक

ध्यान दें कि Numpy 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
"""

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

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

नोट: उदाहरण Pyment प्रलेखन से लिए गए हैं

Comments

मैं यह जोड़ सकता हूं कि जेटब्रेन्स पाइक्हार्म में डिफ़ॉल्ट रूप से क्या उपयोग किया जाता है, अपनी पद्धति को परिभाषित करने और दर्ज करने के बाद ट्रिपल उद्धरण टाइप करें। jetbrains.com/pycharm/help/creating-documentation-comments.html

— फेलिप अल्मीडा

सबसे व्यापक उत्तर में, इतिहास और वर्तमान सर्वोत्तम प्रथाओं की भावना शामिल है। अब हम सभी को एक नए "सर्वश्रेष्ठ" प्रारूप की ओर सामुदायिक गति की कुछ समझ है और सभी नए अन्य सभी से माइग्रेशन टूल बनाने की दिशा में कुछ अतिरिक्त सामुदायिक प्रयास हैं, इसलिए हम वास्तव में सर्वोत्तम अभ्यास विकसित कर सकते हैं।

— BobHy

यो @daouzli, शैली लिंक गूगल 404. है मैं belive यह एक सही है। आप sphinx google style उदाहरण भी जोड़ सकते हैं । महान जवाब btw। संपादित करें: मैंने आपका जवाब खुद से संपादित किया।

— वॉय

अच्छा उत्तर। मैं कहता हूँ कि आप PyCharm (JetBrains) में डिफ़ॉल्ट डॉकस्ट्रिंग प्रारूप को कहाँ बदल सकते हैं: सेटिंग्स -> टूल्स -> पायथन इंटीग्रेटेड टूल्स -> डॉकस्ट्रिंग प्रारूप। सौभाग्य!

— जैकसन

मुझे आश्चर्य है कि पहली पाठ पंक्ति के बारे में किसी ने टिप्पणी नहीं की है: वर्तमान में यह कड़ाई से सही कह रहा है, लेकिन मुझे लगता है कि पसंद किया गया तरीका इसे ट्रिपल उद्धरण के बाद पहली पंक्ति में रखना है। PEP 8 और PEP 257 अपने लगभग सभी उदाहरणों में करता है। PEP 287 यह आपका तरीका है, लेकिन मेरे अनुभव में यह आम नहीं है।

— लैपिनोट

Answer 2

गूगल स्टाइल गाइड एक उत्कृष्ट अजगर शैली गाइड शामिल हैं। इसमें पठनीय डॉकस्ट्रिंग सिंटैक्स के लिए कन्वेंशन शामिल हैं जो पीईपी -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

Comments

मुझे लगता है "डॉकस्ट्रिंग्स में हस्ताक्षर" -स्टाइल भयानक रूप से बेमानी और वाचाल है। पायथन 3+ के लिए, फंक्शन एनोटेशन ऐसा करने के लिए बहुत अधिक स्वच्छ तरीका है। इससे भी बदतर अगर यह छद्म मजबूत-प्रकारों का उपयोग करता है: अजगर टाइपिंग बतख के साथ बेहतर है।

— एवपोक

हाँ, लेकिन कम से कम यह संकेत देता है कि किस प्रकार के बतख की उम्मीद है, और अधिकांश

— देवता

@ व्यक्तिगत रूप से, मुझे फ़ंक्शन एनोटेशन पसंद नहीं है। उन में कक्षाओं का उपयोग करने के लिए आपको अनावश्यक आयात करना पड़ सकता है, उनमें तार का उपयोग करने के लिए आप क्षैतिज स्थान से बहुत तेज़ी से उनका वर्णन कर सकते हैं। अब तक मैंने उन्हें किसी भी चीज़ के लिए इस्तेमाल करने की बात नहीं दिखाई है।

— OdraEncoded

@Nathan, Google की शैली मार्गदर्शिका उन टिप्पणियों की घोषणा करती है जो घोषणात्मक होने के बजाय वर्णनात्मक होती हैं, जैसे "Bigtable से एक पंक्ति में" एक बड़ी फ़ाइल से "पंक्तियाँ"। इस प्रकार, "गणना करें ..." को "गणना करता है ..." को बदलना आपके उदाहरण को बाकी टिप्पणी, "रिटर्न" और "राइज़" के साथ अधिक सुसंगत बना देगा।

— gwg

नाइट: Google शैली के बाद, अनिवार्य रूप के बजाय वर्णनात्मक का उपयोग करें, "गणना करता है ..." और "जोड़ता है ..."

— sbeliakov

Answer 3

पीईपी -8 की तुलना में बहुत अधिक विस्तार के साथ डॉकस्ट्रिंग कन्वेंशन पीईपी -257 में हैं ।

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

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

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

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. 
    ...

Comments

ध्यान दें कि PEP-8 विशेष रूप से कहता है कि डॉकस्ट्रिंग्स को आदेशों / निर्देशों के रूप में लिखा जाना चाहिए, बजाय विवरणों के, जैसे। """Return the squared result"""के बजाय """Returns the squared result"""। हालांकि व्यक्तिगत रूप से, मैं यह लिखता हूं कि पीईपी के कहने के बावजूद टिम यहां कैसे हैं।

— कैम जैक्सन

मैं भी उस सलाह से सहमत नहीं हूँ (अत्यावश्यक काल का उपयोग करते हुए) क्योंकि यह एक वाक्य से अधिक समय के लिए अजीब लग रहा है। इसके अलावा, आप एक फ़ंक्शन का वर्णन कर रहे हैं , पाठक को यह नहीं बता रहा है कि क्या करना है।

— mk12

नोट: वर्णनात्मक docstrings के बजाय प्रिस्क्रिप्टिव के लिए विनिर्देश वास्तव में PEP-257 में प्रकट होता है , PEP-8 में नहीं। मैं जावा की एक परंपरा से आया हूं, जहां मैं कार्यों का वर्णन कर रहा था, लेकिन आखिरकार जब मेरा प्रोग्रामिंग प्रतिमान ऑब्जेक्ट-ओरिएंटेड से प्रक्रियात्मक पर स्विच हो गया तो मैंने अत्यावश्यक काल का उपयोग करना शुरू कर दिया। और जब मैंने साक्षर-प्रोग्रामिंग-शैली के प्रलेखन को उत्पन्न करने के लिए पाइको का उपयोग करना शुरू किया , तो यह बहुत स्पष्ट हो गया कि क्यों अनिवार्य तनाव का सुझाव दिया गया था। आपको अपने प्रतिमान के आधार पर चयन करना चाहिए।

— karan.dodia 20

अनिवार्य एक व्याकरणिक मनोदशा है । (क्षमा करें।)

— डेनिस ड्रेचर

@ Mk12 Git कमिट मैसेज को डिस्क्रिप्शन के बजाय कमांड के रूप में भी लिखा जाना चाहिए। और वे एक कोड परिवर्तन को " वर्णन " भी कर रहे हैं, "पाठक को नहीं बता रहा है कि क्या करना है"। इसलिए मुझे लगता है कि आदेशों के रूप में विवरण लिखना केवल सम्मेलन है।

— onephew

Answer 4

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

• एक उदाहरण के साथ एक साथ खस्ता से प्रारूप का विनिर्देश
• आपके पास इसे प्रस्तुत करने के लिए एक स्फिंक्स एक्सटेंशन है: 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

Comments

NumPy प्रारूप IMHO बहुत अधिक ऊर्ध्वाधर स्थान लेता है जो वाइडस्क्रीन मॉनिटर पर दुर्लभ होता है (सिवाय आपके द्वारा उपयोग किए गए 90 डिग्री से, लेकिन मुझे लगता है कि अधिकांश लोग ऐसा नहीं करते हैं) इसलिए, IMHO Google प्रारूप पठनीयता और सुविधाओं के संबंध में एक अच्छा विकल्प है।

— सेमानिनो

मुझे लगता है कि यह कुछ व्यक्तिपरक है। एक बार जब आपके पास अधिक जटिल डॉकस्ट्रिंग होता है (विभिन्न वर्गों के साथ, उदाहरण के लिए, आदि, इसलिए प्रारूप की परवाह किए बिना किसी भी तरह का बहुत अधिक ऊर्ध्वाधर स्थान लेना), मुझे पढ़ने के लिए आसान / बेहतर संरचित करने के लिए सुपीडॉक प्रारूप आसान लगता है।

— जॉरिस

व्यक्तिगत रूप से मुझे ऐसा लगता है कि डॉकस्ट्रिंग डॉक्यूमेंटेशन में बेहतर है, न कि सोर्स कोड, अगर यह इतना लंबा है तो वे मॉड्यूल की असंभवता को समाप्त कर देते हैं।

— जोनाथन हार्टले

Answer 5

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

Comments

PEP-257 का उल्लेख "कैसे मैं ठीक से दस्तावेज़ पैरामीटर, रिटर्न मान, अपवाद उठाए गए आदि के संदर्भ में होना चाहिए" एक JOKE है - यह उनके बारे में एक भी शब्द नहीं कहता है (हालांकि एक कोड उदाहरण कुछ दिखाता है)। IMHO Google प्रारूप पठनीयता और सुविधाओं के संबंध में एक अच्छा विकल्प है।

— सेनामिनो

Answer 6

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

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

Comments

मैं नियमित रूप ipythonसे एक पुस्तकालय का परीक्षण-ड्राइव करने के लिए उपयोग करता हूं , और यह पढ़ने के डॉकस्ट्रिंग्स को सरल बना देता है - मुझे केवल टाइप करना है your_module.some_method_im_curious_about?और मुझे डॉकस्ट्रिंग सहित हर अच्छा प्रिंटआउट मिलता है।

— थानाटोस

एक पुस्तकालय के उपयोगकर्ता या एक एपीआई या जो एक प्लगइन लिख रहे हैं, सभी को कोड को देखने और इसके बारे में समझ बनाने की आवश्यकता है। मुझे जावा या C # की तुलना में पायथन में टिप्पणियाँ अधिक महत्वपूर्ण लगती हैं क्योंकि प्रकार घोषित नहीं किए गए हैं। यह बहुत मदद करता है अगर टिप्पणियों से मोटे तौर पर पता चलता है कि किस प्रकार के बतख पारित किए जा रहे हैं और वापस आ गए हैं। (अन्यथा, आपको वास्तव में सभी कोड चलना होगा और एक टैली अप करना होगा कि किसी दिए गए पैरामीटर को ... यहाँ पर चलने योग्य होना चाहिए ... वहाँ पर अनुक्रमण का समर्थन करें ... अंत में संख्यात्मक घटाव का समर्थन करें ... अहा! यह मूल रूप से है int array। एक कमेंट से मदद मिली होगी!)

— Jon Coombs

एह, नहीं। Docstrings अदृश्य नहीं हैं और यह बिंदु का एक सा है। यदि आप दौड़ते हैं तो आपको डॉकस्ट्रिंग देखने को मिलती हैhelp फ़ंक्शन को दस्तावेज़ित फ़ंक्शन / विधि / वर्ग (और आप केवल संकलित मॉड्यूल तक पहुंच है, तो भी कर सकते । व्यक्तिगत रूप से मुझे लगता है कि एक व्यक्ति को इस बात को ध्यान में रखना चाहिए जब डॉकस्ट्रिंग कन्वेंशन (यानी कि इसे पढ़ने का इरादा है)।

— skyking

Answer 7

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

pep257 मानक से आपके द्वारा किए गए विचलन की रिपोर्ट करेगा और इसे pylint और pep8 की तरह कहा जाता है।

Comments

PEP-257 का उल्लेख "कैसे मैं ठीक से दस्तावेज़ पैरामीटर, रिटर्न मान, अपवाद उठाए गए आदि के संदर्भ में होना चाहिए" के संदर्भ में एक JOKE है - यह उनके बारे में एक भी शब्द नहीं कहता है (हालांकि एक कोड उदाहरण कुछ दिखाता है)। NumPy प्रारूप IMHO बहुत अधिक ऊर्ध्वाधर स्थान लेता है जो वाइडस्क्रीन मॉनिटर पर दुर्लभ होता है (सिवाय आपके द्वारा उपयोग किए गए 90 डिग्री से, लेकिन मुझे लगता है कि अधिकांश लोग ऐसा नहीं करते हैं) इसलिए, IMHO Google प्रारूप पठनीयता और सुविधाओं के संबंध में एक अच्छा विकल्प है।

— सेमानिनो

@ सेमिनो मैं pep257 कार्यक्रम के संदर्भ में Numpy Docstring Standard का उल्लेख कर रहा हूं, - PEP-257 नहीं। उस कार्यक्रम को अब pydocstyle कहा जाता है। pydocstyle आपको कुछ numpydoc जांच करने की अनुमति देता है, उदाहरण के लिए, pydocstyle --select=D4 tmp.pyअनुभाग नामकरण सहित docstring सामग्री मुद्दों की एक श्रृंखला के लिए जाँच करता है।

— फिन Finरूप नील्सन