Ben Hoyt's technical writing
·
设计Python风格的库API
💡
原文英文，约6500词，阅读约需24分钟。
📝
内容提要
本文介绍Python库API设计的原则，包括遵循PEP 8和PEP 20规范，简单易用的API设计，简洁明了的命名，使用下划线表示私有变量，异常以及版本更新的处理，使用关键字参数和动态类型保持向后兼容。同时，文章也提到了Python的类型注释和数据类的使用，以及Python的灵活性需要谨慎使用。
🎯
关键要点
- 良好的API设计对用户非常重要。
- 创建库时，从良好的基础开始并进行迭代。
- 尽量遵循PEP 8和理解PEP 20，这是正确的方式。
- 标准库并不总是最佳示例。
- 暴露干净的API；文件结构是实现细节。
- 扁平结构优于嵌套结构。
- 设计库时应使用 import lib...lib.Thing() 而不是 from lib import LibThing...LibThing()。
- 避免全局配置；使用良好的默认值并让用户覆盖它们。
- 避免全局状态；使用类来代替。
- 名称应尽可能简短，同时保持清晰。
- 函数名称应为动词，类名称应为名词，但不要过于纠结于此。
- 使用单下划线表示私有是可以的；双下划线的额外隐私是不必要的。
- 如果发生错误，应抛出异常；在适当的情况下使用自定义异常。
- 只有在彻底重构API时才打破向后兼容性。
- 关键字参数和动态类型对于保持向后兼容性非常有用。
- 至少对公共API使用类型注释；用户会感谢你。
- 对于主要是数据的类使用 @dataclass。
- Python的表达能力是无限的；不要过度使用它。
➡️
