Python

在实际生产中，机器学习工作现在看起来，白天像是个算法工程师的活，晚上就变成运维+测试了。Python 一直以来也都受到测试工程师和运维工程师的偏爱，下面是几个经典的注释活用case。

用注释写单元测试:doctest

单元测试是代码开发环节必不可少的一环，对于Bug定位和代码质量而言是非常重要的。现在最广为人知的单元测试框架就是Unittest，它借鉴了Java中成熟的单元测试框架的JUnit。即使像Django还对这个框架有特殊的支持，然而在实现Unittest的时候会感觉确实比较啰嗦，setup，teardown…在维护单元测试的时候很多时候感觉力不从心。

一个巧妙的方式可以是通过doctest，用docstring注释的方式来完成单元测试，由于每个方法def下面都先跟着一段测试用例，然后紧跟着就是代码正文，这样一来很方便我们测试现有代码的质量，另一方面又便于修改。

举个例子：

deffactorial(n):

"""Return the factorial of n, an exact integer >= 0.

>>> [factorial(n) for n in range(6)]

[1, 1, 2, 6, 24, 120]

>>> factorial(30)

265252859812191058636308480000000

>>> factorial(-1)

Traceback (most recent call last):

...

ValueError: n must be >= 0

Factorials of floats are OK, but the float must be an exact integer:

>>> factorial(30.1)

Traceback (most recent call last):

...

ValueError: n must be exact integer

>>> factorial(30.0)

265252859812191058636308480000000

It must also not be ridiculously large:

>>> factorial(1e100)

Traceback (most recent call last):

...

OverflowError: n too large

"""

importmath

ifnotn>=0:

raiseValueError("n must be >= 0")

ifmath.floor(n)!=n:

raiseValueError("n must be exact integer")

ifn+1==n:# catch a value like 1e300

raiseOverflowError("n too large")

result=1

factor=2

whilefactor<=n:

result*=factor

factor+=1

returnresult

if__name__=="__main__":

importdoctest

doctest.testmod()

deffactorial(n):

"""Return the factorial of n, an exact integer >= 0.

>>> [factorial(n) for n in range(6)]

[1, 1, 2, 6, 24, 120]

>>> factorial(30)

265252859812191058636308480000000

>>> factorial(-1)

Traceback (most recent call last):

...

ValueError: n must be >= 0

Factorials of floats are OK, but the float must be an exact integer:

>>> factorial(30.1)

Traceback (most recent call last):

...

ValueError: n must be exact integer

>>> factorial(30.0)

265252859812191058636308480000000

It must also not be ridiculously large:

>>> factorial(1e100)

Traceback (most recent call last):

...

OverflowError: n too large

"""

importmath

ifnotn>=0:

raiseValueError("n must be >= 0")

ifmath.floor(n)!=n:

raiseValueError("n must be exact integer")

ifn+1==n:# catch a value like 1e300

raiseOverflowError("n too large")

result=1

factor=2

whilefactor<=n:

result*=factor

factor+=1

returnresult

if__name__=="__main__":

importdoctest

doctest.testmod()

上面是官网提供的一个求N的阶乘函数示例，在docstring 中通过 >>>符号来开始一个单元测试，之后换行输入预期结果即可。实际上就是复制粘贴一下调试过程和结果，真的再简单不过了，想实现TDD也因此变得非常轻松。

用注释写API文档:apidoc

在我们完成机器学习模型后，想要提供一个对外服务的接口以贡献我们的算力时就需要完备的API文档，也是通过API的调用才能为我们的模型提供源源不断的校验数据，对于提升模型效果有非常实际的意义。对大多数人而言调用API来完成开发都是一件比较开心的事情，因为我们可以少做很多工作就可以实现强大功能。然而，当我们需要对外提供API时就要面临不一样的考验了，接口鉴权、接口设计、版本控制、并发问题、日志埋点…这些都是需要面对的新问题，而利用 apidoc 可以很好地解决这些API文档中常见的诸多问题，相当于通过模板提升了我们的接口设计的能力。

apidoc为Python提供了一种类似于 docstring 的方式来写API文档，从语法上看比较类似于 R中的roxygen，都需要用户以 @xxx 符号作为一个开头，随后书写相关的定义和功能。

举个例子：

下面是一个API接口的定义方法，最核心的部分就是

路由

GET/POST方法

名称/分组

参数与调用例子

路由

GET/POST方法

名称/分组

参数与调用例子

(这年头没有用例的代码都是耍流氓)

"""

@api {get} /user/:id Request User information

@apiName GetUser

@apiGroup User

@apiParam {Number} id Users unique ID.

@apiSuccess {String} firstname Firstname of the User.

@apiSuccess {String} lastname Lastname of the User.

"""

"""

@api {get} /user/:id Request User information

@apiName GetUser

@apiGroup User

@apiParam {Number} id Users unique ID.

@apiSuccess {String} firstname Firstname of the User.

@apiSuccess {String} lastname Lastname of the User.

"""

我们可以直接撸一个官方示例来学习如何使用apidoc。

首先，下载示例源码

git clonehttps://github.com/apidoc/apidoc

cdapidoc

git clonehttps://github.com/apidoc/apidoc

cdapidoc

然后，安装 apidoc 组件

sudo npm install apidoc -g

sudo npm install apidoc -g

接着，利用官方代码来制作一个例子，并且访问即可。

