科学计算数据分析【免费下载链接】numpyThe fundamental package for scientific computing with Python.项目地址https://gitcode.com/gh_mirrors/nu/numpy点击查看免费下载本文以 NumPy 仓库中的 doc/EXAMPLE_DOCSTRING.rst 为范本系统讲解 NumPy乃至整个 SciPy 生态docstring 的标准结构与写作方法。该文档以multivariate_normal随机分布函数为实例逐节示范了从签名行、Parameters、Returns 到 References、Examples 的完整写法。读完本文你将掌握如何为 C 语言扩展函数撰写带签名声明的 docstring、如何组织数学说明与可复现示例并通过仓库中 numpy/random/mtrand.pyx 的真实实现与 numpy/random/tests/test_random.py 的测试用例理解规范背后的工程实践。文档定位一份活的docstring 规范范例doc/EXAMPLE_DOCSTRING.rst是 NumPy 仓库中一份特殊的文档——它不是讲述某个 API 的用法而是用一整篇完整的 docstring来示范如何写 docstring。文档开篇的注释点明了两个关键事实该示例针对的是C 语言编写或经 Cython 编译的函数因此需要显式给出函数签名signaturePython 无法通过内省inspection获取 C 函数的参数签名所以签名必须写在 docstring 的首行而对于其他用纯 Python 编写的函数则直接从一行描述开始即可。这意味着凡是numpy/random/mtrand.pyx、numpy/random/_generator.pyx中定义的函数其 docstring 都必须遵循这一约定——签名行 各规范小节。与之配套的写作规范可参考doc/HOWTO_DOCUMENT.rst该文件已声明其内容被 numpydoc 文档标准取代进一步印证了 NumPy docstring 规范的标准化地位。docstring 的标准结构逐节剖析范例 docstring 采用 numpydoc 约定按固定顺序组织以下小节1. 签名行Signaturemultivariate_normal(mean, cov[, shape])签名行是 C 函数 docstring 的第一行用于弥补 Python 无法内省 C 函数签名的缺陷。注意示例中使用了方括号[, shape]表示可选参数——这是旧式写法在仓库真实代码中签名已显式写出全部参数与默认值例如 numpy/random/mtrand.pyx 中的multivariate_normal(mean, cov, sizeNone, check_validwarn, tol1e-8)显然显式列出默认值比方括号省略写法更精确、更利于文档工具解析。2. 一句话描述Summary签名之后紧跟一行式描述说明函数做什么Draw samples from a multivariate normal distribution.规范要求这一行要短、以动词开头、能独立成句让读者在文档索引中即可快速理解函数用途。后续的详细段落则进一步展开背景例如将多元正态分布定义为一维正态分布向高维的推广并类比 mean 与方差的关系。3. Parameters 小节示例给出三个参数参数类型说明mean(N,) ndarrayN 维分布的均值cov(N, N) ndarray分布的协方差矩阵shapetuple of ints, optional如(m, n, k)则生成m*n*k个样本输出形状为(m, n, k, N)缺省时返回单个样本真实代码中的参数列表更为完整numpy/random/mtrand.pyx 补充了cov增加约束说明必须对称且半正定才能正确采样size : int or tuple of ints, optional明确标注sizeNone时返回单个(N,)样本check_valid : { warn, raise, ignore }, optional——协方差矩阵非半正定时采取的行为tol : float, optional——检查协方差奇异值时的容差且注明检查前cov会被转换为 double。而新的Generator版本numpy/random/_generator.pyx还多了method : { svd, eigh, cholesky }, optional参数用于选择计算因子矩阵A满足A A.T cov的分解方法并明确性能差异默认svd最慢但最稳健cholesky最快但稳健性较差eigh介于两者之间。4. Returns 小节out : ndarray The drawn samples, arranged according to shape. ...规范要求即使返回值类型简单也要写出out : ndarray及其形状语义。示例特别解释了输出形状规则——out[i, j, ... , :]的最后一维是 N 维样本即每个切片out[i, j, ...]都是来自该分布的一个 N 维采样值。5. See also 小节用于给出相关但不等同的参考对象normal scipy.stats.norm : Provides random variates, as well as probability density function, cumulative density function, etc.规范的写法是同类 API 直接列名称跨模块对象采用module.object : 一句话说明的格式。仓库真实 docstring 中则将random.Generator.multivariate_normal列为首选参考并标注新代码应使用该新 API。6. Notes 小节数学背景与几何直觉Notes 是 docstring 中最具技术含量的小节范例展示了三方面内容数学定义均值是 N 维空间中样本最可能生成的位置坐标类比一维钟形曲线的峰值协方差矩阵元素C_ij是x_i与x_j的协方差C_ii是x_i的方差散布程度。原文使用 reStructuredText 数学指令:math:排版公式。常用近似模型球面协方差cov为单位阵的倍数与对角协方差cov仅对角线上有非负元素——这是实际应用中降低参数量的两种常见做法。可运行的绘图示例用对角协方差[[1, 0], [0, 100]]生成 5000 个点并绘制散点图直观展示点在 x 轴或 y 轴方向延展的几何特性注意此时两变量独立、等高线方向与坐标轴对齐。7. References 小节列出支撑数学背景的文献使用.. [n]编号列表格式.. [1] A. Papoulis, Probability, Random Variables, and Stochastic Processes, 3rd ed., McGraw-Hill Companies, 1991 .. [2] R.O. Duda, P.E. Hart, and D.G. Stork, Pattern Classification, 2nd ed., Wiley, 2001.仓库真实 docstringnumpy/random/mtrand.pyx保留了这两条引用说明教学范例与实际实现一脉相承。8. Examples 小节可复现的 doctestExamples 必须是可以直接被 doctest 执行的代码范例演示了两种用法 mean (1, 2) cov [[1, 0], [0, 1]] x np.random.multivariate_normal(mean, cov, (3, 3)) x.shape (3, 3, 2)即size(3, 3)时生成 3×3 个二维样本输出形状为(3, 3, 2)。第二个示例则展示结果因随机数而异的写法——用# may vary标注不确定性输出。真实 docstring 还加入了统计验证示例生成 800 个样本后用pts.mean(axis0)、np.cov(pts.T)、np.corrcoef(pts.T)验证样本均值、协方差与相关系数接近理论值并附散点图展示负相关点云的取向。9. 索引指令indexdocstring 末尾的.. index: :refguide: random:distributions将本函数纳入文档索引的random:distributions分类便于文档工具生成交叉引用与 API 索引。从范例到实现multivariate_normal 的源码级原理范例 docstring 描述的 API 在仓库中的实现位于 numpy/random/mtrand.pyx。其采样算法值得关注注释中已完整阐述预处理mean、cov转为 ndarray 并做维度校验mean 必须一维、cov 必须二维且方阵、两者长度一致否则抛出ValueError生成标准正态矩阵按final_shape list(shape) [N]生成独立标准正态随机数并 reshape 为(-1, N)SVD 分解求因子矩阵对cov做svd(cov)得(u, s, v)由于sqrt(s) * v满足A A.T cov即dot(transpose(A), A) cov于是x np.dot(x, np.sqrt(s)[:, None] * v)即可将标准正态样本变换为具有目标协方差的多元正态样本平移与整形x mean并 reshape 回final_shape。代码注释特别说明选择 SVD 而非 Cholesky 是为了保持历史输出结果一致GH10839确保先cov.astype(np.double)再比较使tol有意义。check_valid的实现也清晰可循非ignore时用np.allclose(np.dot(v.T * s, v), cov, rtoltol, atoltol)判断协方差是否半正定不满足时按warn发RuntimeWarning、按raise抛ValueError。这正对应 docstring 中check_valid参数的三档语义Docstring、实现与文档三者完全一致。测试用例对 docstring 的印证numpy/random/tests/test_random.py 中的test_multivariate_normal逐一验证了 docstring 声称的行为size(3, 2)时输出形状与数值序列完全吻合与期望数组比较精度decimal15不传 size默认单样本时返回(N,)形状——印证 Returns 中未指定 shape 时返回单个 N 维样本的说明非半正定协方差[[1, 2], [2, 1]]触发RuntimeWarning——印证check_validwarn默认行为check_validignore时不产生任何警告check_validraise时抛出ValueErrorfloat32 协方差输入也能正常采样且不触发异常——印证实现中的 double 转换逻辑。新旧 API 与写作规范的最佳实践从范例文档到仓库实现可以总结出 NumPy docstring 写作的核心最佳实践签名行只属于 C/Cython 函数纯 Python 函数直接从一句话描述开始小节顺序固定Signature → Summary → Parameters → Returns → See also → Notes → References → Examples → 索引指令便于工具链Sphinx numpydoc自动解析参数与返回描述要给出形状与约束如(N,) ndarray、必须对称半正定并标注可选参数默认值数学内容用:math:排版复杂背景放入 Notes避免挤占 SummaryExamples 必须可运行随机结果用# may vary标注示例不仅要展示调用更要展示如何验证结果均值、协方差的统计核对文档、实现、测试三方对齐docstring 中的每个参数与行为都能在 numpy/random/mtrand.pyx、numpy/random/_generator.pyx 与numpy/random/tests/下的测试中找到对应证据。撰写 NumPy 风格 docstring 时把doc/EXAMPLE_DOCSTRING.rst作为起点模板对照真实实现补齐参数细节如check_valid、tol、method并用仓库测试验证示例结论即可写出信息完整、机器可解析、读者可复现的高质量 API 文档。赞分享科学计算数据分析【免费下载链接】numpyThe fundamental package for scientific computing with Python.项目地址https://gitcode.com/gh_mirrors/nu/numpy点击查看免费下载相关推荐SpeechBrain 代码规范指南NumPy 风格 Docstring 写作与自动校验实战SpeechBrain 代码规范指南NumPy 风格 Docstring 写作与自动校验实战 SpeechBrainA PyTorch based Spee人工智能深度学习语音音频NLP预训练Manim 社区 Docstring 编写规范从 NumPy 格式到类型注解的完整实践指南Manim 社区 Docstring 编写规范从 NumPy 格式到类型注解的完整实践指南 导读 本文以 Manim Community 官方贡献指南中的图形学教育DiceDB 命令文档编写指南以 SET 命令为范例的完整规范与实战解析DiceDB 命令文档编写指南以 SET 命令为范例的完整规范与实战解析 docs/sample_command_docs.md 是 DiceDB 项目中命令数据库缓存后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 NumPy Docstring 规范实战：以 multivariate_normal 为例的完整写作指南
科学计算数据分析【免费下载链接】numpyThe fundamental package for scientific computing with Python.项目地址https://gitcode.com/gh_mirrors/nu/numpy点击查看免费下载本文以 NumPy 仓库中的 doc/EXAMPLE_DOCSTRING.rst 为范本系统讲解 NumPy乃至整个 SciPy 生态docstring 的标准结构与写作方法。该文档以multivariate_normal随机分布函数为实例逐节示范了从签名行、Parameters、Returns 到 References、Examples 的完整写法。读完本文你将掌握如何为 C 语言扩展函数撰写带签名声明的 docstring、如何组织数学说明与可复现示例并通过仓库中 numpy/random/mtrand.pyx 的真实实现与 numpy/random/tests/test_random.py 的测试用例理解规范背后的工程实践。文档定位一份活的docstring 规范范例doc/EXAMPLE_DOCSTRING.rst是 NumPy 仓库中一份特殊的文档——它不是讲述某个 API 的用法而是用一整篇完整的 docstring来示范如何写 docstring。文档开篇的注释点明了两个关键事实该示例针对的是C 语言编写或经 Cython 编译的函数因此需要显式给出函数签名signaturePython 无法通过内省inspection获取 C 函数的参数签名所以签名必须写在 docstring 的首行而对于其他用纯 Python 编写的函数则直接从一行描述开始即可。这意味着凡是numpy/random/mtrand.pyx、numpy/random/_generator.pyx中定义的函数其 docstring 都必须遵循这一约定——签名行 各规范小节。与之配套的写作规范可参考doc/HOWTO_DOCUMENT.rst该文件已声明其内容被 numpydoc 文档标准取代进一步印证了 NumPy docstring 规范的标准化地位。docstring 的标准结构逐节剖析范例 docstring 采用 numpydoc 约定按固定顺序组织以下小节1. 签名行Signaturemultivariate_normal(mean, cov[, shape])签名行是 C 函数 docstring 的第一行用于弥补 Python 无法内省 C 函数签名的缺陷。注意示例中使用了方括号[, shape]表示可选参数——这是旧式写法在仓库真实代码中签名已显式写出全部参数与默认值例如 numpy/random/mtrand.pyx 中的multivariate_normal(mean, cov, sizeNone, check_validwarn, tol1e-8)显然显式列出默认值比方括号省略写法更精确、更利于文档工具解析。2. 一句话描述Summary签名之后紧跟一行式描述说明函数做什么Draw samples from a multivariate normal distribution.规范要求这一行要短、以动词开头、能独立成句让读者在文档索引中即可快速理解函数用途。后续的详细段落则进一步展开背景例如将多元正态分布定义为一维正态分布向高维的推广并类比 mean 与方差的关系。3. Parameters 小节示例给出三个参数参数类型说明mean(N,) ndarrayN 维分布的均值cov(N, N) ndarray分布的协方差矩阵shapetuple of ints, optional如(m, n, k)则生成m*n*k个样本输出形状为(m, n, k, N)缺省时返回单个样本真实代码中的参数列表更为完整numpy/random/mtrand.pyx 补充了cov增加约束说明必须对称且半正定才能正确采样size : int or tuple of ints, optional明确标注sizeNone时返回单个(N,)样本check_valid : { warn, raise, ignore }, optional——协方差矩阵非半正定时采取的行为tol : float, optional——检查协方差奇异值时的容差且注明检查前cov会被转换为 double。而新的Generator版本numpy/random/_generator.pyx还多了method : { svd, eigh, cholesky }, optional参数用于选择计算因子矩阵A满足A A.T cov的分解方法并明确性能差异默认svd最慢但最稳健cholesky最快但稳健性较差eigh介于两者之间。4. Returns 小节out : ndarray The drawn samples, arranged according to shape. ...规范要求即使返回值类型简单也要写出out : ndarray及其形状语义。示例特别解释了输出形状规则——out[i, j, ... , :]的最后一维是 N 维样本即每个切片out[i, j, ...]都是来自该分布的一个 N 维采样值。5. See also 小节用于给出相关但不等同的参考对象normal scipy.stats.norm : Provides random variates, as well as probability density function, cumulative density function, etc.规范的写法是同类 API 直接列名称跨模块对象采用module.object : 一句话说明的格式。仓库真实 docstring 中则将random.Generator.multivariate_normal列为首选参考并标注新代码应使用该新 API。6. Notes 小节数学背景与几何直觉Notes 是 docstring 中最具技术含量的小节范例展示了三方面内容数学定义均值是 N 维空间中样本最可能生成的位置坐标类比一维钟形曲线的峰值协方差矩阵元素C_ij是x_i与x_j的协方差C_ii是x_i的方差散布程度。原文使用 reStructuredText 数学指令:math:排版公式。常用近似模型球面协方差cov为单位阵的倍数与对角协方差cov仅对角线上有非负元素——这是实际应用中降低参数量的两种常见做法。可运行的绘图示例用对角协方差[[1, 0], [0, 100]]生成 5000 个点并绘制散点图直观展示点在 x 轴或 y 轴方向延展的几何特性注意此时两变量独立、等高线方向与坐标轴对齐。7. References 小节列出支撑数学背景的文献使用.. [n]编号列表格式.. [1] A. Papoulis, Probability, Random Variables, and Stochastic Processes, 3rd ed., McGraw-Hill Companies, 1991 .. [2] R.O. Duda, P.E. Hart, and D.G. Stork, Pattern Classification, 2nd ed., Wiley, 2001.仓库真实 docstringnumpy/random/mtrand.pyx保留了这两条引用说明教学范例与实际实现一脉相承。8. Examples 小节可复现的 doctestExamples 必须是可以直接被 doctest 执行的代码范例演示了两种用法 mean (1, 2) cov [[1, 0], [0, 1]] x np.random.multivariate_normal(mean, cov, (3, 3)) x.shape (3, 3, 2)即size(3, 3)时生成 3×3 个二维样本输出形状为(3, 3, 2)。第二个示例则展示结果因随机数而异的写法——用# may vary标注不确定性输出。真实 docstring 还加入了统计验证示例生成 800 个样本后用pts.mean(axis0)、np.cov(pts.T)、np.corrcoef(pts.T)验证样本均值、协方差与相关系数接近理论值并附散点图展示负相关点云的取向。9. 索引指令indexdocstring 末尾的.. index: :refguide: random:distributions将本函数纳入文档索引的random:distributions分类便于文档工具生成交叉引用与 API 索引。从范例到实现multivariate_normal 的源码级原理范例 docstring 描述的 API 在仓库中的实现位于 numpy/random/mtrand.pyx。其采样算法值得关注注释中已完整阐述预处理mean、cov转为 ndarray 并做维度校验mean 必须一维、cov 必须二维且方阵、两者长度一致否则抛出ValueError生成标准正态矩阵按final_shape list(shape) [N]生成独立标准正态随机数并 reshape 为(-1, N)SVD 分解求因子矩阵对cov做svd(cov)得(u, s, v)由于sqrt(s) * v满足A A.T cov即dot(transpose(A), A) cov于是x np.dot(x, np.sqrt(s)[:, None] * v)即可将标准正态样本变换为具有目标协方差的多元正态样本平移与整形x mean并 reshape 回final_shape。代码注释特别说明选择 SVD 而非 Cholesky 是为了保持历史输出结果一致GH10839确保先cov.astype(np.double)再比较使tol有意义。check_valid的实现也清晰可循非ignore时用np.allclose(np.dot(v.T * s, v), cov, rtoltol, atoltol)判断协方差是否半正定不满足时按warn发RuntimeWarning、按raise抛ValueError。这正对应 docstring 中check_valid参数的三档语义Docstring、实现与文档三者完全一致。测试用例对 docstring 的印证numpy/random/tests/test_random.py 中的test_multivariate_normal逐一验证了 docstring 声称的行为size(3, 2)时输出形状与数值序列完全吻合与期望数组比较精度decimal15不传 size默认单样本时返回(N,)形状——印证 Returns 中未指定 shape 时返回单个 N 维样本的说明非半正定协方差[[1, 2], [2, 1]]触发RuntimeWarning——印证check_validwarn默认行为check_validignore时不产生任何警告check_validraise时抛出ValueErrorfloat32 协方差输入也能正常采样且不触发异常——印证实现中的 double 转换逻辑。新旧 API 与写作规范的最佳实践从范例文档到仓库实现可以总结出 NumPy docstring 写作的核心最佳实践签名行只属于 C/Cython 函数纯 Python 函数直接从一句话描述开始小节顺序固定Signature → Summary → Parameters → Returns → See also → Notes → References → Examples → 索引指令便于工具链Sphinx numpydoc自动解析参数与返回描述要给出形状与约束如(N,) ndarray、必须对称半正定并标注可选参数默认值数学内容用:math:排版复杂背景放入 Notes避免挤占 SummaryExamples 必须可运行随机结果用# may vary标注示例不仅要展示调用更要展示如何验证结果均值、协方差的统计核对文档、实现、测试三方对齐docstring 中的每个参数与行为都能在 numpy/random/mtrand.pyx、numpy/random/_generator.pyx 与numpy/random/tests/下的测试中找到对应证据。撰写 NumPy 风格 docstring 时把doc/EXAMPLE_DOCSTRING.rst作为起点模板对照真实实现补齐参数细节如check_valid、tol、method并用仓库测试验证示例结论即可写出信息完整、机器可解析、读者可复现的高质量 API 文档。赞分享科学计算数据分析【免费下载链接】numpyThe fundamental package for scientific computing with Python.项目地址https://gitcode.com/gh_mirrors/nu/numpy点击查看免费下载相关推荐SpeechBrain 代码规范指南NumPy 风格 Docstring 写作与自动校验实战SpeechBrain 代码规范指南NumPy 风格 Docstring 写作与自动校验实战 SpeechBrainA PyTorch based Spee人工智能深度学习语音音频NLP预训练Manim 社区 Docstring 编写规范从 NumPy 格式到类型注解的完整实践指南Manim 社区 Docstring 编写规范从 NumPy 格式到类型注解的完整实践指南 导读 本文以 Manim Community 官方贡献指南中的图形学教育DiceDB 命令文档编写指南以 SET 命令为范例的完整规范与实战解析DiceDB 命令文档编写指南以 SET 命令为范例的完整规范与实战解析 docs/sample_command_docs.md 是 DiceDB 项目中命令数据库缓存后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考