Python pydoc模块详解:查看、生成帮助文档
#demo.py文件 def display(add): ''' 这是一个函数 ''' print(add) class my_cla: ''' 这是一个类 ''' def say(self,add): ''' 这是一个类实例方法 ''' print(add)如上所示,我们分别创建了 display() 函数和 my_cla 类,该类中还包含一个 say() 实例方法,并且我们为它们设置了说明性文档。
在此基础上,可以通过 help() 函数或者 __doc__ 属性来调用函数、类或者类方法的说明性文档。例如在上面程序的基础上,添加如下代码:
help(display) help(my_cla) help(my_cla.say)执行程序,运行结果为:
Help on function display in module __main__:
display(add)
这是一个函数
Help on class my_cla in module __main__:
class my_cla(builtins.object)
| 这是一个类
|
| Methods defined here:
|
| say(self, add)
| 这是一个类实例方法
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
Help on function say in module __main__:
say(self, add)
这是一个类实例方法
实际上,Python 还提供了 pydoc 模块,通过该模块可以快速地生成程序的帮助文档。接下来就详细讲解 pydoc 模块的用法。
pydoc在控制台中查看文档
和 help() 及 __doc__ 不同,使用 pydoc 模块无需编写任何 python 代码,通过执行 python 命令即可查看程序中成员的说明性文档。执行如下 Python 命令,即可在控制台查看指定模块的说明性文档,命令语法格式如下:
python -m pydoc 模块名
其中,-m 表示运行指定模块,这里表示要执行 pydoc 模块。注意在指定模块名时,除非其创建在 Python 解释器能自行找到的目录下,否则这里要明确模块所在的位置。以 demo.py 文件为例,在控制台执行如下命令:
python -m pydoc demo
执行此命令,即可看到 demo.py 文件中 display() 函数、my_cla 类以及该类中 say() 实例方法的说明性文档。读者可自行执行该命令查看输出结果,这里不再给出执行结果。如果读者执行该命令,可以看到,对于模块中各个成员的说明性文档,该命令有自己的组织方法,即总是按如下顺序来显示:值得一提的是,使用该命令在控制台输出执行模块的帮助信息时,可能一屏无法显示所有的信息,我们可以通过滚动鼠标滑轮或者按“空格”键来滑屏,查看后续的信息。
- 模块的文档说明:就是*.py 文件顶部的注释信息,这部分信息会被提取成模块的文档说明。
- CLASSES :列出该模块所包含的全部类。
- FUNCTIONS:列出该模块所包含的全部函数。
- DATA:列出该模块所包含的全部成员变量。
- FILE:显示该模块对应的源文件。
pydoc生成HTML文档
除此之外,pydoc 还可以将指定模块的帮助信息提取出来,并自动组织成一个 HTML 文档。使用 pydoc 模块生成 HTML 帮助文档的命令如下:
python -m pydoc -w 模块名
上面命令主要就是为 pydoc 模块额外指定了 -w 选项,该选项代表 write,表明输出 HTML 文档。例如,在 demo.py 所在当前目录下运行如下命令:
python -m pydoc -w demo
运行上面命令,可以看到系统生成“wrote demo.html” 提示信息。接下来可以在该目录下发现额外生成了一个 demo.html 文件,使用浏览器打开该文件,可以看到如图 1 所示的页面。图 1 使用 pydoc 生成的 HTML 文档
显然,该 HTML 页面与在控制台中查看的文档信息基本相同,区别仅仅在于这是一个 HTML 页面,我们可以拖动滑块来上、下滚动屏幕,查看更加方便。
不仅如此,pydoc 模块还可以查看当前操作系统中所有 Python 模块的 HTML 文档信息,有以下 2 种方式:
python -m pydoc -p 端口号
python -m pydoc -b
举个例子,执行如下命令:
python -m pydoc -p 8899
执行此命令,会看到如下输出信息:
Server ready at http://localhost:8899/
Server commands: [b]rowser, [q]uit
server>
图 2 pydoc查看所有Python模块
在该页面中,如果想查看某个模块的说明文档,直接点击该模块即可。
需要指明的一点是,pydoc 在显示所有 Python 模块时,会大致按照以下顺序进行显示:
- 显示 Python 内置的核心模块;
- 显示当前目录下的所有 Python 模块;
- 显示 PYTHONPATH 环境变量指定路径下包含的 Python 模块。
pydoc查找模块
pydoc 还提供了一个 -k 选项,该选项可以找到名称中包含执行字符串的所有模块。该选项的语法格式如下:python -m pydoc -k 模块名
例如,在 demo.py 所在目录下运行如下命令:python -m pydoc -k demo
可以看到如下输出信息:
......
demo
所有教程
- C语言入门
- C语言编译器
- C语言项目案例
- 数据结构
- C++
- STL
- C++11
- socket
- GCC
- GDB
- Makefile
- OpenCV
- Qt教程
- Unity 3D
- UE4
- 游戏引擎
- Python
- Python并发编程
- TensorFlow
- Django
- NumPy
- Linux
- Shell
- Java教程
- 设计模式
- Java Swing
- Servlet
- JSP教程
- Struts2
- Maven
- Spring
- Spring MVC
- Spring Boot
- Spring Cloud
- Hibernate
- Mybatis
- MySQL教程
- MySQL函数
- NoSQL
- Redis
- MongoDB
- HBase
- Go语言
- C#
- MATLAB
- JavaScript
- Bootstrap
- HTML
- CSS教程
- PHP
- 汇编语言
- TCP/IP
- vi命令
- Android教程
- 区块链
- Docker
- 大数据
- 云计算