（小甲鱼python）函数笔记合集七 函数(XI)总结 python函数的函数文档、类型注释、内省详解

一、基础复习

1. 函数的基本用法 创建和调用函数 函数的形参与实参等等
2. 函数的几种参数 位置参数、关键字参数、默认参数等
3. 函数的收集参数*args **args 解包参数详解
4. 函数中参数的作用域 局部作用域 全局作用域 global语句 嵌套函数 nonlocal语句等详解
5. 函数的闭包（工厂函数）
6. lambda()函数表达式、map()、filter()函数详解
7. 生成器的定义、使用和产生生成器的两种方法详解
8. 函数的递归、递归和迭代的区别详解
9. python实现汉诺塔详解(主要通过函数的递归实现)

二、函数文档、类型注释、内省

1.函数文档

在python中，使用help()函数，可以快速查看一个函数的使用文档了

函数文档的作用： 相当于函数的说明书
例1：

>>> 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.

例2：函数文档

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

>>> exchange(20)
126.4

通过help()函数查看文档

>>> help(exchange)
Help on function exchange in module __main__:

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

>>> 

2.类型注释

例3：代码返回字符串

>>> def times(s:str,n:int) ->str:
	return s * n

>>> times("FishC",5)  # 第一个字符串打印5遍。
'FishCFishCFishCFishCFishC'
>>> 
>>> times(5,5) # 这里传入整数也是可以的，  :str是给人看的，不是给机器看的。
25

代码注释：希望调用者传入到s参数中的类型是字符串类型，传入到n参数是整数类型，函数将返回一个字符串类型的返回值。

>>> def times(s:str="FishC",n:int=3) ->str:
	return s * n

>>> times()
'FishCFishCFishC'
>>> 

例4：代码返回列表。

>>> def times(s:list,n:int=3) ->list:
	return s * n

>>> times([1,2,3])
[1, 2, 3, 1, 2, 3, 1, 2, 3]
>>> 

例5：代码返回字典（本人python版本为3.7.3，代码会报错，python3.9版本可以正常运行。）

>>> def times(s:dict[str,int],n:int=3) ->list:
	return list(s.keys()) * n

>>> 
>>> times({'A':1,'B':2,'C':3})
['A','B','C','A','B','C','A','B','C']

3.内省

内省：指在程序运行的时候能够进行自我检测的一种机制，称之为内省或者自省。

例6：想知道函数的名字可以通过name来获取，前后是两个下横线’__’
代码注释：

• name： 返回函数的名字
• annotations：查看函数的类型注释
• doc：查看文档

>>> times.__name__  #返回函数的名字
'times'
>>> 
>>> times.__annotations__  # 用annotations查看函数的类型注释，以字典的方式打印函数里面的三个类型注释
{'s': <class 'list'>, 'n': <class 'int'>, 'return': <class 'list'>}
>>> exchange.__doc__  # 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__) # print会把转义字符给解析出来

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

课后题：
1.函数文档必须要放在函数体的开头吗？
答：是的。
解析：下面这样写是没有用的。

>>> def exchange(dollor, rage=6.32):
...     pass
...     """
...     功能：汇率转换，美元 -> 人民币
...     参数：
...     - dollar 美元数量
...     - rate 汇率，默认值 6.32（2022-03-08）
...     返回值：
...     - 人民币数量
...     ""
...     return dollar * rate
...
>>> help(exchange)
Help on function exchange in module __main__:

exchange(dollor, rage=6.32)

2.函数文档通常是保存在哪里？
答：当然是保存在函数中啦~
解析：具体地说，是保存在函数中的 doc 中，所以我们才能够在程序运行的时候使用 doc 进行自省。

>>> exchange.__doc__
'\n\t功能：汇率转换，美元 -> 人民币\n\t参数：\n\t- dollar 美元数量\n\t- rate 汇率，默认值 6.32（2022-03-07）\n\t返回值：\n\t- 人民币数量\n\t'

3.请问下面代码会打印什么呢？

>>> def times(s:str, n:int) -> str:
...     return s * n
...
>>> times(5, "FishC")
# 请问这里会打印什么内容？

答：

>>> times(5, "FishC")
'FishCFishCFishCFishCFishC'

解析：类型注释仅是作为函数作者对程序员的提醒，并不会起到真正的限制作用。
4.请问下面代码会打印什么呢？

>>> def foo(a: 'x', b: 5 + 6, c: list) -> max(2, 9):
>>>     pass
...
>>> foo.__annotations__
# 请问这里会打印什么内容？

答：

>>> foo.__annotations__
{'a': 'x', 'b': 11, 'c': <class 'list'>, 'return': 9}

5.如果我们自己定义一个函数 times，期望用户传入的两个参数分别是 整数型列表 和 整数，那么请问相应的类型注释应该怎么写？
答：

>>> def times(s:list[int], n:int = 5) -> list[int]:
...     return s * n

6.如果我们自己定义一个函数 times，期望用户传入的两个参数分别是 字典（其中键为字符串，值为浮点数）和 整数，那么请问相应的类型注释应该怎么写？
答：

>>> def times(s:dict[str, float], n:int = 5) -> list[str]:
...     return list(s.keys()) * n
...

题目来自小甲鱼函数XI