apidoc-iexample/ -ooutput/ -ttemplate/

openoutput/index.html

apidoc-iexample/ -ooutput/ -ttemplate/

openoutput/index.html

几个参数的含义如下：

-i:input，表示输入的文件夹

-o:output，表示输出文件夹

-t:template，表示模板文件，通过替换模板我们可以修改文档皮肤

-i:input，表示输入的文件夹

-o:output，表示输出文件夹

-t:template，表示模板文件，通过替换模板我们可以修改文档皮肤

在 example 文件夹下，我们需要在apidoc.json 中填写配置文件，定义文档的header和footer部分内容，其余的文件会被自动识别出其中的docstring作为API文档的一部分。

由于apidoc的官方文档非常简单清晰，所以这里不过多强调语法。

apidoc 还为我们提供了接口调试的功能，在实际使用的时候要注意：

我们需要一个web server 才可以使用这个接口调试的功能

要注意跨域的问题。

我们需要一个web server 才可以使用这个接口调试的功能

要注意跨域的问题。

通过版本对比，我们还可以快速排查API接口的变化情况。需要注意的是这个功能要求我们要将历史的文档记录也要保存在该目录下的文件中，通常我们可以把历史的注释输出到一个特定文件中保存。

总的来说，虽然，API文档的书写并不是一件难度非常高的事情，却能体现系统模块设计和用户体验设计的功力，我们应该对那些无代码示例，无版本控制的API文档say no！

用注释写命令行接口:docopt

利用docopt，我们可以在注释中直接声明文件的命令行传入参数，而不需要通过 argvs变量来捕获输入值再做判断，这在调用运维脚本或者若干任务调度脚本的时候尤其管用，极大地提升了CLI的效率。

举个例子：(此处代码仅供参考)

"""Usage:

fiannceR.py tcp [--timeout=]

fiannceR.py serial [--baud=9600] [--timeout=]

fiannceR.py -h | --help | --version

"""

fromdocoptimportdocopt

if__name__=='__main__':

arguments=docopt(__doc__,version='0.1.1rc')

print(arguments)

"""Usage:

fiannceR.py tcp [--timeout=]

fiannceR.py serial [--baud=9600] [--timeout=]

fiannceR.py -h | --help | --version

"""

fromdocoptimportdocopt

if__name__=='__main__':

arguments=docopt(__doc__,version='0.1.1rc')

print(arguments)

随后，我们可以在命令行中成功调用

fiannceR.py tcp 0.0.0.0 3838

fiannceR.py tcp 0.0.0.0 3838

这里的 arguments 将传出一个字典对象，以Key-Value的形式将命令行中的输入值捕获。

{'--baud':None,

'--help':False,

'--timeout':None,

'--version':False,

'-h':False,

'':'0.0.0.0',

'':'3838',

'serial':False,

'tcp':True}

{'--baud':None,

'--help':False,

'--timeout':None,

'--version':False,

'-h':False,

'':'0.0.0.0',

'':'3838',

'serial':False,

'tcp':True}

总结

如果真的要从数据撸到模型、接口，那么一排注释的画面真是美得不敢想象。

"""unitest

>>> FinanceR('20161001')

21.01

"""

defFinanceR(date):

price=get_price(date)

return(price)

class(BaseHandler):

defget(self):

"""apidoc

@api {get} /price/:date 获取当前价格

@apiName GetPrice

@apiGroup Quota

@apiParam {Number} date 交易日期

@apiSuccess {String} price

"""

date=self.get_argument('date',None)

try:

price=FinanceR(date)

self.write({'data':{'price':price},'response':{'message':'success','code':200}})

exceptExceptionase:

self.write({'data':None,'response':{'message':str(e),'code':404}})

"""Usage:

fiannceR.py tcp [--timeout=]

fiannceR.py serial [--baud=9600] [--timeout=]

fiannceR.py -h | --help | --version

"""

fromdocoptimportdocopt

if__name__=='__main__':

arguments=docopt(__doc__,version='0.1.1rc')

print(arguments)

"""unitest

>>> FinanceR('20161001')

21.01

"""

defFinanceR(date):

price=get_price(date)

return(price)

class(BaseHandler):

defget(self):

"""apidoc

@api {get} /price/:date 获取当前价格

@apiName GetPrice

@apiGroup Quota

@apiParam {Number} date 交易日期

@apiSuccess {String} price

"""

date=self.get_argument('date',None)

try:

price=FinanceR(date)

self.write({'data':{'price':price},'response':{'message':'success','code':200}})

exceptExceptionase:

self.write({'data':None,'response':{'message':str(e),'code':404}})

"""Usage:

fiannceR.py tcp [--timeout=]

fiannceR.py serial [--baud=9600] [--timeout=]

fiannceR.py -h | --help | --version

"""

fromdocoptimportdocopt

if__name__=='__main__':

arguments=docopt(__doc__,version='0.1.1rc')

print(arguments)

欢迎大家留言讨论，给出更多应用案例，交流分享。

参考文献

APIDoc

Python 指南：测试你的代码

doctest

nose is nicer testing for python

tox: standardize testing in Python

Biopython测试框架

Docopt

Sphinxdocopt.R

APIDoc

Python 指南：测试你的代码

doctest

nose is nicer testing for python

tox: standardize testing in Python

Biopython测试框架

Docopt

Sphinxdocopt.R