函数注释语法

函数注释包括：

参数注释：以冒号（:）标记

返回值注释：以 -> 标记

语法结构大体如下：

1、def foo(a: expression, b: expression = 5) -> expression:

2、 ...

在伪语法中，参数看起来像：identifier [: expression] [= expression]。也就是说，参数注释总在其默认值之前。当函数定义被执行时，所有的注释表达式都被求值，就像默认值一样。

参数列表后面可以跟一个 -> 和一个 Python 表达式。与参数的注释一样，在执行函数定义时，将对该表达式求值。

单个注释

函数注释可以包含类型、帮助字符串，以及其他更多信息。

来看一个例子，有一个函数 sum()，接受三个参数 a、b、c，并返回它们的和。

1、>>> def sum(a, b: int, c: 'The default value is 5' = 5) -> float:

2、...     return a + b + c

3、... 

4、>>> 

其中，第一个参数 a 没有注释，第二个参数 b 带有类型为 int 的注释，第三个参数 c 带有一个帮助字符串注释并且拥有默认值，返回值用类型 float 来注释。

调用 sum() 两次，一次使用 int，一次使用字符串：

1、>>> sum(1, 2)

2、8

3、>>> 

4、>>> sum('Hello', ', ', 'Python!')

5、'Hello, Python!'

显然，注释对函数的执行没有任何影响。在这两种情况下，sum() 都做了正确的事情，只不过注释被忽略了而已。

访问函数注释

函数对象有一个名为 __annotations__ 的属性，它是一个映射（dict），用于将每个参数名（key）映射到其相关的注释（value）。

注意： 映射中有一个特殊的 key，叫做“return”，仅当为函数的返回值提供注释时，才会显示该 key。

回到上述示例，并检查它的注释：

1、>>> type(sum.__annotations__)

2、

3、>>>

4、>>> sum.__annotations__

5、{'c': 'The default value is 5', 'return': , 'b': }

之所以选择 “return”，是因为它不会与任何参数名冲突。“return”是 Python 中的一个关键字，任何使用“return”作为参数名的尝试都会引发 SyntaxError。

多个注释

倘若，函数注释中要同时包含类型和帮助字符串，怎么办？很容易，可以使用具有两个 key（例如：type 和 help）的 dict：

1、>>> def div(a: dict(type=float, help='the dividend'),

2、...         b: dict(type=float, help='the divisor (must be different than 0)')

3、...     ) -> dict(type=float, help='the result of dividing a by b'):

4、...     """Divide a by b"""

5、. ..     return a / b

6、... 

7、>>> 

调用 div()：

1、>>> div.__annotations__

2、{'a': {'type': , 'help': 'the dividend'}, 'return': {'type': , 'help': 'the result of dividing a by b'}, 'b': {'type': , 'help': 'the divisor (must be different than 0)'}}

3、>>>

4、>>> div(5, 2)

5、2.5

注意： 如果要包含更多的注释（示例中是 2 个），可以在 dict 中包含更多的 key:value 对。

动态注释

__annotations__ 是函数的一个属性，类型为 dict。由于 dict 是可变的，这意味着，可以在程序运行时动态地修改注释。

假设，想知道是否使用了参数的默认值，或者想把所有的返回值都加起来。

>>> def sum(a, b) -> 0:

...     result = a + b

...     sum.__annotations__['return'] += result

...     return result

... 

>>> sum.__annotations__['return']

0

>>> 

>>> sum(1, 2)

3

>>> sum.__annotations__['return']

3

>>> 

>>> sum(3, 4)

7

>>> sum.__annotations__['return']

10

pycharm

函数中输入 """ 3个双引号，然后按回车，

自动出现

1.

文件添加方式: pycharm提供了一个在新建文件自动生成文件头注释的功能,可以实现自动生成运行环境,作者、日期等必要信息,使用比较方便,配置十分简单。 #!C:\pythonCode # -*- coding:utf-...

2.

自动生成函数注释,包括参数和返回值。使用方法,函数定义时,直接输入三个双引号后回车。 也可以将光标放在方法上,会弹出一个小灯,选择第一个就好了。

pycharm

函数中输入 """ 3个双引号，然后按回车，

自动出现

类似这样， 写所需的注释就可以了

如果是参数注释：以冒号（:）标记

函数注释是Python 3的一项功能,可让您向函数参数添加任意元数据并返回值。

函数定义

　　　　函数定义的简单规则：

函数代码块以def关键词开头，后接函数标识符名称和圆括号()，任何传入参数和自变量必须放在圆括号中间
函数内容以冒号起始，并且缩进
若有返回值，Return[expression] 结束函数；不带return 表达式相当于返回None

