我已经看到了几种标准,用于编写关于函数期望并在Python中返回的数据类型的注释.关于哪一个是最佳实践,是否达成共识？
http://www.python.org/dev/peps/pep-3107/中的新功能是否应该开始使用？
函数注释不是特定用途,它们可以用于任何事情.
可以编写工具来从注释中提取信息并执行任何操作,包括检查类型或生成文档.但是python本身对信息没有任何作用.您可以使用完全不同的目的,即提供将在参数上调用的函数或声明可能的返回值字符串.
注释可以是任何对象:
def somefunc(param1: "string annotation",
param2: 151631,
param3: any_object): -> "some information here":
你可以使用以下方法检索对象:
print (somefunc.func_annotations)
{'param1': "string annotation",
'param2': 151631,
'param3':
PEP提供的用例建议:
提供打字信息
类型检查
让IDE显示函数期望和返回的类型
函数重载/泛型函数
外语桥梁
适应
谓词逻辑功能
数据库查询映射
RPC参数编组
其他信息
参数和返回值的文档
由于函数注释语法太新,因此它实际上不用于任何生产工具.
我建议使用其他方法来记录.我使用epydoc生成我的文档,它可以从docstrings中读取参数输入信息:
def x_intercept(m, b):
"""
Return the x intercept of the line M{y=m*x+b}. The X{x intercept}
of a line is the point at which it crosses the x axis (M{y=0}).
This function can be used in conjuction with L{z_transform} to
find an arbitrary function's zeros.
@type m: number
@param m: The slope of the line.
@type b: number
@param b: The y intercept of the line. The X{y intercept} of a
line is the point at which it crosses the y axis (M{x=0}).
@rtype: number
@return: the x intercept of the line M{y=m*x+b}.
"""
return -b/m
这个例子来自epydoc的网站.它可以生成各种格式的文档,并可以从您的类和调用配置文件生成良好的图形.
如果使用epydoc生成API文档,则有三种选择.
Epytext.
ReStructuredText,RST.
JavaDoc表示法,看起来有点像epytext.
我推荐使用RST,因为它适用于sphinx,可生成包含API引用的整体文档套件.RST标记在此处定义.您可以指定的各种epydoc字段在此处定义.
例.
def someFunction( arg1, arg2 ):
"""Returns the average of *two* (and only two) arguments.
:param arg1: a numeric value
:type arg1: **any** numeric type
:param arg2: another numeric value
:type arg2: **any** numeric type
:return: mid-point (or arithmetic mean) between two values
:rtype: numeric type compatible with the args.
"""
return (arg1+arg2)/2
京公网安备 11010802040832号 | 京ICP备19059560号-6 