pydoc
Ka-Ping Yee 曾創(chuàng)建了一個(gè)相當(dāng)著名的模塊，名叫 pydoc （比較而言： pydoc 可以做到 perldoc 所能做的任何事，并且做得更好、更漂亮:-）。對(duì)于 Python 2.1 來說， pydoc （以及它支持的 inspect ）是標(biāo)準(zhǔn)庫的一部分。而對(duì)于使用 Python 1.5.2、1.6 或者 2.0 版本的用戶來說，下載并安裝 pydoc 也很簡單 ― 請(qǐng)立即下載（請(qǐng)參閱 參考資料）。
作為提供給閱讀這篇 Python 文章的任何初學(xué)者的背景資料，Python 一直有些半正式的文檔標(biāo)準(zhǔn)。這些標(biāo)準(zhǔn)并沒有試圖過度地限制開發(fā)者，而是給開發(fā)者提供“一種明顯的寫文檔的方法。”幸運(yùn)的是，通常情況下，Python 開發(fā)者所寫的文檔比使用其它語言的典型開發(fā)者所寫的要好得多。
Python 文檔之所以“優(yōu)秀”的主要因素是使用所謂的“docstring”。雖然 docstring 實(shí)際上只是一個(gè)被稱為 _doc_ 的變量，但還是有一個(gè)普遍使用的創(chuàng)建它們的快捷方式：只要在模塊、函數(shù) def 、類定義或方法 def 的頭部放入一個(gè)簡單的由（三重）引號(hào)括起來的字符串。此外，還有幾個(gè)接近標(biāo)準(zhǔn)的模塊級(jí)的“魔術(shù)”變量名被經(jīng)常使用。盡管那些文檔規(guī)則不太正式，但幾乎所有第三方的模塊和標(biāo)準(zhǔn)模塊的文檔都使用相同的模式。讓我們來看一個(gè)使用大部分元素的簡化示例：
清單 1: 附帶典型文檔的模塊 mymod.py
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
|
#!/usr/bin/python"""Show off features of [pydoc] moduleThis is a silly module todemonstrate docstrings"""__author__ = 'David Mertz'__version__= '1.0'__nonsense__ = 'jabberwocky'class MyClass: """Demonstrate class docstrings""" def __init__ (self, spam=1, eggs=2): """Set default attribute values only Keyword arguments: spam ― a processed meat product eggs ― a fine breakfast for lumberjacks """ self.spam = spam self.eggs = eggs |
pydoc 模塊利用了 Python 文檔的約定，又使用了一些有關(guān) Python 導(dǎo)入、繼承和其它類似的實(shí)用知識(shí)。此外， pydoc 有絕對(duì)的天賦可以使自己在不同的操作模式下被使用（馬上就能看到更多有關(guān)這個(gè)論點(diǎn)的資料）。讓我們用一些時(shí)間，看看通過 OS 命令行調(diào)用的 manpage 風(fēng)格的用法。
假設(shè)您已將上述模塊 mymod 安裝在您的系統(tǒng)上，但不知道它有什么用處（在示例中并不多）。您可以閱讀源代碼，不過更簡單的方法可能是：
清單 2：獲取‘manpage'風(fēng)格的文檔
|
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
|
% pydoc.py mymodPython Library Documentation: module mymodNAME mymod - Show off features of [pydoc] moduleFILE /articles/scratch/cp18/mymod.pyDESCRIPTION This is a silly module to demonstrate docstringsCLASSES MyClass class MyClass | Demonstrate class docstrings | | __init__(self, spam=1, eggs=2) | Set default attribute values only | | Keyword arguments: | spam ― a processed meat product | eggs ― a fine breakfast for lumberjacksDATA __author__ = 'David Mertz' __file__ = './mymod.pyc' __name__ = 'mymod' __nonsense__ = 'jabberwocky' __version__ = '1.0'VERSION 1.0AUTHOR David Mertz |
根據(jù)特定的平臺(tái)和安裝過程，上述樣本可能會(huì)顯示在一個(gè)允許滾屏、搜索等功能并突出顯示某些關(guān)鍵字的文本查看器中。對(duì)于像這樣簡單的示例，只是比純粹的閱讀源代碼好一點(diǎn)。但請(qǐng)考慮一下像下面這樣簡單的示例：
清單 3：檢查類的繼承結(jié)構(gòu)
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
|
% cat mymod2.pyfrom mymod import MyClassclass MyClass2(MyClass): """Child class""" def foo(self): pass% pydoc.py mymod2.MyClass2Python Library Documentation: class MyClass2 in mymod2class MyClass2(mymod.MyClass) | Child class | | __init__(self, spam=1, eggs=2) from mymod.MyClass | | foo(self) |
在這個(gè)快速報(bào)告中，我們可以知道 MyClass2 有 __init__() 和 foo() 方法（以及相應(yīng)的參數(shù)），哪個(gè)方法是類自身實(shí)現(xiàn)的以及其它哪些方法是繼承而來（以及被繼承的類所處的位置）。
另一個(gè)美妙的類似于 manpage 的功能是用來在模塊中搜索關(guān)鍵字的 -k 選項(xiàng)。例如：
清單 4：為任務(wù)定位適當(dāng)?shù)哪K
|
1
2
3
4
5
6
7
|
% pydoc.py -k uuencodeuu - Implementation of the UUencode and UUdecode functions.% pydoc.py uuPython Library Documentation: module uuNAME uu - Implementation of the UUencode and UUdecode functions.[...] |
pydoc 除了它的命令行用法之外，還有其它四種“模式”可以顯示被生成的同樣的文檔。
Shell 模式：在 Python 交互式 shell 中，您可以導(dǎo)入 pydoc 的 help() 函數(shù)，這樣就能夠在不離開交互式會(huì)話的情況下獲得任何對(duì)象的幫助。也可以只輸入一個(gè) help 進(jìn)入交互式“help 解釋器”。例如：
清單 5：shell 模式下的交互式 help 解釋器
|
1
2
3
4
5
6
7
8
9
10
11
|
#------- Interactive shell with help enhancements ------#>>> from pydoc import help>>> import uu>>> help(uu.test)Help on function test in module uu:test() uuencode/uudecode main program>>> helpWelcome to Python 2.0! This is the online help utility.[...introductory message about help shell...]help> |
- Web 服務(wù)器模式：僅使用 -p 選項(xiàng)， pydoc 就會(huì)在 LOCALHOST 上作為一個(gè)簡單的 Web 服務(wù)器自啟動(dòng)。您可以使用任何 Web 瀏覽器瀏覽所有已安裝在現(xiàn)有操作系統(tǒng)上的模塊。這個(gè)服務(wù)器的主頁是一張模塊列表，根據(jù)目錄（并用瀏覽器支持的醒目色塊）將它們分組。此外，您查看其文檔的每個(gè)模塊也廣泛分布著它導(dǎo)入的函數(shù)、方法以及指向任何模塊的鏈接。
- HTML 生成器模式： -w 選項(xiàng)對(duì)于 pydoc 可以歸檔的任何文檔都能生成 HTML 文檔頁面。這些頁面與您在 Web 服務(wù)器模式下可能會(huì)瀏覽到的頁面本質(zhì)上是一回事，但頁面是靜態(tài)的，可以進(jìn)行存檔、傳輸?shù)鹊取?/li>
- TK 瀏覽器模式： -g 選項(xiàng)將創(chuàng)建一個(gè)和 xman 或 tkman 風(fēng)格很相似的“圖形幫助瀏覽器。”
distutils
對(duì)于 Python 1.6 來說， distutils 包已經(jīng)成為標(biāo)準(zhǔn) Python 庫的一部分。 distutils 包有兩個(gè)目的。一方面， distutils 希望讓最終用戶覺得安裝新模塊、包和工具的過程一致而輕松。另一方面， distutils 還希望讓新模塊、包和工具的開發(fā)者覺得創(chuàng)建這些容易安裝的分發(fā)包很輕松。讓我們簡要看一下這兩個(gè)方面。
在最簡單的情況下，開發(fā)者將已經(jīng)選擇為您特定的平臺(tái)創(chuàng)建了安裝程序。如果是這種情況，您其實(shí)根本不需要知道 distutils 的存在。目前， distutils 能夠?yàn)橹С?RPM 的 Linux 系統(tǒng)創(chuàng)建 RPM，為 Win32 系統(tǒng)創(chuàng)建 Windows EXE 安裝程序。雖然這兩個(gè)平臺(tái)是主角，但還存在著其它平臺(tái)，要么開發(fā)者可能已經(jīng)有了適用于您的平臺(tái)的解決方法（要么有創(chuàng)建一個(gè)安裝程序的時(shí)間和興趣）。
雖然沒有最簡單的例子，但幸運(yùn)的是下一個(gè)出色的例子并沒有復(fù)雜太多。假設(shè)您獲取了一個(gè)支持 distutils 的源代碼分發(fā)包，您可以依靠大量的東西（當(dāng)然，在一切正常的情況下）。分發(fā)包的歸檔文件必須按照標(biāo)準(zhǔn)歸檔文件格式 ― 通常可以是 .zip 格式或 .tgz / .tar.gz 格式（偶爾會(huì)是 .tbz 格式或 tar.Z 格式， .sit 格式支持很快會(huì)添加到 MacOS 中去）。多數(shù)時(shí)候，Windows 用戶使用 zip 格式文件，而 Linux/UNIX 用戶使用 tarball 格式文件。不過要想在大多數(shù)平臺(tái)上解包大部分的文件格式并不困難。一旦您將歸檔文件解包了，您就會(huì)獲得一個(gè)文件集合，它被保存在與歸檔文件同名的目錄里。例如：
清單 6：將一個(gè) [distutils] 歸檔文件解包
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
|
E:\Archive\devel>unzip -q Distutils-1_0_2.zipE:\Archive\devel>cd Distutils-1.0.2E:\Archive\devel\Distutils-1.0.2>lsThe volume label in drive E is ARCHIVE.The Volume Serial Number is E825:C814.Directory of E:\Archive\devel\Distutils-1.0.2 6-14-01 0:38a <DIR> 0 . 6-14-01 0:38a <DIR> 0 .. 5-03-01 6:30p 15355 0 CHANGES.txt 5-03-01 6:32p <DIR> 0 distutils 5-03-01 6:32p <DIR> 0 doc 5-03-01 6:32p <DIR> 0 examples10-02-00 11:47p 373 0 MANIFEST.in 5-03-01 6:32p <DIR> 0 misc 5-03-01 6:32p 496 0 PKG-INFO 4-20-01 2:30p 14407 0 README.txt 6-29-00 11:45p 1615 0 setup.cfg 5-03-01 6:17p 1120 0 setup.py 4-20-01 2:29p 9116 0 TODO 4-11-00 9:40p 836 0 USAGE.txt |
大多數(shù)模塊分發(fā)包的文件和目錄會(huì)比這個(gè)例子中顯示的要少。你真正需要的僅僅是文件 setup.py ，其中包含安裝指令。但實(shí)際上，大家一致希望目錄中有其它文件，這樣 setup.py 就有可以安裝的東西了。這里，您需要做的是：
|
1
|
E:\archive\devel\Distutils-1.0.2> python setup.py install |
至少那應(yīng)該是您該做的事情。如果出現(xiàn)問題，請(qǐng)閱讀（很可能也包含在 setup.py 中的） README.txt 或 README 文件。然后，再查閱 Greg Ward 的 Installing Python Modules 文檔。（請(qǐng)參閱 參考資料）。
接下來該做什么呢？您可以通過名字來猜測， setup.py 其實(shí)只是普通的 Python 腳本，所以當(dāng)它運(yùn)行時(shí)可以做任何事。但在大多數(shù)情況下 setup.py 會(huì)有一種相當(dāng)固定的格式。可能看上去像這樣：
清單 7：最小的 setup.py 安裝腳本
|
1
2
3
4
5
6
7
8
9
10
11
12
|
#!/usr/bin/env python"""Setup script for the sample #1 module distribution: single top-level pure Python module, named explicitly in 'py_modules'."""from distutils.core import setupsetup (# Distribution meta-data name = "sample", version = "1.0", description = "Distutils sample distribution #1",# Description of modules and packages in the distribution py_modules = ['sample'], ) |
這里真正的工作是由導(dǎo)入的 distutils 實(shí)現(xiàn)，特別是由 setup() 函數(shù)來實(shí)現(xiàn)。基本上， setup() 函數(shù)采用一組包含一列需要安裝的東西（除 py_modules 外還可能有 packages 或 ext_modules 或其它東西）的已命名的變量。
distutils 的魔力在于 創(chuàng)建模塊分發(fā)包時(shí)利用安裝時(shí)使用的完全相同的 setup.py 文件。一旦您 ― 模塊開發(fā)者 ― 創(chuàng)建了一個(gè) setup.py 腳本（也可能是‘setup.cfg'或其它擴(kuò)展名）指定了需要安裝的東西，創(chuàng)建分發(fā)包所要做的全部事情就是（下面的一步或幾步）：
清單 8：創(chuàng)建模塊分發(fā)包
|
1
2
3
|
% python setup.py sdist% python setup.py bdist_wininst% python setup.py bdist_rpm |
根據(jù)您指定的特定的分發(fā)包，您將創(chuàng)建一個(gè)標(biāo)準(zhǔn)的歸檔文件（tarball 或 zip 格式文件，取決于平臺(tái)類型）或者一個(gè)完整的安裝程序（像上面討論過的那樣）。
把兩者結(jié)合在一起
雖然我們還沒有完全達(dá)到目的，但是 Python 已經(jīng)逐步成為最容易使用的編程語言的一種， 而且還是最容易使用的編程 社區(qū)的一種。雖然某些新的工具還有一些需要克服的缺陷，但在普遍意義上，讓 Python 對(duì)用戶透明這個(gè)要求已經(jīng)實(shí)現(xiàn)了。
