pydoc
Ka-Ping Yee 曾創建了一個相當著名的模塊,名叫 pydoc (比較而言: pydoc 可以做到 perldoc 所能做的任何事,并且做得更好、更漂亮:-)。對于 Python 2.1 來說, pydoc (以及它支持的 inspect )是標準庫的一部分。而對于使用 Python 1.5.2、1.6 或者 2.0 版本的用戶來說,下載并安裝 pydoc 也很簡單 ?D 請立即下載(請參閱 參考資料)。
作為提供給閱讀這篇 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 ?D a processed meat product eggs ?D a fine breakfast for lumberjacks """ self.spam = spam self.eggs = eggs
pydoc 模塊利用了 Python 文檔的約定,又使用了一些有關 Python 導入、繼承和其它類似的實用知識。此外, pydoc 有絕對的天賦可以使自己在不同的操作模式下被使用(馬上就能看到更多有關這個論點的資料)。讓我們用一些時間,看看通過 OS 命令行調用的 manpage 風格的用法。
假設您已將上述模塊 mymod 安裝在您的系統上,但不知道它有什么用處(在示例中并不多)。您可以閱讀源代碼,不過更簡單的方法可能是:
清單 2:獲取‘manpage'風格的文檔
% pydoc.py mymod Python Library Documentation: module mymod NAME mymod - Show off features of [pydoc] module FILE /articles/scratch/cp18/mymod.py DESCRIPTION This is a silly module to demonstrate docstrings CLASSES MyClass class MyClass | Demonstrate class docstrings | | __init__(self, spam=1, eggs=2) | Set default attribute values only | | Keyword arguments: | spam ?D a processed meat product | eggs ?D a fine breakfast for lumberjacks DATA __author__ = 'David Mertz' __file__ = './mymod.pyc' __name__ = 'mymod' __nonsense__ = 'jabberwocky' __version__ = '1.0' VERSION 1.0 AUTHOR David Mertz
根據特定的平臺和安裝過程,上述樣本可能會顯示在一個允許滾屏、搜索等功能并突出顯示某些關鍵字的文本查看器中。對于像這樣簡單的示例,只是比純粹的閱讀源代碼好一點。但請考慮一下像下面這樣簡單的示例:
清單 3:檢查類的繼承結構
% cat mymod2.py from mymod import MyClass class MyClass2(MyClass): """Child class""" def foo(self): pass % pydoc.py mymod2.MyClass2 Python Library Documentation: class MyClass2 in mymod2 class MyClass2(mymod.MyClass) | Child class | | __init__(self, spam=1, eggs=2) from mymod.MyClass | | foo(self)
在這個快速報告中,我們可以知道 MyClass2 有 __init__() 和 foo() 方法(以及相應的參數),哪個方法是類自身實現的以及其它哪些方法是繼承而來(以及被繼承的類所處的位置)。
另一個美妙的類似于 manpage 的功能是用來在模塊中搜索關鍵字的 -k 選項。例如:
清單 4:為任務定位適當的模塊
% pydoc.py -k uuencode uu - Implementation of the UUencode and UUdecode functions. % pydoc.py uu Python Library Documentation: module uu NAME uu - Implementation of the UUencode and UUdecode functions. [...]
pydoc 除了它的命令行用法之外,還有其它四種“模式”可以顯示被生成的同樣的文檔。
??? Shell 模式:在 Python 交互式 shell 中,您可以導入 pydoc 的 help() 函數,這樣就能夠在不離開交互式會話的情況下獲得任何對象的幫助。也可以只輸入一個 help 進入交互式“help 解釋器”。例如:
??? 清單 5:shell 模式下的交互式 help 解釋器
#------- 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 >>> help Welcome to Python 2.0! This is the online help utility. [...introductory message about help shell...] help>
- ??? Web 服務器模式:僅使用 -p 選項, pydoc 就會在 LOCALHOST 上作為一個簡單的 Web 服務器自啟動。您可以使用任何 Web 瀏覽器瀏覽所有已安裝在現有操作系統上的模塊。這個服務器的主頁是一張模塊列表,根據目錄(并用瀏覽器支持的醒目色塊)將它們分組。此外,您查看其文檔的每個模塊也廣泛分布著它導入的函數、方法以及指向任何模塊的鏈接。
- ??? HTML 生成器模式: -w 選項對于 pydoc 可以歸檔的任何文檔都能生成 HTML 文檔頁面。這些頁面與您在 Web 服務器模式下可能會瀏覽到的頁面本質上是一回事,但頁面是靜態的,可以進行存檔、傳輸等等。
- ??? TK 瀏覽器模式: -g 選項將創建一個和 xman 或 tkman 風格很相似的“圖形幫助瀏覽器。”
distutils
對于 Python 1.6 來說, distutils 包已經成為標準 Python 庫的一部分。 distutils 包有兩個目的。一方面, distutils 希望讓最終用戶覺得安裝新模塊、包和工具的過程一致而輕松。另一方面, distutils 還希望讓新模塊、包和工具的開發者覺得創建這些容易安裝的分發包很輕松。讓我們簡要看一下這兩個方面。
在最簡單的情況下,開發者將已經選擇為您特定的平臺創建了安裝程序。如果是這種情況,您其實根本不需要知道 distutils 的存在。目前, distutils 能夠為支持 RPM 的 Linux 系統創建 RPM,為 Win32 系統創建 Windows EXE 安裝程序。雖然這兩個平臺是主角,但還存在著其它平臺,要么開發者可能已經有了適用于您的平臺的解決方法(要么有創建一個安裝程序的時間和興趣)。
雖然沒有最簡單的例子,但幸運的是下一個出色的例子并沒有復雜太多。假設您獲取了一個支持 distutils 的源代碼分發包,您可以依靠大量的東西(當然,在一切正常的情況下)。分發包的歸檔文件必須按照標準歸檔文件格式 ?D 通常可以是 .zip 格式或 .tgz / .tar.gz 格式(偶爾會是 .tbz 格式或 tar.Z 格式, .sit 格式支持很快會添加到 MacOS 中去)。多數時候,Windows 用戶使用 zip 格式文件,而 Linux/UNIX 用戶使用 tarball 格式文件。不過要想在大多數平臺上解包大部分的文件格式并不困難。一旦您將歸檔文件解包了,您就會獲得一個文件集合,它被保存在與歸檔文件同名的目錄里。例如:
清單 6:將一個 [distutils] 歸檔文件解包
E:\Archive\devel>unzip -q Distutils-1_0_2.zip E:\Archive\devel>cd Distutils-1.0.2 E:\Archive\devel\Distutils-1.0.2>ls The 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:38a0 . 6-14-01 0:38a 0 .. 5-03-01 6:30p 15355 0 CHANGES.txt 5-03-01 6:32p 0 distutils 5-03-01 6:32p 0 doc 5-03-01 6:32p 0 examples 10-02-00 11:47p 373 0 MANIFEST.in 5-03-01 6:32p 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
大多數模塊分發包的文件和目錄會比這個例子中顯示的要少。你真正需要的僅僅是文件 setup.py ,其中包含安裝指令。但實際上,大家一致希望目錄中有其它文件,這樣 setup.py 就有可以安裝的東西了。這里,您需要做的是:
E:\archive\devel\Distutils-1.0.2> python setup.py install
至少那應該是您該做的事情。如果出現問題,請閱讀(很可能也包含在 setup.py 中的) README.txt 或 README 文件。然后,再查閱 Greg Ward 的 Installing Python Modules 文檔。(請參閱 參考資料)。
接下來該做什么呢?您可以通過名字來猜測, setup.py 其實只是普通的 Python 腳本,所以當它運行時可以做任何事。但在大多數情況下 setup.py 會有一種相當固定的格式。可能看上去像這樣:
清單 7:最小的 setup.py 安裝腳本
#!/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 setup setup (# Distribution meta-data name = "sample", version = "1.0", description = "Distutils sample distribution #1", # Description of modules and packages in the distribution py_modules = ['sample'], )
這里真正的工作是由導入的 distutils 實現,特別是由 setup() 函數來實現。基本上, setup() 函數采用一組包含一列需要安裝的東西(除 py_modules 外還可能有 packages 或 ext_modules 或其它東西)的已命名的變量。
distutils 的魔力在于 創建模塊分發包時利用安裝時使用的完全相同的 setup.py 文件。一旦您 ?D 模塊開發者 ?D 創建了一個 setup.py 腳本(也可能是‘setup.cfg'或其它擴展名)指定了需要安裝的東西,創建分發包所要做的全部事情就是(下面的一步或幾步):
清單 8:創建模塊分發包
% python setup.py sdist % python setup.py bdist_wininst % python setup.py bdist_rpm
根據您指定的特定的分發包,您將創建一個標準的歸檔文件(tarball 或 zip 格式文件,取決于平臺類型)或者一個完整的安裝程序(像上面討論過的那樣)。
把兩者結合在一起
雖然我們還沒有完全達到目的,但是 Python 已經逐步成為最容易使用的編程語言的一種, 而且還是最容易使用的編程 社區的一種。雖然某些新的工具還有一些需要克服的缺陷,但在普遍意義上,讓 Python 對用戶透明這個要求已經實現了。
更多文章、技術交流、商務合作、聯系博主
微信掃碼或搜索:z360901061

微信掃一掃加我為好友
QQ號聯系: 360901061
您的支持是博主寫作最大的動力,如果您喜歡我的文章,感覺我的文章對您有幫助,請用微信掃描下面二維碼支持博主2元、5元、10元、20元等您想捐的金額吧,狠狠點擊下面給點支持吧,站長非常感激您!手機微信長按不能支付解決辦法:請將微信支付二維碼保存到相冊,切換到微信,然后點擊微信右上角掃一掃功能,選擇支付二維碼完成支付。
【本文對您有幫助就好】元