　　　　函数通常使用三个单引号  '''...'''   来注释说明函数；函数体内容不可为空，可用 pass 来表示空语句；以下几个为简单的函数示例：

 1 ''' some basic functions ''' 2 def func1():                    # 函数无传入参数 3     print("func1")              # 无return值 4 func1()                         # 函数调用 5  6 def func2(): 7     return("func2")             # return 字符串 "func2" 8 print(func2()) 9 10 def func3(a,b):                 # 需传两个参数11     print("a+b = %d" %(a+b))    # print表达式，无return12 func3(3,4)13 14 def func4(a,b):                 # 需传两个参数15     return (a+b)                # return a+b 的值16 print(func4(4,3))

　　函数调用

　　　　定义一个函数只给了函数一个名称，指定了函数里包含的参数，和代码块结构。

　　　　这个函数的基本结构完成以后，你可以通过另一个函数调用执行，也可以直接从Python提示符执行。

　　　　上面的例子中  func1() 就是无参数函数的调用； func3(3,4) 为有参数函数的调用

　　深入函数定义

　　　　默认参数值

　　　　　　最常用的一种形式是为一个或过个参数指定默认值。调用时，可不传入有默认值的参数。参考下例：

 1 ''' advanced: 简单询问框 ''' 2 def ask_ok(hint, retries=4, complaint='Yes or no, please!'):    # 仅有hint是必须要传入的，retries 和 complaint 均有默认值 3     while True: 4         u = input(hint) 5         if u in ('y','ye','yes'):             # in 的用法；若用户回答在('y','ye','yes') return True  6             return True 7         if u in ('n','no','nop','nope'):      # 若用户回答在('n','no','nop','nope') return False 8             return False 9         retries = retries -1                  # 若用户输入不在之前所列，可重试，重试次数-110         if retries <= 0 :                     # 若超出重试次数，raise自定义Error11             raise IOError('refusenik user')12         print(complaint)                      # 若用户输入不在之前所列，提示 complaint 信息13 14 result1 = ask_ok("Yes or No?")                # 只给必要的参数值hint，可尝试输入'y' 'no' 等；输入其他的如 'x' 超过4次15 print(result1)                                # 查看return的值16 17 # result2 = ask_ok("Yes or No?",2)            # 给出retries=2，尝试输入其他的如 'x' 超过2次        18 19 # result3 = ask_ok("Yes or No?",'Y or N?')    # 不可只省略第二个参数，若尝试输入其他的如 'x'，会报错20 21 # result4 = ask_ok("Yes or No?",3,'Y or N?')  # 给出所有的参数，可尝试输入'y' 'no' 等；输入其他的如 'x' 超过3次22 # print(result4)

　　　　 　　注意：默认值是在函数定义作用域被解析的，如下所示

1 '''默认值是在函数定义作用域被解析的'''2 i = 53 def print_i(var=i):4     print(var)5 i = 66 print_i()        # 输出为5

 　　　　　　重要警告：默认值只被赋值一次。这使得当默认值是可变对象时会有所不同，如列表、字典或大多数类的实例。如下例，函数在后续调用过程中会累积之前传给它的参数。

 1 ''' 默认值只被赋值一次。这使得当默认值是可变对象时会有所不同，如列表、字典或大多数类的实例。 2     函数在后续调用过程中会累积之前传给它的参数。 3 ''' 4 def append_L(a,L=[]):         # 必须传参a，L不必须，为list，默认为空 5     L.append(a) 6     return L 7 print(append_L(1))            # 给出参数 a=1, 此时 L 已变为 [1] 8 print(append_L(2))            # 输出 [1,2] 9 print(append_L(3))            # 输出 [1,2,3]10 11 ''' L缺省时，做改变L，而不是累积值，可像下方这样定义函数 '''12 def change_L(a,L=None):13     if L is None:14         L = []15     L.append(a)16     return L17 print(change_L(1))            # 给出参数 a=1, L为None18 print(change_L(2))            # 给出参数 a=2, L为None    输出 [2]19 print(change_L(3,[0]))        # 给出参数 a=1, L=[0]    输出 [0,3]

　　　　关键字参数

　　　　　　上面的例子中，调用函数给出的参数都是根据定义的顺序来的。函数还可以根据 关键字函数 的形式来调用，参见下面的示例：

1 def add(a,b):                    
2     return (a+b)                
3 print(add(b=9,a=2))                # 关键字参数定义 b=9 , a=2 与传参顺序无关4 # print(add(b=9,2))                # 会报错

　　　　可变参数列表

　　　　　　可以让函数调用可变个数的参数（不常用），这些参数被包装进一个元组。在这些可变个数的参数之前，可以有零到多个普通的参数。

　　　　　　可变参数的表示为在其参数名前加*，如*args；参见下面的示例：

1 def join_bysep(*strs,sep):        # strs 可为多个参数2     return sep.join(strs)         # 字符串连接函数 sep.join(str)3 print(join_bysep("red","blue","green",sep=" "))4 print(join_bysep("red","blue",sep=","))5 print(join_bysep("red",sep=","))6 print(join_bysep(sep=","))        # 无strs传参，为一空的字符串

函数注释是Python 3的一项功能,可让您向函数参数添加任意元数据并返回值。