善用docstring和annotations配合pycharm自动提示让python函数使用更便捷

在使用别人定义的函数的时候，大多数时候我们不关心函数具体实现，而只想知道每个参数以及返回值的类型和说明。令人欣喜的就是pycharm已经集成了参数类型提示和说明的快捷键功能，不过这需要被调用的函数在定义的时候按照一定的格式去标注docstring和annotations。下面我们就一起来了解下这些都是啥，让我们以后自己定义的函数也能使用起来更便捷。

我是T型人小付，一位坚持终身学习的互联网从业者。喜欢我的博客欢迎在csdn上关注我，如果有问题欢迎在底下的评论区交流，谢谢。

什么是docstring？

docstring是一个没有赋值给任何变量的string，其被用于类（class），模块（module），函数（function）或者方法（method）的定义中。一个对象的docstring出现在该对象定义的最前面，内容是对该对象的功能或者参数等的描述信息，通常用三引号表示。docstring的获取可以通过对象的__doc__属性。

下面是单行的docstring演示

def square(a):
    '''Returned argument a is squared.'''
    return a**a

print (square.__doc__)

Returned argument a is squared.

下面是多行的docstring演示

def some_function(argument1):
    """Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

   """

    return argument1

虽然说在docstring里面写什么内容都无所谓，不过为了便于pycharm的自动提示，后面我们会按照PEP规定的格式去写。

顺便一提的是python中的注释用#来表示，其也可以起到解释说明的作用，但是就没有pycharm的自动提示了。

什么是annotations?

annotations用在函数的定义中，和docstring一样也是对函数的描述信息，不影响函数功能的实现。但是annotation着重于描述函数的参数和返回值的类型或者描述。

其格式类似下面这样

def func(x:'annotating x', y: 'annotating y', z: int) -> float:
	print(x + y + z)

在每个参数后面用冒号连接一个数据类型或者是字符串，做为该参数的annotation。在参数括号后用箭头接一个数据类型或者字符串做为返回值的annotation，最后用冒号接真正的函数定义内容。

获取函数的annotations可以用__annotations__属性，例如

print(func.__annotations__)

{'x': 'annotating x', 'y': 'annotating y', 'z': <class 'int'>, 'return': <class 'float'>}

当然pycharm中也会有自动提示，不需要我们真正去用该属性去查看。

pycharm自动提示

下面分参数类型和函数说明两部分来看看pycharm的操作和函数所需的书写规范

函数参数类型提示

在pycharm中有个快捷键是Ctrl+p，当光标在函数输入参数的地方时按该快捷键可以提示函数的参数名和类型，但是前提是函数定义是用annotation声明了类型。

例如，定义函数如下

def func1(para1:int,para2:str,para3:float)->list:
    return para1+para2+para3

在使用该函数的时候，如果按下Ctrl+p，效果如下

可以看到快捷键显示了函数的

• 参数个数
• 参数类型
• 当前传递参数

基本上结合参数名和参数类型就能让我们对当前参数有个比较有意义的了解了，这个快捷键只要是在小括号内就可以使用。

假如函数的annotation并不是参数类型，而是字符串，就不能在这里显示了，例如函数定义如下

def func1(para1:int,para2:'second parameter',para3:float)->list:
    return para1+para2+para3

可以看到第二个参数的annotation变成了字符串，那么再使用快捷键效果如下

第二个参数的类型提示没了。

所以为了方便显示参数类型，函数参数的annotation建议使用数据类型，而函数的返回值数据类型和说明字符串则无所谓。

函数说明提示

那么如果想看函数的描述信息又该如何呢？首先从函数的定义看起。

我们尝试在pycharm中给刚才的函数func1添加docstring

def func1(para1:int,para2:'second parameter',para3:float)->list:
    '''
    
    :param para1: 
    :param para2: 
    :param para3: 
    :return: 
    '''
    return para1+para2+para3

会发现pycharm自动帮我们规定好了格式，其中包括3个参数的说明和返回值的说明。我们在冒号后面补充完整

def func1(para1:int,para2:'second parameter',para3:float)->list:
    '''
    
    :param para1: this is 1st parameter
    :param para2: hello from 2nd parameter
    :param para3: the 3rd parameter says hi
    :return: I am the return value
    '''
    return para1+para2+para3

然后在引用该函数的时候用快捷键Ctrl+q就能看到这些信息了，如下

可以看到这里不仅显示了刚才我们输入的内容，同时也将函数的annotation也一起显示了出来。

下面我们实际传递几个参数进来看看

print(func1(1,2,3))

结果为

6

所以上面所说的都是函数的一些描述信息，包括数据类型。并不构成函数使用中的强制约束，毕竟python还是动态语言嘛。

总结

通过以上的结果可以总结下以后自己定义函数的时候可以遵循的规则

• 在函数的参数定义那里，使用annotation的方式规定参数和返回值数据类型
• 在函数的docstring里面用pycharm规定好的格式，详细描述下每个参数以及返回值的含义
• 快捷键Ctrl+p和Ctrl+q分别用来快速查看当前参数信息和查看完整函数说明信息

再次强调，不管是annotation或是docstring都只是描述性信息，不构成任何强制约束。