पीईपी 257 रूसी में। (डॉकस्ट्रिंग्स समझौता)

टिप्पणी

औचित्य

“पारंपरिक परंपराएँ स्पष्टता, स्थिरता, रखरखाव में आसानी और अच्छी प्रोग्रामिंग आदतों को बढ़ावा देती हैं। लेकिन वे आपको अपनी इच्छा के विरुद्ध कार्य करने के लिए मजबूर नहीं करते हैं। यह पायथन है! ”

टिम पीटर्स ऑन comp.lang.python, 2001-06-16

विशिष्टता

एक डॉकस्ट्रिंग क्या है?

1. मॉड्यूल, वर्ग या __in__ स्तर पर एक साधारण असाइनमेंट के तुरंत बाद होने वाले स्ट्रिंग शाब्दिक "विशेषता प्रलेखन स्ट्रिंग्स" कहलाते हैं। (विशेषता docstrings)
   
2. स्ट्रिंग शाब्दिक जो दस्तावेज़ की एक और पंक्ति के तुरंत बाद होती हैं, उन्हें "अतिरिक्त प्रलेखन लाइनें" कहा जाता है। (अतिरिक्त खुराक)

def f(x):
    """  docstring   __doc__ ."""
    """
     "additional docstrings",   , 
        Docutils.
    """
    return x**2

f.a = 1
""" "attribute docstrings"   : f.a"""

एकल पंक्ति प्रलेखन लाइनें

def kos_root():
    """    root KOS"""
    global _kos_root
    if _kos_root: return _kos_root
    ...

• . .
• , . docstring .
• , .
• — «», . (« », « »), . , : « ...».
  
  

  « » «Return pathname» «Returns pathname». PEP-257 , .

• «», / ( ). :
  
  

  def function(a, b):
      """function(a, b) -> list"""
  

  
  , C ( ), . . - :
  
  

  def function(a, b):
      def function(a, b):
      """ X   ."""
  

  
  ( -, « X» !)
  
  

  , : « », «description» . , , .

  
  

def complex(real=0.0, imag=0.0):
    """  .

     :
    real --   (  0.0)
    imag --   (  0.0)
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero
    ...

Docstring प्रसंस्करण

def trim(docstring):
    if not docstring:
        return ''
    #     (  Python)
    #      :
    lines = docstring.expandtabs().splitlines()
    #    (   ):
    indent = sys.maxsize
    for line in lines[1:]:
        stripped = line.lstrip()
        if stripped:
            indent = min(indent, len(line) - len(stripped))
    #   (   ):
    trimmed = [lines[0].strip()]
    if indent < sys.maxsize:
        for line in lines[1:]:
            trimmed.append(line[indent:].rstrip())
    #       :
    while trimmed and not trimmed[-1]:
        trimmed.pop()
    while trimmed and not trimmed[0]:
        trimmed.pop(0)
    #    :
    return '\n'.join(trimmed)

def foo ():
    """
       .
    """

>>> print repr(foo.__doc__)
'\n        .\n    '
>>> foo.__doc__.splitlines()
['', '        .', '    ']
>>> trim(foo.__doc__)
'    .'

def foo():
    """ 
     .
    """

def bar():
    """
     
     .
    """