Python中docstring(文檔字符串)用法示例詳解
更新時間：2025年10月19日 12:11:12 作者：Redmi人兒
這篇文章主要介紹了Python中docstring(文檔字符串)用法的相關資料,文檔字符串（docstring）是 Python 提供的一種標準化方式,用于為模塊、類、函數或方法添加說明性文字,是代碼自解釋性的重要體現,需要的朋友可以參考下
在Python中，docstring（文檔字符串）是用來為模塊、類、方法、函數等提供文檔的一種方式。它是一個字符串字面量，出現在模塊、類、函數或方法的定義的第一條語句。通過使用docstring，我們可以為代碼添加描述性的文檔，這些文檔可以通過內置的help()函數或者各種文檔生成工具（如Sphinx）來查看。
下面是一個簡單的例子，展示如何在函數中使用docstring：
def add(a, b):
"""
計算兩個數的和
參數:
a (int): 第一個加數
b (int): 第二個加數
返回:
int: 兩個加數的和
"""
return a + b
然后，我們可以通過以下方式查看這個函數的文檔：
使用help()函數：在Python交互環(huán)境中，輸入help(add)，就會顯示這個函數的文檔字符串。
使用__doc__屬性：直接打印add.doc，也會輸出同樣的文檔字符串。
例如：
print(help(add)) # 或者 print(add.__doc__)
docstring的格式可以有很多種，常見的包括純文本、reStructuredText（reST）和Google風格等。上面例子中使用的是比較常見的格式，類似于Google風格。
使用docstring的好處是：
代碼和文檔在一起，容易維護。
可以通過工具自動生成文檔。
方便其他開發(fā)者理解你的代碼。
在編寫大型項目時，良好的docstring是非常重要的。
在Python中，docstring（文檔字符串）是一種特殊的字符串，用于為模塊、函數、類和方法提供文檔說明。它位于定義的第一行，用三個雙引號 """ 或三個單引號 ''' 包裹。
基本用法
1. 函數文檔字符串
def add(a, b):
"""
計算兩個數的和
參數:
a (int): 第一個數字
b (int): 第二個數字
返回:
int: 兩個數字的和
示例:
>>> add(2, 3)
5
>>> add(-1, 1)
0
"""
return a + b
2. 類文檔字符串
class Calculator:
"""
一個簡單的計算器類
屬性:
brand (str): 計算器品牌
方法:
add: 加法運算
subtract: 減法運算
"""
def __init__(self, brand):
self.brand = brand
def multiply(self, a, b):
"""返回兩個數的乘積"""
return a * b
查看文檔字符串
1. 使用help()函數
help(add) # 或者 help(Calculator)
2. 使用__doc__屬性
print(add.__doc__) print(Calculator.__doc__)
3. 在交互式環(huán)境中
# 在IPython或Jupyter中 add? # 或者 add??
常見的文檔字符串格式
1. Google風格
def calculate_area(radius):
"""
計算圓的面積
Args:
radius (float): 圓的半徑
Returns:
float: 圓的面積
Raises:
ValueError: 當半徑為負數時
Example:
>>> calculate_area(5)
78.53981633974483
"""
if radius < 0:
raise ValueError("半徑不能為負數")
return 3.141592653589793 * radius ** 2
2. NumPy風格
def calculate_area(radius):
"""
計算圓的面積
Parameters
----------
radius : float
圓的半徑
Returns
-------
float
圓的面積
Examples
--------
>>> calculate_area(5)
78.53981633974483
"""
return 3.141592653589793 * radius ** 2
模塊級別的文檔字符串
"""
math_utils.py
這個模塊提供了一些數學工具函數。
包含的功能:
- 基本算術運算
- 幾何計算
- 統(tǒng)計函數
作者: Your Name
版本: 1.0
"""
def average(numbers):
"""計算數字列表的平均值"""
return sum(numbers) / len(numbers)
實際示例
class BankAccount:
"""
銀行賬戶類
屬性:
account_holder (str): 賬戶持有人姓名
balance (float): 賬戶余額
account_number (str): 賬戶號碼
方法:
deposit: 存款
withdraw: 取款
get_balance: 查詢余額
"""
def __init__(self, account_holder, initial_balance=0):
"""
初始化銀行賬戶
Args:
account_holder (str): 賬戶持有人姓名
initial_balance (float, optional): 初始余額，默認為0
"""
self.account_holder = account_holder
self.balance = initial_balance
self.account_number = self._generate_account_number()
def deposit(self, amount):
"""
存款操作
Args:
amount (float): 存款金額
Returns:
float: 更新后的余額
Raises:
ValueError: 當存款金額為負數時
"""
if amount <= 0:
raise ValueError("存款金額必須為正數")
self.balance += amount
return self.balance
def withdraw(self, amount):
"""
取款操作
Args:
amount (float): 取款金額
Returns:
float: 更新后的余額
Raises:
ValueError: 當取款金額為負數或超過余額時
"""
if amount <= 0:
raise ValueError("取款金額必須為正數")
if amount > self.balance:
raise ValueError("余額不足")
self.balance -= amount
return self.balance
# 使用幫助文檔
help(BankAccount)
help(BankAccount.deposit)
總結
通過docstring添加幫助文檔的主要好處：
- 自我文檔化：代碼和文檔在一起，便于維護
- 交互式幫助：在Python解釋器中可以直接查看
- 自動化文檔：可以被Sphinx等工具自動提取生成API文檔
- 代碼可讀性：讓其他開發(fā)者更容易理解你的代碼
- IDE支持：大多數IDE可以顯示docstring作為提示
這是Python生態(tài)系統(tǒng)中的一個重要約定，強烈建議為所有公共接口添加適當的docstring。
到此這篇關于Python中docstring(文檔字符串)用法示例詳解的文章就介紹到這了,更多相關Python docstring用法內容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！
相關文章
在工作中我們需要經常對數據庫進行操作,比如 Oracle、MySQL、SQL Sever等,這篇文章主要給大家介紹了關于Python操作MySQL數據庫的基本方法包括了數據查詢與數據更新(新增、刪除、修改),需要的朋友可以參考下2023-09-09
我們經常會遇這樣一個需求,判斷字符串中是否包含某個關鍵詞,也就是特定的子字符串,本文主要給大家分享了 7 種可以達到此效果的方法,大家可以根據需要進行選擇2025-12-12
在Python中畫圖(基于Jupyter notebook的魔法函數)
這篇文章主要介紹了在Python中畫圖(基于Jupyter notebook的魔法函數),文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值,需要的朋友可以參考下2019-10-10
這篇文章主要介紹了Python Matplotlib繪圖基礎知識代碼解析,文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值,需要的朋友可以參考下2020-08-08
有時候請求一個網頁的時候,無論是GET請求還是POST請求都訪問不了,并出現403錯誤,這是因為這些網頁為了防止惡意采集信息,使用了反爬機制,本文給大家介紹了python如何使用請求頭部headers處理403錯誤,需要的朋友可以參考下2024-03-03
本文主要介紹了ubuntu遷移anaconda到另外的目錄，文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值，需要的朋友們下面隨著小編來一起學習學習吧2023-07-07
在本篇文章里小編給大家整理的是關于python實現發(fā)送帶附件的郵件代碼分享內容，需要的朋友們可以參考下。2020-09-09
在Python中，filter函數是一種內置的高階函數，它能夠接受一個函數和一個迭代器，然后返回一個新的迭代器，本文主要來介紹一下Python中filter函數的具體用法，需要的可以參考一下2023-07-07
這篇文章主要介紹了python numpy中setdiff1d的用法說明，具有很好的參考價值，希望對大家有所幫助。一起跟隨小編過來看看吧2021-04-04
Django使用Channels實現WebSocket的方法
WebSocket是一種在單個TCP連接上進行全雙工通訊的協(xié)議。WebSocket允許服務端主動向客戶端推送數據。這篇文章主要介紹了Django使用Channels實現WebSocket,需要的朋友可以參考下2019-07-07