Python学习笔记（十四）- 文档间奏（The Documentation Interlude）

1.什么时候应该使用文档字符串（documentation strings）而不是井号注释（hash-mark comments）？
答：文档字符串（docstrings）被认为是大型函数文档的最佳选择，在你的代码中描述了模块，函数，类和方法的使用。井号注释如今最好限于较小规模的文档，那些有关于代码中战略要点的神秘表达式（expression）或语句（statement）。这是部分原因是因为文档字符串在源文件（source files）中更容易找到，但也因为它们可以由 PyDoc 系统提取和显示。

 

2.列举三种查看文档字符串的方法。
答：您可以通过打印对象的 __doc__ 属性，将其传递给 PyDoc 的 help 函数，以及通过选择 PyDoc 基于 HTML 的用户界面中的模块（Python 3.2及更早版本中的 -g GUI客户端模式或 -b Python 3.2及更高版本中的浏览器模式，从 3.3 开始需要）来查看文档字符串。两者都运行一个客户端/服务器系统，在弹出的 Web 浏览器中显示文档。还可以运行 PyDoc 将模块的文档保存在 HTML文件中，以便以后查看或打印。

其中一个例子：（假设在系统命令行中）

C:\code>python -m pydoc -b

Sever ready at http://localhost:XXXXXX

Sever commands:[b]rowser, [q]uit

Sever>q

Sever Stopped

 

3.如何获取对象中可用属性的列表？
答：内置 dir(X) 函数返回依赖于任何对象的所有属性的列表。表格的列表推导式 [a for a dir(X) if a.startswith('__')] 可用于过滤掉带有 __ 前导双下划线的内部名称（我们将学习如何将其包含在函数中）本书的下一部分，以便于使用）。

 

4.如何获得计算机上所有可用模块的列表？
答：在 Python 3.2及更早版本中，您可以运行 PyDoc GUI 界面，并选择“打开浏览器”;这将打开一个网页，其中包含程序可用的每个模块的链接。此 GUI 模式不再适用于 Python 3.3。在Python 3.2及更高版本中，通过使用 -b 命令行开关运行 PyDoc 的较新的全浏览器模式，您可以获得相同的功能; 在此更新模式下，在web浏览器中显示的顶层开始页具有相同的索引页，其中列出了所有可用模块。（说的好像就上第二条后面的例子）

 

5.在这本书之后你应该购买哪本Python书？
答：当然，我的 （说真的，现在有几百本书了;前言列出了一些推荐的后续书籍，无论是参考还是应用教程，你都应该浏览适合你需求的书籍。）

 

标注：转载《Learning Python 5th Edition》[奥莱理]

1. When should you use documentation strings instead of hash-mark comments?
2. Name three ways you can view documentation strings.
3. How can you obtain a list of the available attributes in an object?
4. How can you get a list of all available modules on your computer?
5. Which Python book should you purchase after this one?

1. Documentation strings (docstrings) are considered best for larger, functional documentation, describing the use of modules, functions, classes, and methods in your code. Hash-mark comments are today best limited to smaller-scale documentation about arcane expressions or statements at strategic points on your code. This is partly because docstrings are easier to find in a source file, but also because they can be extracted and displayed by the PyDoc system.
2. You can see docstrings by printing an object’s __doc__ attribute, by passing it to PyDoc’s help function, and by selecting modules in PyDoc’s HTML-based user interfaces—either the -g GUI client mode in Python 3.2 and earlier, or the -b all-browser mode in Python 3.2 and later (and required as of 3.3). Both run a client/ server system that displays documentation in a popped-up web browser. PyDoc can also be run to save a module’s documentation in an HTML file for later viewing or printing.
3. The built-in dir(X) function returns a list of all the attributes attached to any object. A list comprehension of the form [a for a in dir(X) if not a.starts with('__')] can be used to filter out internals names with underscores (we’ll learn how to wrap this in a function in the next part of the book to make it easier to use).
4. In Python 3.2 and earlier, you can run the PyDoc GUI interface, and select “open browser”; this opens a web page containing a link to every module available to your programs. This GUI mode no longer works as of Python 3.3. In Python 3.2 and later, you get the same functionality by running PyDoc’s newer all-browser mode with a -b command-line switch; the top-level start page displayed in a web browser in this newer mode has the same index page listing all available modules.
5. Mine, of course. (Seriously, there are hundreds today; the preface lists a few recommended follow-up books, both for reference and for application tutorials, and you should browse for books that fit your needs.)