SuperAPI AI 工具集

designing-python-apis

编程与开发

查看项目

更新于 10-15 23:57

技能介绍

用途:指导设计直观的 Python 库 API,遵循简单性、一致性、最少意外和可发现性原则,并采用渐进式披露模式(简单函数→可配置类→底层访问)。

主要能力:命名约定(动作动词、get_、is_/has_/can_、to_/from_);自定义异常与带提示的错误信息;公共再导出应直接引用规范实现而非包装或复制,并通过文档化导入路径测试真实行为;弃用需先警告、记录移除版本、仅在主版本移除。

关键限制与陷阱:失败必须显式暴露,错误路径不得写入成功标记;不得把不同失败吞并为通用消息;空或部分结果不得伪装成完整答案;外部调用计量应放在最低共享请求边界;意外输入不得静默无操作;验证错误不得留下部分修改,需先验证再变更;过滤为空不得视为全部通过;不得伪造回退数据;非零退出码不得丢弃真实输出。

用法:通过公共导入路径测试,如 from mylib import initialize_parser,并用身份断言防止漂移。反模式包括布尔陷阱,应改用关键字参数。

适用场景:Python 库与包 API 设计、评审与演进。限制:具体版本、平台、收费等信息暂未提供。