27. 第 6 章 類別的繼承 6-27
本 書 後 面 會 談 到 描 述 器 , 屆 時 你 會 知 道 描 述 器 的 定 義 方 式 , 也 就 能 明白
__get__()的意義,基本上,你可以忽略 super(type)的用法,若真的想要深
入瞭解,可以參考〈Things to Know About Python Super〉中的說明:
www.artima.com/weblogs/viewpost.jsp?thread=236275
www.artima.com/weblogs/viewpost.jsp?thread=236278
www.artima.com/weblogs/viewpost.jsp?thread=237121
6.3 文件與套件資源
如果你跟隨本書到達這一節,表示對於函式、模組與類別的定義與撰寫等,
都有了一定的認識。一個好的語言必須有好的程式庫來搭配,而一個好的程式
庫必定得有清楚、詳盡的文件,對 Python 來說正是如此,在這一節中,將先
從如何撰寫文件開始,之後來看看如何查詢既有的文件,以及去哪尋找社群貢
獻的套件。
6.3.1 DocString
對於程式庫的使用,實際上,Python 的標準程式庫原始碼本身就附有文
件,舉 list()來說,如果在 REPL 中鍵入 list.__doc__會發生什麼事呢?
>>> list.__doc__
"list() -> new empty listnlist(iterable) -> new list initialized from iterable's
items"
>>>
這字串很奇怪,還有一些換行字元?如果鍵入 help(list)就不會覺得奇怪
了:
>>> help(list)
Help on class list in module builtins:
class list(object)
| list() -> new empty list
| list(iterable) -> new list initialized from iterable's items
|
略…
28. 6-28 Python 3.5 技術手冊
實際上,help()函式會取得 list.__doc__的字串,結合一些它在程式庫中查
找出來的資訊加以顯示。透過__doc__取得的字串稱為 DocString,可以自行在
原始碼中定義。例如,想為自訂函式定義 DocString,可以如下:
def max(a, b):
'''Given two numbers, return the largest one.'''
return a if a > b else b
在函式、類別或模組定義的一開頭,使用'''包括起來的多行字串,會成為函
式、類別或模組的__doc__屬性值,也就會是會成為 help()的輸出內容之一。先來
看個函式的例子:
>>> def max(a, b):
... '''Given two numbers, return the largest one.'''
... return a if a > b else b
...
>>> max.__doc__
'Given two numbers, return the largest one.'
>>> help(max)
Help on function max in module __main__:
max(a, b)
Given two numbers, return the largest one.
>>>
如果 DocString 只有一行,那麼'''包括起來的字串就不會換行。如果'''
包括換行與縮排,那麼__doc__的內容也會包括這些換行與縮排。
因此,慣例上,單行的 DocString 會是在一行中使用'''左右含括起來,而
函式或方法中的 DocString 若是多行字串,'''緊接的第一行,會是個函式的簡
短描述,之後空一行後,才是參數或其他相關說明,最後換一行並縮排結束,
這樣在 help()輸出時會比較美觀。例如:
>>> def max(a, b):
... '''Find the maximum number.
...
... Given two numbers, return the largest one.
... '''
... return a if a > b else b
...
>>> help(max)
Help on function max in module __main__:
max(a, b)
Find the maximum number.
29. 第 6 章 類別的繼承 6-29
Given two numbers, return the largest one.
>>>
如果是類別或模組的多行 DocString,會是在'''後馬上換行,然後以相同
層次縮排,並開始撰寫說明。例如:
docs openhome/abc.py
# Copyright 2016 openhome.cc. All Rights Reserved.
# Permission to use, copy, modify, and distribute this code and its
# documentation for educational purpose.
"""
Abstract Base Classes (ABCs) for Python Tutorial
Just a demo for DocStrings.
"""
from abc import ABCMeta, abstractmethod
class Ordering(metaclass=ABCMeta):
'''
A abc for implementing rich comparison methods.
The class must define __gt__() and __eq__() methods.
'''
@abstractmethod
def __eq__(self, other):
'''Return a == b'''
pass
@abstractmethod
def __gt__(self, other):
'''Return a > b'''
pass
def __ge__(self, other):
'''Return a >= b'''
30. 6-30 Python 3.5 技術手冊
return self > other or self == other
略…
如果想針對套件來撰寫 DocString,可以在套件相對應的資料夾中之
__init__.py 使用'''來含括字串撰寫。例如:
docs openhome/__init__.py
'''
Libraries of openhome.cc
If you can't explain it simply, you don't understand it well enough.
- Albert Einstein
'''
在 REPL 中,可針對套件使用 help()。例如:
>>> import openhome.abc
>>> help(openhome)
Help on package openhome:
NAME
openhome - Libraries of openhome.cc
DESCRIPTION
If you can't explain it simply, you don't understand it well enough.
- Albert Einstein
PACKAGE CONTENTS
abc
FILE
c:workspacedocsopenhome__init__.py
>>>
至於方才定義的 abc.py 模組,使用 help()的結果如下:
>>> help(openhome.abc)
Help on module openhome.abc in openhome:
NAME
openhome.abc - Abstract Base Classes (ABCs) for Python Tutorial
31. 第 6 章 類別的繼承 6-31
DESCRIPTION
Just a demo for DocStrings.
CLASSES
builtins.object
Ordering
class Ordering(builtins.object)
| A abc for implementing rich comparison methods.
|
| The class must define __gt__() and __eq__() methods.
|
| Methods defined here:
|
| __eq__(self, other)
| Return a == b
|
| __ge__(self, other)
| Return a >= b
略…
你 也 可 以 直 接 使 用 help(openhome.abc.Ordering) 、
help(openhome.abc.Ordering.__eq__)來分別查詢相對應的 DocString。如果想要
進一步認識 DocString 的撰寫或使用慣例,可以參考標準程式庫(位於 Python
安裝目錄的 Lib)原始碼中的撰寫方式,或者是參考 PEP 275:
www.python.org/dev/peps/pep-0257/#what-is-a-docstring
6.3.2 查詢官方文件
除了使用 help()查詢文件之中,對於 Python 官方的程式庫,也可以在線上
查詢,文件位址是 docs.python.org,預設會顯示最新版本的 Python 文件,可
以在首頁左上角選取想要的版本。
圖 6.1 Python 官方文件
32. 6-32 Python 3.5 技術手冊
在 1.2.3 中談過,Windows 版本的 Python 裏,安裝資料夾中提供了一個
python351.chm 檔案,包含了許多 Python 文件,方便隨時取用查閱。
在官方文件中,有關於程式庫 API 查詢的部份,是列在 Indices and tables 中,
在撰寫 Python 程式的過程中,經常需要在這邊查詢相關 API 如何使用。
圖 6.2 API 索引
除了連上網站查詢官方 API 文件之外,還可以使用內建的 pydoc 模組啟動
一個簡單的 pydoc 伺服器,例如:
>python -m pydoc -p 8080
Server ready at http://localhost:8080/
Server commands: [b]rowser, [q]uit
server>
在執行 python 時指定-m 引數,表示執行指定模組中頂層的程式流程,在這邊
是指定執行 pydoc 模組,並附上-p 引數指定了 8080,這會建立一個簡單的文件
伺服器,並在 8080 連接埠接受連線。你可以使用 b 開啟預設瀏覽器,或自行
啟動瀏覽器連線 http://localhost:8080/,就可以進行文件查詢。