开发者社区> 异步社区> 正文
阿里云
为了无法计算的价值
打开APP
阿里云APP内打开

《Python高手之路》——2.6 管理API变化

简介:
+关注继续查看

本节书摘来自异步社区《Python高手之路》一书中的第2章,第2.6节,作者[法]Julien Danjou(朱利安•丹乔), 王飞龙 译,更多章节内容可以访问云栖社区“异步社区”公众号查看。

2.6 管理API变化

在构造API时很难一蹴而就。API需要不断演化、添加、删除或者修改所提供的功能。

在后面的段落中women将讨论如何管理公共API的变化。公共API是指将应用程序或库暴露给终端用户的API。内部API则有另外的考虑,并且由于它们在内部(也就是说用户不需要直接操作这些API),因而可以任意处理它们:分解、调整或者根据需要任意使用。

这两种API很容易区分。Python的传统是用下划线作为私有API的前缀,如foo是公共API,而_bar是私有的。

在构建API时,最糟糕的事情莫过于API被突然破坏。Linus Torvalds就因对Linux内核公共API破坏的零容忍而闻名。考虑到如此多的人依赖Linux,可以说他的选择是非常明智的。

Unix平台的库管理系统很复杂,它依赖于soname(http://en.wikipedia.org/wiki/Soname )和细粒度的版本标识符。Python中没有这样的系统,也没有对应的转换。因此完全取决于维护者如何选择正确的版本号和策略。但是,关于如何定义自己的库或应用程序的版本,你依然可以将Unix系统作为你的灵感来源。通常,版本号应该反映出API对用户的影响,大部分开发人员通过主版本号的增加来表示此类变化,但这取决于你对版本号管理的方法,你也可以采用增加小版本号的方式。

不管如何决定,最重要的一步就是在修改API时要通过文档对修改进行详细地记录,包括:

  • 记录新的接口;
  • 记录废除的旧的接口;
  • 记录如何升级到新的接口。

旧接口不要立刻删除。实际上,应该尽量长时间地保留旧接口。因为已经明确标识为作废,所以新用户不会去使用它。在维护实在太麻烦时再移除旧接口。API变化的记录见示例2.2.

示例2.2API变化的记录

class Car(object):  
    def turn_left(self):  
        """Turn the car left.  

        .. deprecated:: 1.1  
           Use :func:`turn` instead with the direction argument set to left  
        """  
        self.turn(direction='left')  

    def turn(self, direction):  
        """Turn the car in some direction.  

        :param direction: The direction to turn to.  
        :type direction: str  
        """  
        # Write actual code here instead  
        pass

使用Sphinx标记强调修改是个好主意。在构建文档时,用户应该能清楚地知道某个功能不应该再被使用,并且可以直接访问到新功能,并随之解释如何升级旧代码。这个方法的缺点就是,你不能指望开发人员在升级你的Python包到新版本时会去读你的修改日志或者文档。

Python提供了一个很有意思的名为warnings的模块用来解决这一问题。这一模块允许代码发出不同类型的警告信息,如PendingDeprecationWarning和DeprecationWarning。这些警告能够用来通知开发人员某个正在调用的函数已经废弃或即将废弃。这样,开发人员就能够看到他们正在使用旧接口并且应该相应地进行处理5。

回到之前的例子,我们可以利用它向用户发出警告,如示例2.3所示。

示例2.3 带警告的API变化的记录

import warnings  

class Car(object):  
    def turn_left(self):  
        """Turn the car left.  

        .. deprecated:: 1.1  
           Use :func:`turn` instead with the direction argument set to "left".  
        """  
        warnings.warn("turn_left is deprecated, use turn instead",  
                      DeprecationWarning)  
        self.turn(direction='left')  

    def turn(self, direction):  
        """Turn the car in some direction.  

        :param direction: The direction to turn to.  
        :type direction: str  
        """  
        # Write actual code here instead  
        pass

任何调用了废弃的turn_left函数的代码,都将引发一个警告:

>>> Car().turn_left()  
__main__:8: DeprecationWarning: turn_left is deprecated, use turn instead

注意

  从Python 2.7开始,DeprecationWarning默认将不显示。可以通过在调用python时指定-W all选项来禁用这一过滤器。关于-W的可用值的更多信息可以参考python手册。

让你的代码告诉开发人员他们的程序正在使用某些最终将要停止工作的东西是明智的,因为这其实也可以自动化。当运行他们的测试集合时,开发人员可以在执行python时使用-W error选项,它会将警告转换为异常。这意味着一个废弃的函数每次被调用时都会有一个错误被抛出,这样使用你的库的开发人员就可以很容易知道如何具体修改他们的代码。

示例2.4 运行python -W error

>>> import warnings  
>>> warnings.warn("This is deprecated", DeprecationWarning)  
Traceback (most recent call last):  
  File "<stdin>", line 1, in <module>  
DeprecationWarning: This is deprecated

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
跨平台API对接(Python)的使用
跨平台API对接(Python)的使用
38 0
跨平台API对接(Python)的使用
![](https://ceshiren.com/uploads/default/original/3X/3/a/3a86a19fb6dbb3f346088c7323fa31227d08207b.png) ## Python-Jenkins Python-Jenkins 通过 HTTP 方式运行 Jenkins job 。 Python-Jenkins 官网:https://pypi.py
37 0
跨平台API对接(Python)的使用
跨平台API对接(Python)的使用
55 0
Python编程:python-attrs模块的简单使用
Python编程:python-attrs模块的简单使用
58 0
Python编程:使用sqlalchemy对数据库进行增删改查
Python编程:使用sqlalchemy对数据库进行增删改查
53 0
Python编程:列表、集合、字典推导式的示例
Python编程:列表、集合、字典推导式的示例
20 0
Python编程:asyncio协程编程
Python编程:asyncio协程编程
22 0
Python编程:pillow对图像的简单处理
Python编程:pillow对图像的简单处理
10 0
Python编程:将markdown格式转换为rst格式
Python编程:将markdown格式转换为rst格式
30 0
Python编程专属技巧2
Python编程专属技巧2
39 0
+关注
异步社区
异步社区(www.epubit.com)是人民邮电出版社旗下IT专业图书旗舰社区,也是国内领先的IT专业图书社区,致力于优质学习内容的出版和分享,实现了纸书电子书的同步上架,于2015年8月上线运营。公众号【异步图书】,每日赠送异步新书。
文章
问答
文章排行榜
最热
最新
相关电子书
更多
API 平台的安全实践
立即下载
ACE 区域技术发展峰会:Flink Python Table API入门及实践
立即下载
Python 系列直播——深入Python与日志服务,玩转大规模数据分析处理实战第二讲
立即下载