什么是标准的Python docstring格式？ [英] What is the standard Python docstring format?

问题描述

我已经看到在Python中编写docstrings的几种不同风格，是否有官方或约定的风格？

解决方案

格式

Python docstrings可以按照其他帖子显示的几种格式写入。然而，默认的Sphinx docstring格式没有被提及，并且基于 reStructuredText（reST）。您可以在该图标中获取有关主要格式的一些信息。

请注意， PEP 287 建议使用reST。

以下是docstrings的主要使用格式。

- Epytext

历史上一个 javadoc 喜欢风格很流行，所以它被作为 Epydoc 的基础（被称为 epytext 格式）生成文档。

示例：

 code>
这是一个javadoc样式
 
 @param param1：这是第一个参数
 @param param2：这是第二个参数
 @return：这是什么返回的描述
 @raise keyError：引发异常

  

- reST

如今，可能更流行的格式是 reStructuredTe xt （reST）格式，由狮身人面像用于生成文档。
注意：默认情况下，它在JetBrains PyCharm中使用（在定义方法后输入三重引号，然后按Enter键）。默认情况下，它也在Pyment中用作输出格式。

示例：

 这是一个reST风格
 
：param param1：这是第一个参数
：param param2：这是第二个参数
 ：return：这是什么返回的描述
：raisees keyError：引发异常

  

- Google

Google有自己的格式经常使用。它也可以由狮身人面像解释。

示例：

 
这是一个Google样式的例子
 
 Args：
 param1：这是第一个参数
 param2：这是第二个参数
 
返回： 
这是对返回的内容的描述
 
 Raises：
 KeyError：引发异常

  

即使更多示例

- Numpydoc

请注意，Numpy建议按照自己的 numpydoc ，基于Google格式，并可由Sphinx使用。

我的numpydoc描述一种非常exhautive numpydoc格式的字符串
$ string

参数
- ---------
first：array_like
第一个参数名称`first`
second：
第二个参数
第三个：{'value' ，'other'}，opti onal
第三个参数，默认为'value'

返回
-------
string
a一个字符串中的值

Raises
------
KeyError
当一个键错误
另一个错误

转换/生成

使用像 Pyment 这样的工具自动生成一个尚未记录的Python项目的docstrings，或者转换现有的docstrings（可以混合多种格式）从一个格式到另一个。

注意：这些示例取自作品文件

I have seen a few different styles of writing docstrings in Python, is there an official or "agreed-upon" style?

解决方案

Formats

Python docstrings can be written following several formats as the other posts showed. However the default Sphinx docstring format was not mentioned and is based on reStructuredText (reST). You can get some information about the main formats in that tuto.

Note that the reST is recommended by the PEP 287

There follows the main used formats for docstrings.

- Epytext

Historically a javadoc like style was prevalent, so it was taken as a base for Epydoc (with the called Epytext format) to generate documentation.

Example:

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

- reST

Nowadays, the probably more prevalent format is the reStructuredText (reST) format that is used by Sphinx to generate documentation. Note: it is used by default in JetBrains PyCharm (type triple quotes after defining a method and hit enter). It is also used by default as output format in Pyment.

Example:

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

- Google

Google has their own format that is often used. It also can be interpreted by Sphinx.

Example:

"""
This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

Even more examples

- Numpydoc

Note that Numpy recommend to follow their own numpydoc based on Google format and usable by Sphinx.

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
    the 1st param name `first`
second :
    the 2nd param
third : {'value', 'other'}, optional
    the 3rd param, by default 'value'

Returns
-------
string
    a value in a string

Raises
------
KeyError
    when a key error
OtherError
    when an other error
"""

Converting/Generating

It is possible to use a tool like Pyment to automatically generate docstrings to a Python project not yet documented, or to convert existing docstrings (can be mixing several formats) from a format to an other one.

Note: The examples are taken from the Pyment documentation

这篇关于什么是标准的Python docstring格式？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！