Python 简明教程
Python - Docstrings
Docstrings in Python
在 Python 中，文档字符串是一种对模块、类、函数和方法进行编制文档的方式。它们位于三引号 (""" """) 内，并且可能跨越多行。
文档字符串是 Python 代码编写文档的便捷方式。它们可通过 doc 访问它们编制文档的相应 Python 对象的属性。以下是编写文档字符串的不同方式。
Multi-Line Docstrings
多行文档字符串用于制作更详细的文档。它们提供更全面的描述，包括参数、返回值和其他相关详细信息。多行文档字符串以三引号开头和结尾，包括一行摘要，后面是空行和更详细的描述。
Example
以下示例使用多行文档字符串来解释代码。
def multiply(a, b):
"""
Multiply two numbers and return the result.
Parameters:
a (int or float): The first number.
b (int or float): The second number.
Returns:
int or float: The result of multiplying a and b.
"""
return a * b
result = multiply(5, 3)
print("Product:", result)Docstrings for Modules
为模块编写文档字符串时，应把文档字符串放在模块顶部，紧跟在任何 import 语句之后。模块文档字符串提供模块功能的概述，并列出其主要组件，例如模块提供的函数、类和异常的列表。
Example
在本例中，我们演示了在 Python 中为模块使用文档字符串。
import os
"""
This module provides Utility functions for file handling operations.
Functions:
- 'read_file(filepath)': Reads and returns the contents of the file.
- 'write_file(filepath, content)': Writes content to the specified file.
Classes:
- 'FileNotFoundError': Raised when a file is not found.
Example usage:
>>> import file_utils
>>> content = file_utils.read_file("example.txt")
>>> print(content)
'Hello, world!'
>>> file_utils.write_file("output.txt", "This is a test.")
"""
print("This is os module")Docstrings for Classes
类可以有文档字符串来描述其目的和用法。类中的每个方法也可以有自己的文档字符串。类文档字符串应提供该类的概览及其方法。
Example
在下面的示例中，我们展示了在 Python 中为类使用文档字符串。
class Calculator:
"""
A simple calculator class to perform basic arithmetic operations.
Methods:
- add(a, b): Return the sum of two numbers.
- multiply(a, b): Return the product of two numbers.
"""
def add(self, a, b):
"""Return the sum of two numbers."""
return a + b
def multiply(self, a, b):
"""
Multiply two numbers and return the result.
Parameters:
a (int or float): The first number.
b (int or float): The second number.
Returns:
int or float: The result of multiplying a and b.
"""
return a * b
cal = Calculator()
print(cal.add(87, 98))
print(cal.multiply(87, 98))Accessing Docstrings
Python 中的文档字符串可使用 doc 访问它们编制文档的对象的属性。此属性包含与对象关联的文档字符串（文档字符串），从而能够访问和显示有关函数、类、模块或方法的目的和用法的的信息。
Example
在以下示例中，我们定义了两个函数“add”和“multiply”，每个函数都有一个含参和返回值描述的 docstring。然后，我们使用 “ doc ” 属性以访问并打印这些 docstring −
# Define a function with a docstring
def add(a, b):
"""
Adds two numbers together.
Parameters:
a (int): The first number.
b (int): The second number.
Returns:
int: The sum of a and b.
"""
return a + b
result = add(5, 3)
print("Sum:", result)
# Define another function with a docstring
def multiply(x, y):
"""
Multiplies two numbers together.
Parameters:
x (int): The first number.
y (int): The second number.
Returns:
int: The product of x and y.
"""
return x * y
result = multiply(4, 7)
print("Product:", result)
# Accessing the docstrings
print(add.__doc__)
print(multiply.__doc__)Best Practices for Writing Docstrings
以下是在 Python 中编写 docstring 的最佳实践 −
-
Be Clear and Concise − 确保 docstring 清楚地解释代码的目的和用法，避免不必要的详细信息。
-
Use Proper Grammar and Spelling − 确保 docstring 语法和拼写正确。
-
Follow Conventions − 使用 docstring 格式化的标准惯例，例如 Google 样式、NumPy 样式或 Sphinx 样式。
-
Include Examples − 在适用的情况下提供示例，以说明如何使用已记录的代码。
Google Style Docstring
Google 样式 docstring 使用缩进和标题提供一种结构化的方式来记录 Python 代码。它们设计为可读和信息丰富，遵循特定格式。
Example
以下是具有 Google 样式 docstring 的函数示例 −
def divide(dividend, divisor):
"""
Divide two numbers and return the result.
Args:
dividend (float): The number to be divided.
divisor (float): The number to divide by.
Returns:
float: The result of the division.
Raises:
ValueError: If `divisor` is zero.
"""
if divisor == 0:
raise ValueError("Cannot divide by zero")
return dividend / divisor
result = divide(4, 7)
print("Division:", result)NumPy/SciPy Style Docstring
NumPy/SciPy 样式 docstring 在科学计算中很常见。它们包括参数、返回值和示例部分。
Example
以下是具有 NumPy/SciPy 样式 docstring 的函数示例 −
def fibonacci(n):
"""
Compute the nth Fibonacci number.
Parameters
----------
n : int
The index of the Fibonacci number to compute.
Returns
-------
int
The nth Fibonacci number.
Examples
--------
>>> fibonacci(0)
0
>>> fibonacci(5)
5
>>> fibonacci(10)
55
"""
if n == 0:
return 0
elif n == 1:
return 1
else:
return fibonacci(n-1) + fibonacci(n-2)
result = fibonacci(4)
print("Result:", result)Sphinx Style Docstring
Sphinx 样式 docstring 与 Sphinx 文档生成器兼容，并使用 reStructuredText 格式。
reStructuredText (reST) 是一种用于创建结构化文本文档的轻量级标记语言。Sphinx 文档生成器将 “reStructuredText” 文件作为输入，并以各种格式生成高质量的文档，包括 HTML、PDF、ePub 等。
Example
以下是具有 Sphinx 样式 docstring 的函数示例 −
def divide(dividend, divisor):
"""
Divide two numbers and return the result.
Args:
dividend (float): The number to be divided.
divisor (float): The number to divide by.
Returns:
float: The result of the division.
Raises:
ValueError: If `divisor` is zero.
"""
if divisor == 0:
raise ValueError("Cannot divide by zero")
return dividend / divisor
result = divide(76, 37)
print("Result:", result)