Python docstring文件字串
阿新 • • 發佈:2019-02-04
使用DocStrings
Python有一個很奇妙的特性,稱為文件字串,它通常被簡稱為docstrings。DocStrings是一個重要的工具,由於它幫助你的程式文件更加簡單易懂,你應該儘量使用它。你甚至可以在程式執行的時候,從函式恢復文件字串!
使用DocStrings
例7.8 使用DocStrings
#!/usr/bin/python # Filename: func_doc.py def printMax(x, y): '''Prints the maximum of two numbers. The two values must be integers.''' x = int(x) # convert to integers, if possible y = int(y) if x > y: print x, 'is maximum' else: print y, 'is maximum' printMax(3, 5) print printMax.__doc__
輸出
$ python func_doc.py
5 is maximum
Prints the maximum of two numbers.
The two values must be integers.
它如何工作
在函式的第一個邏輯行的字串是這個函式的文件字串。注意,DocStrings也適用於模組和類,我們會在後面相應的章節學習它們。
文件字串的慣例是一個多行字串,它的首行以大寫字母開始,句號結尾。第二行是空行,從第三行開始是詳細的描述。強烈建議你在你的函式中使用文件字串時遵循這個慣例。
你可以使用__doc__
(注意雙下劃線)呼叫printMax
函式的文件字串屬性(屬於函式的名稱)。請記住Python把每一樣東西都作為物件,包括這個函式。我們會在後面的類一章學習更多關於物件的知識。
如果你已經在Python中使用過help()
,那麼你已經看到過DocStings的使用了!它所做的只是抓取函式的__doc__
屬性,然後整潔地展示給你。你可以對上面這個函式嘗試一下——只是在你的程式中包括help(printMax)
。記住按q退出help
。
自動化工具也可以以同樣的方式從你的程式中提取文件。因此,我強烈建議你對你所寫的任何正式函式編寫文件字串。隨你的Python發行版附帶的pydoc命令,與help()
類似地使用DocStrings。