Python 速查手冊

6.3 __doc__

本書已有新版,請參考 Python 簡易手冊 - 目錄

__doc__ 為類別 (class) 的預設屬性 (attribute) ,用以當作文件字串 (docstring) ,文件字串用三引號字串 (string) 定義,三引號字串的特性是保留原始編排的方式,並且可以跨多行,主要用途是撰寫函數 (function) 、類別、方法 (method) 及模組 (module) 的功能與說明。

利用內建函數 (built-in function) print() 可以直接印出 __doc__ 屬性,這裡可以看到整數型態的文件字串,分成兩個部分,第一部分是整數型態的建構子 (constructor) ,也就是怎麼用內建函數 int() 建立整數型態的物件 (object) ,空一行後為說明,包括最底下舉例用二進位的數字字串建立的整數物件

a = 22
print(a.__doc__)

#《程式語言教學誌》的範例程式
# http://kaiching.org/
# 檔名:doc01.py
# 功能:示範定義類別
# 作者:張凱慶

於命令列執行以上程式,結果如下

$ python3 doc01.py
int(x=0) -> integer
int(x, base=10) -> integer
 
Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating point numbers, this truncates towards zero.
 
If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by '+' or '-' and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal.
>>> int('0b100', base=0)
4
$

這邊繼續看到怎麼在函數中定義文件字串,文件字串會定義在關鍵字 (keyword) def 的下一行,由於是舉例用,因此函數內容僅用關鍵字 pass 帶過

def demo():
    """函數的文件字串"""
    pass
    
print(demo.__doc__)

#《程式語言教學誌》的範例程式
# http://kaiching.org/
# 檔名:doc02.py
# 功能:示範定義類別
# 作者:張凱慶

於命令列執行以上程式,結果如下

$ python3 doc02.py
函數的文件字串
$

類別中定義文件字串是在關鍵字 class 的下一行,由於這裡也是舉例用,因此類別內容僅用關鍵字 pass 帶過

class Demo:
    """類別的文件字串"""
    pass
    
print(Demo.__doc__)

#《程式語言教學誌》的範例程式
# http://kaiching.org/
# 檔名:doc03.py
# 功能:示範定義類別
# 作者:張凱慶

於命令列執行以上程式,結果如下

$ python3 doc03.py
類別的文件字串
$

方法中定義文件字串同樣是放在關鍵字 def 的下一行,這跟函數相同,利用方法名稱加上 __doc__ 屬性就可取得文件字串

class Demo2:
    def demo():
        """方法的文件字串"""
        pass

d = Demo2()
print(d.demo.__doc__)

#《程式語言教學誌》的範例程式
# http://kaiching.org/
# 檔名:doc04.py
# 功能:示範定義類別
# 作者:張凱慶

於命令列執行以上程式,結果如下

$ python3 doc04.py
方法的文件字串
$

相關教學影片

上一頁: 6.2 __str__()
Python 速查手冊 - 目錄
下一頁: 6.4 類別屬性與實體屬性
回 Python 教材首頁
回程式語言教材首頁