![](../../img/interpret.jpg)
Python 簡易手冊
單元 4 - 文件字串
當開發軟體 (software) 到一定規模之後,往往需要編寫軟體技術文件 (software documentation) 作為輔助,技術文件主要是程式相關定義的說明或教學,因為開發工作往往不是只有自己一個人做,技術文件有助於在移交工作後,讓團隊其他成員理解程式碼 (code) 功能。
Python 利用文件字串 (documentation string) 來寫技術文件,這是直接用三引號字串 (triple-quoted string) 直接定義在程式碼中,然後可以用內建屬性 (attribute) __doc__ 存取,舉簡單例子如下
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | # 從標準程式庫引入 random import random # 印出 random 的文件字串 print(random.__doc__) # 印出分隔線 print("~~~~~~") # 印出 randint() 的文件字串 print(random.randint.__doc__) # 檔名: doc_demo.py # 說明: 《Python簡易手冊》的範例 # 網址: http://kaiching.org # 作者: Kaiching Chang # 時間: 2024 年 2 月 |
第 2 行先引入標準程式庫 (standard library) 中的 random 程式庫
1 2 | # 從標準程式庫引入 random import random |
第 5 行印出 random 的文件字串
4 5 | # 印出 random 的文件字串 print(random.__doc__) |
然後第 11 行印出 random 中 randint() 函數 (function) 的文件字串
10 11 | # 印出 randint() 的文件字串 print(random.randint.__doc__) |
簡單說,這個例子先印出 random 的文件字串,然後印出分隔線,最後印出 randint() 的文件字串,執行結果如下
> python doc_demo.py |
Random variable generators. bytes ----- uniform bytes (values between 0 and 255) integers -------- uniform within range sequences --------- pick random element pick random sample pick weighted random sample generate random permutation distributions on the real line: ------------------------------ uniform triangular normal (Gaussian) lognormal negative exponential gamma beta pareto Weibull distributions on the circle (angles 0 to 2pi) --------------------------------------------- circular uniform von Mises discrete distributions ---------------------- binomial General notes on the underlying Mersenne Twister core generator: * The period is 2**19937-1. * It is one of the most extensively tested generators in existence. * The random() method is implemented in C, executes in a single Python step, and is, therefore, threadsafe. ~~~~~~ Return random integer in range [a, b], including both end points. |
> |
由上可以看到 random 的文件字串有很多行,而 randint() 的文件字串只有一行,基本上由於 random 是程式庫,也就是模組 (module) ,裡頭包含很多定義,所以 random 的文件字串就是說明這個模組的功能。
模組是 Python 的程式檔案,凡是副檔名 .py 的 Python 程式檔案都是模組,單元 68 - 模組與 import 陳述會進一步介紹模組與 import 陳述。
原則上文件字串的第一行是簡單扼要地說明功能,其下如有需要,像是提供簡單的使用範例才會有更多的行數,而 randint() 的文件字串僅有說明,事實上 randint() 就是需要提供兩個整數引數 (argument) 才能成功回傳兩個引數之間的整數,所以雖然只有一行也直接說明用法。
定義文件字串使用三引號字串,基本上前後連續三個單引號或雙引號都是三引號字串,但是單引號及雙引號不能在連續三引號中混用,以下例子示範在模組、函數、類別 (class) 及方法 (method) 中定義文件字串
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 | """這是模組文件字串 僅作示範用 第三行""" # 定義函數 def do_something(): """這是函數文件字串 僅作示範用 第三行""" pass # 定義類別 class ClassDemo: """這是類別文件字串 僅作示範用 第三行""" # 定義方法 def do_something(): """這是方法文件字串 僅作示範用 第三行""" pass # 印出上述定義的文件字串 print(__doc__) print(do_something.__doc__) print(ClassDemo.__doc__) print(ClassDemo.do_something.__doc__) # 檔名: doc_demo2.py # 說明: 《Python簡易手冊》的範例 # 網址: http://kaiching.org # 作者: Kaiching Chang # 時間: 2024 年 2 月 |
這個例子主要示範定義文件字串的位置,模組文件字串放在檔案開頭,如第 1 行到第 3 行
1 2 3 | """這是模組文件字串 僅作示範用 第三行""" |
函數文件字串放在關鍵字 (keyword) def 的下一行,如第 7 行到第 9 行
5 6 7 8 9 10 | # 定義函數 def do_something(): """這是函數文件字串 僅作示範用 第三行""" pass |
上面關鍵字 pass 表示什麼都不做,單元 49 - pass 陳述與省略符號 ...會詳細介紹 pass 的用法。
類別文件字串放在關鍵字 class 的下一行,如第 14 行到第 16 行
12 13 14 15 16 | # 定義類別 class ClassDemo: """這是類別文件字串 僅作示範用 第三行""" |
方法文件字串一樣放在關鍵字 def 的下一行,如第 20 行到第 22 行
18 19 20 21 22 23 | # 定義方法 def do_something(): """這是方法文件字串 僅作示範用 第三行""" pass |
底下執行部分直接印出這四組文件字串,執行結果如下
> python doc_demo2.py |
這是模組文件字串 僅作示範用 第三行 這是函數文件字串 僅作示範用 第三行 這是類別文件字串 僅作示範用 第三行 這是方法文件字串 僅作示範用 第三行 |
> |
文件字串跟註解 (comment) 類似,屬於程式設計師額外在程式碼中加入的說明部分,雖說沒有強制規定撰寫內容或格式,不過這還是要以開發團隊或專案為主,也就是維持團隊或專案的一貫風格。
參考資料
![](../../img/pydoing.gif)