第三章 管理API变化

在python中用下划线作私有API的前缀，比如_foo就是私有API， foo这种则是公有API

当决定修改API的时候要通过文档对修改进行详细地记录，包括：
1 记录新的接口API
2 记录废弃的旧接口
3 记录如何升级到新接口
4旧API不要直接删除，等到维护实在太麻烦的时候再删除

一般情况下使用""" 或者# 添加注释队API进行说明，不过一般情况下，用户很少会去看底层的API注释。
更近一步的是使用名为warnings 模块，来对控制台进行强制输出提示

#!/usr/bin/env python
#-*- coding:utf-8 -*-
import warnings

class Car(object):
    def turn_left(self):

        warnings.warn("测试，看看就知道了",DeprecationWarning)

        self.turn(direction="left")

    def turn(self,direction):

        pass


from lianxi2 import Car
c=Car()
c.turn_left()

按书上代码 理论上应该出信息，但是再python2.7之后的版本里面，DeprecationWarning，PendingDeprecationWarning，ImportWarning都已经被默认屏蔽了，如果想看见需要再控制台的情况下输入python -W all。
一般这个办法不靠谱，推荐直接使用warnings的基类warnings.warn("测试，看看就知道了",Warning)
附上warnings的错误异常

类 描述

Warning 这是所有警告类别类的基类。它是Exception的一个子类。

UserWarning warn（）的默认类别。

DeprecationWarning 有关不推荐使用的功能的警告的基本类别（默认情况下被忽略）。

SyntaxWarning 基本类别，用于警告关于可疑语法特征的警告。

RuntimeWarning 有关可疑运行时功能的警告的基本类别。

FutureWarning 关于构造的警告的基本类别将在未来语义上发生变化。

PendingDeprecationWarning 基本类别，用于警告将来不推荐使用的功能（默认情况下会被忽略）。

ImportWarning 在导入模块的过程中触发警告的基本类别（默认情况下会被忽略）。

UnicodeWarning 与Unicode相关的警告的基本类别。

如果想撤销警告可以使用

import warnings

def fxn():
    warnings.warn("deprecated", DeprecationWarning)

with warnings.catch_warnings():
    warnings.simplefilter("ignore")
    fxn()

在上下文管理器中，所有的警告都将被忽略。这使您可以使用已知不推荐的代码，而不必查看警告，同时不抑制其他可能不知道其使用弃用代码的代码的警告。注意：这只能在单线程应用程序中保证。如果两个或更多线程同时使用catch_warnings上下文管理器，则行为是未定义的。
另一点 再控制台运行 python -W error 可以把这些警告全部转化为异常 跳出
比如：

python -W error 
>>> import warnings
>>> warnings.warn("测试测试")
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
UserWarning: 测试

书上提供了另一个库debtcollector。

from debtcollector import moves
class Car(object):
    @moves.moved_method("turn",version="1.1")
    def turn_left(self):
        """

        Trun the car left
        """

        self.turn(direction="left")

    def turn(self,direction):

        pass

理论上这玩意是通过装饰器来操作的。看着感觉简单，但是感觉并没有warnings好用，如果使用这个库，会让代码耦合性太高吧？

本章总结
1设计API要使用简单，同时api 变化最好是不变的情况下修改内容。
2API最好是趋于一致性
3编写文档，实时的
4简单实现，优化代码

高手之路第三章管理API变化学习完毕，感觉这章更多的是教学的API的设计思路，更API设置的时候插入警告。