函数-函数文档

BrightXiong

>>> # 使用 help() 函数，我们可以快速查看到一个函数的使用文档：
>>> help(print)
Help on built-in function print in module builtins:

print(...)
    print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
   
    Prints the values to a stream, or to sys.stdout by default.
    Optional keyword arguments:
    file:  a file-like object (stream); defaults to the current sys.stdout.
    sep:   string inserted between values, default a space.
    end:   string appended after the last value, default a newline.
    flush: whether to forcibly flush the stream.

>>> # 创建函数文档非常简单，使用字符串就可以了，
>>> def exchange(dollar, rate=6.32):
...         """
...         功能：汇率转换，美元 -> 人民币
...         参数：
...         - dollar 美元数量
...         - rate 汇率，默认值6.32 (2022-03-08)
...         返回值：
...         - 人民币数量
...         """
...         return dollar * rate
...
>>> exchange(20)
126.4
>>> help(exchange)
Help on function exchange in module __main__:

exchange(dollar, rate=6.32)
    功能：汇率转换，美元 -> 人民币
    参数：
    - dollar 美元数量
    - rate 汇率，默认值6.32 (2022-03-08)
    返回值：
    - 人民币数量

>>> # Python 的类型注释
>>> def times(s:str, n:int) -> str:
...         return s * n  
...
>>> # 上面代码表示该函数的作者，希望调用者传入到 s 参数的是字符串类型，传入到 n 参数的是整数类型，最后还告诉我们函数将会返回一个字符串类型的返回值：
>>> times("FishC", 3)
'FishCFishCFishC'
>>> times(5,3)
15

>>> # 只是类型注释，是给人看的，不是给机器看的
>>> # 如果需要使用默认参数，那么类型注释可以这么写：
>>> def times(s:str = "Fishc", n:int = 2) -> str:
...         return s * n
...
>>> times()
'FishcFishc'
>>> # 如果期望的参数类型是列表
>>> def times(s:list, n:int=5) -> list:
...         return s * n
...
>>> times([1, 2, 3], 3)
[1, 2, 3, 1, 2, 3, 1, 2, 3]
>>> # 比如期望参数类型是一个整数列表（也就是列表中所有的元素都是整数）
>>> def times(s:list[int], n:int = 5) ->list:
...         return s * n
...
>>> # 映射类型也可以使用这种方法，比如我们期望字典的键是字符串，值是整数，可以这么写：
>>> def times(s:dict[str, int], n:int = 5) -> list:
...         return list(s.keys()) * n
...
>>> times({'A':1, 'B':2, 'C':3}, 3)
['A', 'B', 'C', 'A', 'B', 'C', 'A', 'B', 'C']
>>> # Python 通过一些特殊的属性来实现内省，比如我们想知道一个函数的名字，可以使用 __name__：
>>> times.__name__
'times'
>>> # 使用 ___annotations__ 查看函数的类型注释：
>>> times.__annotations__
{'s': dict[str, int], 'n': <class 'int'>, 'return': <class 'list'>}

>>> # 查看函数文档，可以使用 __doc__：
>>> exchange.__doc__
'\n\t功能：汇率转换，美元 -> 人民币\n\t参数：\n\t- dollar 美元数量\n\t- rate 汇率，默认值6.32 (2022-03-08)\n\t返回值：\n\t- 人民币数量\n\t'
>>> print(exchange.__doc__)

        功能：汇率转换，美元 -> 人民币
        参数：
        - dollar 美元数量
        - rate 汇率，默认值6.32 (2022-03-08)
        返回值：
        - 人民币数量
       
>>>

未泯

match123_xbd

经典