Pregunta ¿Cuál es el formato de docstring estándar de Python? [cerrado]


He visto algunos estilos diferentes de docstrings de escritura en Python, ¿hay un estilo oficial o "acordado"?


584
2017-10-10 01:10


origen


Respuestas:


Formatos

Las cadenas de documentos de Python se pueden escribir siguiendo varios formatos como se muestran en las otras publicaciones. Sin embargo, el formato predeterminado de docstring de Sphinx no se mencionó y se basa en reStructuredText (reST). Puede obtener información sobre los formatos principales en ese tuto.

Tenga en cuenta que el reST es recomendado por PEP 287

Sigue los principales formatos utilizados para docstrings.

- Epytext

Históricamente javadoc al igual que el estilo era frecuente, por lo que se tomó como una base para Epydoc (con el llamado Epytext formato) para generar documentación.

Ejemplo:

"""
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
"""

- descanso

Hoy en día, el formato probablemente más frecuente es el reStructuredText (reST) formato que es utilizado por Esfinge para generar documentación. Nota: se usa por defecto en JetBrains PyCharm (escriba comillas triples después de definir un método y presione enter). También se usa por defecto como formato de salida en Pyment.

Ejemplo:

"""
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 tiene su propio formato eso se usa a menudo. También puede ser interpretado por Sphinx.

Ejemplo:

"""
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.
"""

Incluso más ejemplos

- Numpydoc

Tenga en cuenta que Numpy recomienda seguir su propio numpydoc basado en el formato de Google y usable por 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
"""

Conversión / Generación

Es posible usar una herramienta como Pyment generar automáticamente cadenas de documentos para un proyecto de Python aún no documentado, o convertir cadenas de documentos existentes (puede mezclar varios formatos) de un formato a otro.

Nota: los ejemplos están tomados del Documentación de pago


617
2018-06-24 11:10



los Guía de estilo de Google contiene una excelente guía de estilo de Python. Incluye convenciones para la sintaxis docstring legible que ofrece una mejor orientación que PEP-257. Por ejemplo:

def square_root(n):
    """Calculate the square root of a number.

    Args:
        n: the number to get the square root of.
    Returns:
        the square root of n.
    Raises:
        TypeError: if n is not a number.
        ValueError: if n is negative.

    """
    pass

Me gustaría extender esto para incluir también información de tipo en los argumentos, como se describe en este Tutorial de documentación de Sphinx. Por ejemplo:

def add_value(self, value):
    """Add a new value.

       Args:
           value (str): the value to add.
    """
    pass

295
2017-11-13 03:14



Las convenciones de Docstring están en PEP-257 con muchos más detalles que PEP-8.

Sin embargo, las cadenas de documentación parecen ser mucho más personales que otras áreas de código. Los diferentes proyectos tendrán su propio estándar.

Tiendo a incluir siempre docstrings, porque tienden a demostrar cómo usar la función y lo que hace muy rápidamente.

Prefiero mantener las cosas consistentes, independientemente de la longitud de la cadena. Me gusta cómo se ve el código cuando la indentación y el espaciado son consistentes. Eso significa que yo uso:

def sq(n):
    """
    Return the square of n. 
    """
    return n * n

Encima:

def sq(n):
    """Returns the square of n."""
    return n * n

Y tienden a dejar de comentar en la primera línea en documentos más largos:

def sq(n):
    """
    Return the square of n, accepting all numeric types:

    >>> sq(10)
    100

    >>> sq(10.434)
    108.86835599999999

    Raises a TypeError when input is invalid:

    >>> sq(4*'435')
    Traceback (most recent call last):
      ...
    TypeError: can't multiply sequence by non-int of type 'str'

    """
    return n*n

Lo que significa que encuentro que las cadenas de documentos que comienzan así son complicadas.

def sq(n):
    """Return the squared result. 
    ...

214
2017-10-10 05:36



Como aparentemente nadie lo mencionó: también puede usar el Numpy Docstring Standard. Es ampliamente utilizado en la comunidad científica.

La extensión de la esfinge de Napolean para analizar las cadenas de documentos de estilo de Google (recomendadas en la respuesta de @Nathan) también es compatible con la cadena de documentos de estilo Numpy, y hace un cortocircuito comparación de ambos.

Y por último, un ejemplo básico para dar una idea de cómo se ve:

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Parameters
    ----------
    arg1 : int
        Description of arg1
    arg2 : str
        Description of arg2

    Returns
    -------
    bool
        Description of return value

    See Also
    --------
    otherfunc : some related other function

    Examples
    --------
    These are written in doctest format, and should illustrate how to
    use the function.

    >>> a=[1,2,3]
    >>> print [x + 3 for x in a]
    [4, 5, 6]
    """
    return True

42
2018-04-21 00:01



PEP-8 es el estándar oficial de codificación python. Contiene una sección sobre docstrings, que se refiere a PEP-257 - una especificación completa para docstrings.


12
2017-10-10 01:48



Los estilos oficiales de Python se enumeran en PEP-8.


3
2017-10-10 01:21



Sugiero usar Vladimir Keleshev pep257 Programa Python para verificar tus documentos contra PEP-257 y el Numpy Docstring Standard para describir parámetros, devoluciones, etc.

pep257 informará la divergencia que haces del estándar y se llama como pylint y pep8.


3
2017-09-11 15:34