初步介绍Python中的pydoc模块和distutils模块

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] 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 文档的约定，又使用了一些有关 Python 导入、继承和其它类似的实用知识。此外， pydoc 有绝对的天赋可以使自己在不同的操作模式下被使用（马上就能看到更多有关这个论点的资料）。让我们用一些时间，看看通过 OS 命令行调用的 manpage 风格的用法。

假设您已将上述模块 mymod 安装在您的系统上，但不知道它有什么用处（在示例中并不多）。您可以阅读源代码，不过更简单的方法可能是：
清单 2：获取‘manpage'风格的文档

% 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