Python Unit Test - 3 pydoc

为你的代码（code）文件写下足够的注释（comment）。

还是先把pydoc提前进行学习和了解。进行unit test，如果不知道unit的对像是如何实现（参数、结构、功能）的，该如何下手？

进行python学习过程中，每一个lib或是BIF学习多数时间都是通过help进行的，而这些完全依赖于python自身完善的docstring（__doc__ 和 pydoc），完备的comment（注释）。
进行单元测试的前提是要了解测试的函数和方法，知道基本的参数、限制条件、异常处理，才能有针对性的设计测试数据对被测对像进行验证（assert）。
一篇优秀的doc对学习者是绝对的福音，对使用者是绝对的天堂。就像java doc一样，python也有这样的python doc，详尽但缺少了点调用实例，做Unit或API测试足够了。

补充小点

• Unit Test，单元测试测什么？函数、类方法
• API Test和Unit Test一样吗？
  相似：都需要了解底层实出源代码，进行基础功能实现的测试；
  区别：API测试还需要进行应用层的测试，也就是API是暴露给用户进行调用（Application Protocal Interface，应用程序接口，从名称中也可以反映）。
  More：其实在同一系统中不同模块间的调用也是interface（接口），这里调用的方法需要进行单元测试（白盒测试），因此在系统层面会有集成测试（黑盒测试）。也许这就是C/S和B/S设计的区别。
• Module（独立的python文件），Package（python module文件集合/目录

1. pydoc
    pydoc是一个独立的模块，因此使用时需要import（当然也可以通过python -m 执行），用来生成python模块的文档信息，并通过html文件形式输出；对于package使用pydoc会生成完成的文件目标。所有的文件均可以通过web访问。
    python中的module、class、function、method都会从其__doc__中获得docstring对像，或者从其文件组成块（block）的最上面的注释（comment）中生成pydoc.
    使用help()可以显示与pydoc相同的对像说明。

2. 示例代码

"""
This is python Modulce / File doc DESC.   # file: pydc.py
"""

def funcdoc():
    """
    This is python Function doc DESC.
    """
    print("function")

class classdoc:
    """
    This is python Class doc DESC.
    """

    def methoddoc(self):
        """
        This is python Method doc DESC.
        """
        print("method")

if __name__ == "__main__":
    funcdoc()

    cla = classdoc()
    cla.methoddoc()

3. doc显示

• python __doc__ 

>>> import pydc
>>> from pydc import funcdoc
>>> from pydc import classdoc

>>> pydc.__doc__       
'\nThis is python Modulce / File doc DESC.\n'

>>> funcdoc.__doc__    
'\n    This is python Function doc DESC.\n    '

>>> classdoc.__doc__

>>> classdoc.methoddoc.__doc__
'\n        This is python Method doc DESC.\n        '

• Help doc

>>> import pydc
>>> help(pydc)
Help on module pydc:

NAME
    pydc - This is python Modulce / File doc DESC.

CLASSES
    builtins.object
        classdoc
    
    class classdoc(builtins.object)
     |  This is python Class doc DESC.
     |  
     |  Methods defined here:
     |  
     |  methoddoc(self)
     |      This is python Method doc DESC.
     |  
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |  
     |  __dict__
     |      dictionary for instance variables (if defined)
     |  
     |  __weakref__
     |      list of weak references to the object (if defined)

FUNCTIONS
    funcdoc()
        This is python Function doc DESC.

• pydoc console显示

>python -m pydoc pydc
Help on module pydc:

NAME
    pydc - This is python Modulce / File doc DESC.

CLASSES
    builtins.object
        classdoc

    class classdoc(builtins.object)
     |  This is python Class doc DESC.
     |
     |  Methods defined here:
     |
     |  methoddoc(self)
     |      This is python Method doc DESC.
     |
     |  ----------------------------------------------------------------------
     |  Data descriptors defined here:
     |
     |  __dict__
     |      dictionary for instance variables (if defined)
     |
     |  __weakref__
     |      list of weak references to the object (if defined)

FUNCTIONS
    funcdoc()
        This is python Function doc DESC.

• pydoc html显示

python -m pydoc -w pydc      # 生成 web 文件
wrote pydc.html

• pydoc web显示 -- 显示当前文件夹下python文件的doc 和 python BIF的doc

>python -m pydoc -n localhost -p 3000 pydc
Server ready at http://localhost:3000/
Server commands: [b]rowser, [q]uit
server> b