Python学习第四十五天—函数11(函数文档、类型注释、内省)

Python 3.12.1 (tags/v3.12.1:2305ca5, Dec  7 2023, 22:03:25) [MSC v.1937 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license()" for more information.
函数是一种代码封装的方法，对程序来说，函数就是一个程序组件，在函数的外部不需要关心函数内部执行的细节的，更需要关注的是函数的接口，以及执行后的结果，学会阅读开发手册和函数文档，使用help函数可以查看函数文档。
help(print)
Help on built-in function print in module builtins:

print(*args, sep=' ', end='\n', file=None, flush=False)
    Prints the values to a stream, or to sys.stdout by default.

    sep
      string inserted between values, default a space.
    end
      string appended after the last value, default a newline.
    file
      a file-like object (stream); defaults to the current sys.stdout.
    flush
      whether to forcibly flush the stream.
一、创建函数文档
def exchange(dollar ,rate=7.186):
    """
    功能：汇率转换，美元->人民币
    参数：
    -dollar 美元数量
    -rate 汇率，默认值7.186(2024-03-09 06:00)
    返回值：
    -人民币的数量
    """
    return dollar * rate

exchange(20)
143.72
二、类型注释
def times(s:str,n:int) -> str:      （希望传入s中的类型为字符串类型，传入到n参数为整数类型，并将返回一个字符串的类型值，这是Python的类型注释）
    return s * n

times("FishC",5)
'FishCFishCFishCFishCFishC'
times(5,5)     
25
作者希望你传入s中的是字符串，你却给到一个整数5，也行，因为这个:str只是一个类型注释，是给人看的，不是给机器看的，这可能是一种弱智的错误，时常会发生，所以在PEP3107文档中指出，在Python3从官方的角度出发，给大家定义这么一套统一的标准。来注释函数的参数和返回值，看下面的内容的写法。
def times(s:str="FishC",n:int=3) -> str:
    return s * n

times()                      （有默认参数，就直接调用）
'FishCFishCFishC'
def times(s:list,n:int=3) -> list:     （如果期待的参数是列表）
    return s * n

times([1,2,3])
[1, 2, 3, 1, 2, 3, 1, 2, 3]
def times(s:list[int],n:int=3) -> list:    （希望参数类型是一个整数列表）
    return s * n

def times(s:dict[str,int],n:int=3) -> list:   （键：值 类型，映射类型也可以使用这种方法，比如我们期待的字典的键是字符串，值是整数）
    return list(s.keys()) * n    （拿它的键乘以n）

times({"A":1,"B":2,"C":3})
['A', 'B', 'C', 'A', 'B', 'C', 'A', 'B', 'C']
三、内省
它是发生在内部，我们能够意识到的主观现象，在程序运行的时候，能够自我检测的一种机制，我们把它称之为内省，自省。Python是通过一些特殊的属性来实现内省的，比如：
我们想知道一个函数的名字，我们可以在程序运行的时候通过这个name来获取：
times.__name__    （注意：name前后是两个英文字符的下划线）
'times'
times.__annotations__       （通过annotations查看函数的类型注释）
{'s': dict[str, int], 'n': <class 'int'>, 'return': <class 'list'>}       （它以字典的方式打印出这个函数里的三个类型注释：两个参数和还有一个返回值）
最后查看函数文档，我们也可以使用：
exchange.__doc__         （这个阅读不友好）
'\n    功能：汇率转换，美元->人民币\n    参数：\n    -dollar 美元数量\n    -rate 汇率，默认值7.186(2024-03-09 06:00)\n    返回值：\n    -人民币的数量\n    '

print(exchange.__doc__)

    功能：汇率转换，美元->人民币
    参数：
    -dollar 美元数量
    -rate 汇率，默认值7.186(2024-03-09 06:00)
    返回值：
-人民币的数量

有关Python的内省还很多，在学后面的类和对象以及魔法方法，还有专门深刻的介绍。