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的表达能力是无限的；不要过度使用它。
🏷️
