Python 函数库 APIs 编写指南

本篇文章基于 2017 PyCon 大会上的演讲：How to make a good library API。列出对于构建 Python 库 API 有用的建议清单。

简洁性

在 README 文件中写入简单的客户端代码。
例如：Pendulum 的 README 文件就是以简单的用户代码开始的。

减少冗余的代码：数一数从第一行开始到你真正调用 API 函数的行数。
例如： 与 Request 库相比，进行 HTTP 请求时 urllib2 库就很多的冗余代码。

使用案例
例如： 这个网页展示的内容：https://python-social-auth-docs.readthedocs.io/en/latest/use_cases.html

在实践中逐步完善：实用且明智的缺省值设置

     - 具有缺省设置，并根据最常用的使用情况来设置缺省值。

     - 设置参数位置，将最常用的参数放在前面，将相似的放在一起。例如： JavaScript 的 history.pushState 函数的默认参数顺序是： state, title,  URL。然而很多用户仅仅想要将 URL 添加进历史值中，但是实际的情况却迫使他们不得不设置 state 与 title 参数的值。

不要将源代码片段复制粘贴进你的 API 中。

避免麻烦的输入：
- 检查是否存在参数名歧义的情况。例如在 Scrapy 1.2 中，send 方法有一个 to 参数，接收的是字符串列表。如果用户传入一个字符串，这个方法就会遍历这个字符串，并将每个字符当做一个邮箱地址并发送邮件。在 Scrapy 1.3 中则修改了这个 Bug，修改后即可以接收字符串，也可以接收字符串列表。
- 检测是否只是为了调用 API 就实例化某些东西的情况。如果存在，可以考虑接收封装值。例如：对于一个仅接受类文件对象的函数，如果用户想要调用它，就不得不使用 StringIO 模块。
- 检查是否可以使用内置类型来替换自定义类型。或者两者都支持使用。

坚持最小惊讶原则（ Principle of least astonishment）：如果一个函数特征很让人吃惊，或许就应该考虑重新设计它了。
- 程序默认的行为是用户所期望的吗？
- 程序默认的行为是否符合用户对于程序性能、副作用，安全性，可靠性，安全性以及限制条件的要求？

要做到抽象
- 让用户不需要关心问题是怎么解决的，而是关心要解决什么问题。 例如： 为了完成一个简单的工作，项目开发人员不必过于在意任务序列、消息破坏，序列化等操作，他们只需要使用 @aap.task 这样一个装饰器即可。 API 关注的是任务的定义而不是完成任务的过程。
- 检查 API 中是否包含了不应该有的东西，牢记，要小心所谓的“抽象漏洞定理”（ The Law of Leaky Abstractions）。例如： RPC（remote procedure call）就是一个很好的反面教材，因为它将远程资源当做了本地资源进行抽象处理，但实际上远程资源的处理不同于本地资源。

像点 Python 的样子
- 努力向常见的 Python 习俗靠近，使你的 API 调用看起来就跟 Python 内置的 API 一样。 例如在 Python2 中，ConfigParser.get 接受一个 section 参数和一个 option 参数。但是这个并不符合 Python 习俗，在 Python 的字典（dict）对象的 get 方法中，我们接受的是 key 参数 和一个缺省参数。 在 Python3 中，这个问题得以修复，此函数的参数输入就类似字典那样了。

一致性

命名问题：你 API 中的命名是否和 Python 的习俗保持了一致性？ 我们命名应该与 PEP8 中所给出一致。PEP8 是 Python 官方的代码风格指南。为了保持命名与代码风格的一致性，建议使用 flake8 来规范你的 API 代码。

命名问题：API 中的命名是否一致？
- 术语的顺序： string_encode VS decode_string
- 缩写问题：activate_prev VS fetch_previous 以及 bin2hex VS strtolower
- 是否带有下划线： gettype VS get_class
- 单复数问题： values_list VS value_list
- 正负问题： button.enabled == True VS button.disabled == True

空值问题：在空值意义的定义是否一致？目前的是最好的选择吗？
- 决定下面哪个代表了空值：None、 False、 []、 ''、 0
- 小心一些出人意料的值： bool(datetime.time(0)) == False 在Python3.5以前是这样

参数问题：在参数的顺序上是否具有一致性？例如：datetime.datetime(year, month, day, minute, second, microsecond) vs datetime.timedelta(days, seconds, microseconds, milliseconds, minutes, hours, weeks)

行为问题：在相似或者不同的行为上是否具有一致性？行为的不对称应该反应在格式的不对称上。例如，numbers.sort() VS sort(numbers)

灵活性

减小整体的不连续性
- 检查所有的类的功能是否单一职责？如果不是，就应该把那些类拆解开来。例如，一个从缓存中获取数据的类应该将其连接缓存服务器的步骤交给另一个类做。

