python numpydoc

NumPyDoc这东西说起来其实就是Python文档社区给NumPy写的那套文档风格指南。你可能见过那种函数定义下面写着Parameters、Returns、Raises的注释块那就是它的产物。NumPy的开发者们当年面对各种科学计算库的文档乱象决定搞一套规范出来。现在它已经成了数据科学界约定俗成的文档风格和Google风格、Sphinx风格并列。1他是什么简单说就是一套结构化的注释模板。不是随便写的它规定了你在函数、类、模块的文档字符串里该写哪些章节每个章节的内容应该长什么样。比如你写个函数做数据清洗按照NumPyDoc风格你得写上函数干什么用的参数有哪些参数名、类型、含义返回什么返回类型、含义可能抛出什么异常还有例子这套风格的好处是清晰、结构化比某些项目里随便写写“这个函数用来处理数据”要强得多。写出来之后你的IDE能识别这些标签自动提示参数和返回内容。Sphinx文档生成器也能直接解析它生成漂亮的文档页面。2他能做什么主要是三件事。第一让你的代码自解释。比如你三个月后回头看自己写的代码打开那个csv文件预处理函数看到Parameters下面写着file_path: str, 输入文件的路径支持相对路径和绝对路径比看一堆args、kwargs游走天地要清晰。第二让IDE给你打工。PyCharm、VSCode这些编辑器能识别NumPyDoc风格的文档字符串。你敲函数名的时候IDE会弹出参数提示里面有你的文档里的内容。这等于把文档直接嵌入了开发流。第三自动生成文档。你在项目里写好了文档运行sphinx-build它会自动抓取这些文档块生成网页或者PDF格式的参考文档。知乎上那些看着像官方文档的Python库很多就是这么来的。另一个很多人忽略的点它强制你思考你的函数的接口。你得想清楚每个参数的类型、含义、默认值。这个思考过程本身就能帮你提前发现设计缺陷。3怎么使用拿一个实际的例子来说。假设你写了个函数把摄氏温度和华氏温度互转。deftemp_convert(value,from_unitC): 温度单位的转换。 支持摄氏度和华氏度之间的相互转换。 转换公式来自热力学定义。 Parameters ---------- value : float 待转换的温度值。 from_unit : str, optional 输入温度的单位C 表示摄氏度F 表示华氏度。 默认为 C。 Returns ------- float 转换后的温度值。 Raises ------ ValueError 如果 from_unit 不是 C 或 F。 Examples -------- temp_convert(100, C) 212.0 temp_convert(32, F) 0.0 iffrom_unitnotin(C,F):raiseValueError(fUnsupported unit:{from_unit})iffrom_unitC:returnvalue*9.0/5.032else:return(value-32)*5.0/9.0注意几个细节第一行是摘要一句话说完这个函数是干什么的。空行之后写详细的描述可以有多个段落。Parameters 下面参数名和类型写在一行用冒号隔开或者用空格隔开但冒号更常见。然后下一行缩进写描述。Returns 的写法和 Parameters 类似。Raises 可选但如果你的函数可能会抛出异常建议写上。4最佳实践有些地方容易出现理解偏差分享一下实际经验。第一个别把参数描述写成废话。“value输入参数”这种写法等于没写。应该写清楚这个参数的物理意义、取值范围、单位。比如上面的“待转换的温度值”虽然简单但已经比“value: 一个数字”强。第二个类型标注尽量具体。float或int可以写清楚别动不动就写Any。如果参数可以是多种类型用float or int或者Union[float, int]。第三个Examples 部分真的很有用。写一个或两个典型用法能帮使用的人省掉10分钟的试错时间。而且这些例子能用doctest库自动化测试一举两得。第四个文档要和代码一起维护。改代码忘了改文档这种事太常见了。建议在代码审查的时候把文档修改当成必须项。第五个注意不要过度文档。一些小函数或者私有函数以单下划线开头的那种可以写简单点甚至不写完整的NumPyDoc。公有的API函数才需要写全。否则项目注释量会变得很夸张反而影响阅读。5和同类技术对比最常拿来比较的是Google风格和Sphinx风格。Google风格的写法deftemp_convert(value,from_unitC):温度单位的转换。 Args: value (float): 待转换的温度值。 from_unit (str, optional): 输入温度的单位。 默认为 C。 Returns: float: 转换后的温度值。 Raises: ValueError: 如果 from_unit 不是 C 或 F。 Sphinx风格reStructuredText格式deftemp_convert(value,from_unitC):温度单位的转换。 :param value: 待转换的温度值。 :type value: float :param from_unit: 输入温度的单位。默认为 C。 :type from_unit: str :returns: 转换后的温度值。 :rtype: float :raises ValueError: 如果 from_unit 不是 C 或 F。 个人感觉NumPyDoc 可读性最好参数和返回值的描述都在独立的段落里一眼就能看到关键信息。特别是参数很多的时候Google风格的Args:部分会挤在一起而NumPyDoc用空行分隔更清楚。Google风格简洁适合小函数或者快速写注释的场景。但参数类型和描述写在一行如果参数多了会有点乱。Sphinx风格的冒号标记法写起来很快但可读性稍差。现在用的人相对少一些。选哪种风格主要看团队习惯。如果已经是NumPy生态的老项目NumPyDoc是自然选择。Google风格现在在Python社区也挺流行Google自己的开源项目都是这个风格。Sphinx风格主要是兼容性的考虑老项目里比较多见。最终效果上三种风格都能被Sphinx正确解析生成文档差别主要是阅读时的体验和书写时的习惯。我自己倾向于NumPyDoc因为参数和返回值的段落分隔让它看起来像一本书的章节而不是一行行的标签。