可愛的Python: pydoc和distutils模組

一年前，如果您問一個誠實的 Python 推廣者，Python 是否缺少某些如 Perl 等其它語言所擁有的重要的東西。答案很可能會是“是”。這並不是說 Python 缺少一定範圍的模組和包的支援（包括 Python 自身和擴充模組）。這當然也不是 Python 勝人一籌的明確的運算式和簡潔的物件導向。

建立在 Python 社區之上

Python 所欠缺的東西就是被 Perl 開發人員描述為“社會因素”的東西。但即使這裡，欠缺社會因素也並不意味著缺少一個積極的、智能的以及有支援力的 Python 社區 ― Python 有很多這樣的社區。一年前的 Python 極度缺乏的是用來共用 Python 代碼的充分規劃的基礎結構。代碼共用是特定的、分散的和非常平凡的工作。

改進 Python 社會基礎的第一步可能是 Tim Middleton 建立的 Vaults of Parnassus 網站（請參閱本文後面的 參考資料）。Python 開發人員第一次擁有了一個專門的地方，那裡有（幾乎）所有已提供的第三方模組、包和工具。但這個地方仍有一些缺陷，使得這個網站可能比 Comprehensive Perl Archive Network 少了些優勢（不過外表比後者更美觀），Vaults 網站只是指向實際的資源位置，並不作為實際資源的鏡像。網站由 Middleton 手工維護，有時候更新很慢；並且 Vex.Net （Vaults 坐落的網站）曾經有間歇斷線的故障。但總的來說，Vaults of Parnassus 在建立強大的 Python 社區的架構先決條件方面提供了寶貴的資源。

有了這樣一個公用網站，Python 社區所需的一切就是用一致的、可靠的方法安裝所有這些可用的模組、包以及工具；再用同樣簡潔的方法指出它們所起的作用。隨著標準 Python 發布的一些新標準模組也給出瞭解決方法。

pydoc

Ka-Ping Yee 曾建立了一個相當著名的模組，名叫 pydoc （比較而言： pydoc 可以做到 perldoc 所能做的任何事，並且做得更好、更漂亮:-）。對於 Python 2.1 來說， pydoc （以及它支援的 inspect ）是標準庫的一部分。而對於使用 Python 1.5.2、1.6 或者 2.0 版本的使用者來說，下載並安裝 pydoc 也很簡單 ― 請立即下載（請參閱 參考資料）。

作為提供給閱讀這篇 Python 文章的任何初學者的背景資料，Python 一直有些半正式的文檔標準。這些標準並沒有試圖過度地限制開發人員，而是給開發人員提供“一種明顯的寫文檔的方法。”幸運的是，通常情況下，Python 開發人員所寫的文檔比使用其它語言的典型開發人員所寫的要好得多。

Python 文檔之所以“優秀”的主要因素是使用所謂的“docstring”。雖然 docstring 實際上只是一個被稱為 _doc_ 的變數，但還是有一個普遍使用的建立它們的捷徑：只要在模組、函數 def 、類定義或方法 def 的頭部放入一個簡單的由（三重）引號括起來的字串。此外，還有幾個接近標準的模組層級的“魔術”變數名被經常使用。儘管那些文檔規則不太正式，但幾乎所有第三方的模組和標準模組的文檔都使用相同的模式。讓我們來看一個使用大部分元素的簡化樣本：

清單 1: 附帶典型文檔的模組 mymod.py

#!/usr/bin/python
"""Show off features of [pydoc] module
This is a silly module to
demonstrate 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