- 检查函数的名称中是否包含了 `and` 或者是否包含多个操作。 如果确实如此，应该将这个函数拆成多个不同的函数。但是，如果这个函数经常被调用，那么可以保留一个结合了众多函数的函数。例如： print_formatted 函数可以被拆解为两个函数： print 和 formated


- 检查是否存在用户复制粘贴代码以改变函数功能的行为。 应该提供代码重构，回调功能。


- 检查在函数内部是否使用了属性值，如果有可以使用 get_something 方法代替。例如在 Djando 的 REST 框架中， CursorPagination 这个类仅仅支持一个固定大小的属性值：page_size，其原因就是这个类没有 get_page_size 这个方法。 这个问题再后来就通过上述方法解决了，即添加了 get_page_size 方法。


- 尽量避免隐藏可能有用的参数。例如我们的 API 中调用了另一个低级的 API 但是却没有展示这个低级 API 的参数情况


- 返回用户可能需要的一切信息


- 用户调用 API 时，要处理用户可能需要所有情况


- 在进行 API 测试的时候要测试每一个 mock.pathch。 虽然在程序运行的时候有一些东西不容易修改，但我们可以通过设置参数来修改某些东西。例如，Python 的内置函数 sched.scheduler 接受两个参数 timefunc 和 delayfunc。而我们没必要对 time.monotonic 和 time.sleep 两个函数进行 mock 测试，用户会根据自己的需求进行相应的改变。

建立抽象
- 按照底层实现的结构，去封装我们的函数成员与对象。例如 Beautiful Soup 就为多个分析器设计了同样的 API 结构。

- 提供多级的抽象结构，从最简单到最个性化。例如， Celery 既提供了 @app.task 这个装饰器，又提供了个性化的 task 类，而这个类继承于 celery.Task


- 提供摆脱封装的方法，让用户可以直接使用被抽象的资源和能力。例如，Django 的查询集合支持使用 .extra 方法将自定义的 SQL 与 ORM 进行结合来产生查询语句，同时也支持使用 .raw 来直接使用原生的 SQL 查询语句。


- 将底层实现中常见的错误进行封装，避免给用户直接报错。例如当 API 支持多个数据引擎的时候，出现数据库连接错误时，其显示信息应该一样。这个帮助用户找出问题所在，并且在修改数据库引擎时不会需要修改很多代码。

要有 Python 范
- 对于获取（get）和 设置（set）操作使用 Python 的自带属性
- 对于运算符重载要使用魔法方法（magic method）
- 对于简单的调试，使用 repr 魔法方法
- 对于包含 打开-关闭 或者 开始-结束 这样的包含生命周期的问题，使用 with 语句
- 对于容易组合共同行为或者登记某些东西使用装饰器
- 对于迭代使用迭代器
- 对于复杂的逻辑问题使用生成器
- 对异步问题使用 asyncio
- 尽量使用内置的集合
- 对于简单的控制反演使用简单的高级函数，例如在 list.sort 函数中接受 key 参数作为等级高低计算函数以便计算列表的顺序。
- 对于复杂的流程问题，可以按照 函数/类的管道、继承、生成器的顺序逐一考虑。例如 管道问题可参考：python-social-auth 管道；继承问题可参考： Django 的类； 生成器问题可参考： Scrapy 的爬虫程序。
- 尊重鸭子式编程风格，要求谅解比谅解本身更加容易

国际化终端用户看到的字符串。

安全性

检查文档中的用于描述函数功能的警告性字眼，例如： warning，careful，remember to, dont't forget。如果存在这些字眼，就得考虑如何更改代码使得函数更加安全稳定。

检查常见的错误，使用 Python 内置的 warning 模块来记录警告

明确不安全的行为。例如如果一些变量没有设置值，不要特意为它设置。不要到处写 fileds = None 这样的语句。

不要通过对象名称或者模块名称来隐式地链接代码，使用一个注册函数或者注册装饰器。例如 Django-admin 的注册问题不仅支持通过函数也支持装饰器。

不要依赖方法的调用顺序，尽量使用 with 语句。

快速报错： 程序出错就直接退出并不是 Python 式的思维

- 当一个库函数接受到一个无效的具有错误格式或者错误表达的参数，例如参数溢出，就产生一个 Value Error 错误。
- 当一个库函数接受到一个不兼容类型的数据便产生一个 TypeError 错误，例如 duck 类型并不兼容 quack 类型。 不要在 if isinstance(duck, LibDuck) 或者 if type(duck) == LibDuck) 这样的语句中引发异常。首先尝试使用 quack，如果错误则引发 TypeError 异常，并打印明确的错误信息。

总结

我的 API 旨在将简单的事情变的简洁，将复杂的事情变为现实，将错误的事情永远杜绝。