Python __doc__属性：查看文档

在使用 dir() 函数和 __all__ 变量的基础上，虽然我们能知晓指定模块（或包）中所有可用的成员（变量、函数和类），比如：

import string
print(string.__all__)

程序执行结果为：

['ascii_letters', 'ascii_lowercase', 'ascii_uppercase', 'capwords', 'digits', 'hexdigits', 'octdigits', 
'printable', 'punctuation', 'whitespace', 'Formatter', 'Template']

但对于以上的输出结果，对于不熟悉 string 模块的用户，还是不清楚这些名称分别表示的是什么意思，更不清楚各个成员有什么功能。
针对这种情况，我们可以使用 help() 函数来获取指定成员（甚至是该模块）的帮助信息。以前面章节创建的 my_package 包为例，该包中包含 __init__.py 、module1.py 和 module2.py 这 3 个模块，它们各自包含的内容分别如下所示：

#!/usr/bin/env python
# -*- coding: utf-8 -*-
__author__ = 'tian'
__data__ = '2024/2/5 11:28'
# software: PyCharm


# __init__.py 文件总的内容
from my_package.module1 import  *
from my_package.module2 import  *

#module1.py 中的内容
def display(arc):
    """
    直接输出指定的参数
    Parameters
    ----------
    arc

    Returns
    -------

    """
    print(arc)

module2.py
class PLanguage:
    """
    PLanguage是一个类，其包含
    display()方法
    """

    def display(self):
        print("https://www.cnblogs.com/qingchengzi")

现在，我们先借助 dir() 函数，查看 my_package 包中有多少可供我们调用的成员。

import  my_package

print([e for e in dir(my_package) if not e.startswith("_")])

程序输出结果：

['PLanguage', 'display', 'module1', 'module2']

通过此输出结果可以得知，在 my_package 包中，有以上 4 个成员可供我们使用。接下来，我们使用 help() 函数来查看这些成员的具体含义（以 module1 为例）：

import  my_package
help(my_package.module1)

输出结果：

Help on module my_package.module1 in my_package:
NAME
    my_package.module1 - # -*- coding: utf-8 -*-

FUNCTIONS
    display(arc)
        直接输出指定的参数
        Parameters
        ----------
        arc
        
        Returns
        -------

DATA
    __data__ = '2024/2/5 11:28'

AUTHOR
    tian

FILE
    e:\workbook\python平时练习学习目录\my_package\module1.py

通过输出结果可以得知，module1 实际上是一个模块文件，其包含 display() 函数，该函数的功能是直接输出指定的 arc 参数。同时，还显示出了该模块具体的存储位置。
当然，有兴趣的读者还可以尝试运行如下几段代码：

import  my_package
help(my_package.module2.PLanguage)

程序输出：

Help on class PLanguage in module my_package.module2:

class PLanguage(builtins.object)
 |  PLanguage是一个类，其包含
 |  display()方法
 |  
 |  Methods defined here:
 |  
 |  display(self)
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors defined here:
 |  
 |  __dict__
 |      dictionary for instance variables (if defined)
 |  
 |  __weakref__
 |      list of weak references to the object (if defined)

值得一提的是，之所以我们可以使用 help() 函数查看具体成员的信息，是因为该成员本身就包含表示自身身份的说明文档（本质是字符串，位于该成员内部开头的位置）。前面讲过，无论是函数还是类，都可以使用 __doc__ 属性获取它们的说明文档，模块也不例外。

以 my_package 包 module1 模块中的 display() 函数为例，我们尝试用 __doc__ 变量获取其说明文档：

import  my_package

help(my_package.module1.display.__doc__)

程序执行结果：

No Python documentation found for '直接输出指定的参数\n    Parameters\n    ----------\n    arc\n\n    Returns\n    -------'.
Use help() to get the interactive help utility.
Use help(str) for help on the str class.

其实，help() 函数底层也是借助 __doc__ 属性实现的。
那么，如果使用 help() 函数或者 __doc__ 属性，仍然无法满足我们的需求，还可以使用以下 2 种方法：
调用 __file__ 属性，查看该模块或者包文件的具体存储位置，直接查看其源代码（后续章节或详细介绍）；
对于非自定义的模块或者包，可以查阅 Python 库的参考文档 https://docs.python.org/3/library/index.html。