可爱的 Python: pydoc 和 distutils 模块

核心提示： 作为提供给阅读这篇 Python 文章的任何初学者的背景资料，Python 一直有些半正式的文档标准，可爱的 Python: pydoc 和 distutils 模块(2)，这些标准并没有试图过度地限制开发者，而是给开发者提供“一种明显的写文档的方法，还有几个接近标准的模块级的

作为提供给阅读这篇 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