Python - 文档字符串

上一页
下一页

Python 中的文档字符串

在 Python 中，文档字符串是用于记录模块、类、函数和方法的一种方式。它们写在三个引号(""" """)内，可以跨多行。

文档字符串是将文档与 Python 代码关联的便捷方式。可以通过各自 Python 对象的__doc__属性访问它们。以下是编写文档字符串的不同方法：

单行文档字符串

单行文档字符串用于简短简单的文档。它们提供了对函数或方法作用的简洁描述。单行文档字符串应适合在一行三引号内，并以句点结尾。

示例

在下面的示例中，我们使用单行文档字符串来编写文本：

def add(a, b):
   """Return the sum of two numbers."""
   return a + b

result = add(5, 3)
print("Sum:", result)

多行文档字符串

多行文档字符串用于更详细的文档。它们提供更全面的描述，包括参数、返回值和其他相关细节。多行文档字符串以三个引号开头和结尾，包含摘要行，后跟空行和更详细的描述。

示例

以下示例使用多行文档字符串来解释代码：

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)

模块的文档字符串

为模块编写文档字符串时，请将文档字符串放在模块顶部，紧跟在任何 import 语句之后。模块文档字符串提供了模块功能的概述，并列出了其主要组件，例如模块提供的函数、类和异常列表。

示例

在此示例中，我们演示了在 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")

类的文档字符串

类可以包含文档字符串来描述其目的和用法。类中的每个方法也可以有自己的文档字符串。类文档字符串应提供对类及其方法的概述。

示例

在下面的示例中，我们展示了在 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))

访问文档字符串

Python 中的文档字符串是使用它们所记录对象的__doc__属性访问的。此属性包含与对象关联的文档字符串，提供了一种访问和显示有关函数、类、模块或方法的目的和用法的的信息的方法。

示例

在下面的示例中，我们定义了两个函数“add”和“multiply”，每个函数都有一个描述其参数和返回值的文档字符串。然后，我们使用“__doc__”属性来访问和打印这些文档字符串：

# 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__)

编写文档字符串的最佳实践

以下是 Python 中编写文档字符串的最佳实践：

  • 清晰简洁 - 确保文档字符串清楚地解释了代码的目的和用法，避免不必要的细节。

  • 使用正确的语法和拼写 - 确保文档字符串书写良好，语法和拼写正确。

  • 遵循约定 - 使用标准的文档字符串格式约定，例如 Google 风格、NumPy 风格或 Sphinx 风格。

  • 包含示例 - 在适用情况下提供示例来说明如何使用已记录的代码。

Google 风格文档字符串

Google 风格文档字符串提供了一种使用缩进和标题来记录 Python 代码的结构化方法。它们旨在易于阅读和信息丰富，并遵循特定的格式。

示例

以下是具有 Google 风格文档字符串的函数示例：

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 风格文档字符串

NumPy/SciPy 风格的文档字符串在科学计算中很常见。它们包含参数、返回值和示例等部分。

示例

下面是一个带有 NumPy/SciPy 风格文档字符串的函数示例：

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 风格文档字符串

Sphinx 风格的文档字符串与 Sphinx 文档生成器兼容，并使用reStructuredText 格式。

reStructuredText (reST) 是一种轻量级的标记语言，用于创建结构化文本文档。Sphinx 文档生成器以 “reStructuredText” 文件作为输入，并生成各种格式的高质量文档，包括 HTML、PDF、ePub 等。

示例

下面是一个带有 Sphinx 风格文档字符串的函数示例：

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)

文档字符串与注释

以下是 Python 文档字符串和注释之间差异的重点，分别关注它们的用途、格式、用法和可访问性：

文档字符串 注释
用于记录 Python 对象，例如函数、类、方法、模块或包。 用于为人类读者注释代码，提供上下文或暂时禁用代码。
用三个引号 (""" """ 或 ''' ''') 编写，并放置在对象定义的紧后。 以 # 符号开头，并放置在与注释代码相同的行上。
存储为对象的属性，并且可以通过编程方式访问。 Python 解释器在执行期间会忽略它，纯粹是为了人类理解。
使用对象的 __doc__ 属性访问。 无法通过编程方式访问；仅存在于源代码中。
打印页面
上一页
下一页
广告