Python docstring文档字符串

在Python中，文档字符串是一种字符串字面值，用于作为不同Python对象的文档，如函数、模块、类及其方法和包。它是所有这些结构定义中的第一行，并成为doc属性的值。

函数的文档字符串

def addition(x, y):
   '''This function returns the sum of two numeric arguments'''
   return x+y
print ("Docstring of addition function:", addition.__doc__)

它将产生以下 输出 –

Docstring of addition function: This function returns the sum of two numeric arguments

docstring可以使用单引号、双引号或三引号来编写。然而，大多数情况下，您可能希望将描述性文本作为文档，因此最好使用三引号。

所有内置的模块和函数都有doc属性，返回它们的docstring。

math模块的docstring

import math

print ("Docstring of math module:", math.__doc__)

它将产生以下 输出 –

Docstring of math module: This module provides access to the mathematical functions
 defined by the C standard.

内置函数的文档字符串

以下代码显示了random模块中abs()函数和randint()函数的文档字符串。

print ("Docstring of built-in abs() function:", abs.__doc__)
import random

print ("Docstring of random.randint() function:",
random.randint.__doc__)

它将产生以下输出 −

Docstring of built-in abs() function: Return the absolute value of the
argument.

Docstring of random.randint() function: Return random integer in range
[a, b], including both end points.

内置类的文档字符串

内置类的文档字符串通常更具解释性，因此文本跨多行。下面，我们检查内置的字典类的文档字符串

print ("Docstring of built-in dict class:", dict.__doc__)

它将会产生以下 输出 –

Docstring of built-in dict class: dict() -> new empty dictionary
dict(mapping) -> new dictionary initialized from a mapping object's
   (key, value) pairs
dict(iterable) -> new dictionary initialized as if via:
   d = {}
   for k, v in iterable:
      d[k] = v
dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

Template类的文档字符串

Template类定义在Python标准库的string模块中。它的文档字符串如下：

from string import Template

print ("Docstring of Template class:", Template.__doc__)

它将产生以下 输出 −

Docstring of Template class: A string class for supporting $- substitutions.

帮助系统中的文档字符串

文档字符串还被Python的内置帮助服务所使用。例如，在Python解释器中检查abs()函数的帮助信息-

>>> help (abs)
Help on built-in function abs in module builtins:
abs(x, /)
   Return the absolute value of the argument.

同样，在解释器终端中定义一个函数并运行帮助命令。

>>> def addition(x,y):
... '''addtion(x,y)
... Returns the sum of x and y
... '''
... return x+y
...
>>> help (addition)
Help on function addition in module __main__:
addition(x, y)
   addtion(x,y)
   Returns the sum of x and y

文档字符串还被集成开发环境（IDE）用于在编辑代码时提供有用的自动完成信息。

文档字符串作为注释

除了函数、方法、类、模块或包等对象之外，出现在任何其他地方的字符串文字都会被解释器忽略，因此它们类似于注释（以#符号开头）。

# This is a comment
print ("Hello World")
'''This is also a comment'''
print ("How are you?")