Cadenas de documentación de Python

Como ya se señaló en un artículo anterior titulado Comentando el código de Python, ha aprendido que la documentación es un paso esencial y continuo en el pro...

Como ya se señaló en un artículo anterior titulado Comentando el código de Python has aprendido que la documentación es un paso esencial y continuo en el proceso de desarrollo de software. El artículo mencionado anteriormente introdujo brevemente el concepto de docstrings, que es una forma de crear documentación para su código Python desde dentro del código. Esta documentación en código funciona para módulos, clases, métodos y funciones, y es la forma preferida de documentar todo el código de Python.

Hay mucho más, y es por eso que veremos más de cerca este tema en este artículo. Cubriremos las convenciones sobre cómo escribir cadenas de documentos correctamente, así como varios formatos de cadenas de documentos que se usan en la práctica, y luego accederemos a una cadena de documentos desde su secuencia de comandos de Python. Y, por último, le presentaremos una serie de herramientas para usar y evaluar docstrings.

Inmersión en Docstrings

El término docstring es una abreviatura de documentation string y describe su código fuente, es decir, lo que hace su función, módulo o clase. Se agrega como un comentario regular justo debajo del encabezado de una función, módulo, clase o método.

Un ejemplo típico es el siguiente y se toma de una clase de Python para trabajar con un dispositivo de medición como un sensor móvil para medir la temperatura, la humedad y la velocidad del viento.

Listado 1: código de Python con una cadena de documentación de una sola línea

1
2
3
4
5
6
class Device:
    def __init__(self, temp=0.0):
        "Initialize the Device object with the given temperature value."
        
        self.set_temperature(temp)
        return

Para escribir una cadena de documentos correctamente, siga una serie de convenciones. Estas convenciones se explican con más detalle en PEP 257, que significa Propuesta de mejora de Python.

Cadenas de documentos de una sola línea

Debido a la simplicidad, la cadena de documentación utilizada en Listado 1 viene como un comentario de una sola línea. Recuerde comenzar el texto de una cadena de documentación con una letra mayúscula y terminarlo con un punto. Basado en el hecho de que el código normalmente se lee con más frecuencia de lo que se escribe, se recomienda describir lo que hace la estructura documentada como una especie de comando en lugar de cómo se hace. Mencionar qué tipo de valor se devuelve a la persona que llama ayuda a comprender el resultado de la función o método.

Es posible que haya notado que la cadena de documentación del método del Listado 1 está enmarcada entre comillas dobles simples. Bueno, siempre que las comillas iniciales y finales sean similares, Python es bastante tolerante, y también se le permite usar tres comillas simples y tres comillas dobles en su lugar:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
    def get_temperature(self):
        '''Return the stored temperature value as a float value.'''

        return self.temperature
    
    def set_temperature(self, temp):
        """Set the temperature value."""

        self.temperature = float(temp)
        return

Asegúrese de que las comillas de cierre estén en la misma línea que las comillas de apertura. Además, no agregue líneas vacías antes o después del texto de la cadena de documentación.

Cadenas de documentación multilínea {#cadenas de documentación multilínea}

Además, una cadena de documentación también se puede escribir como un comentario de varias líneas. Cuando se utilizan comentarios de varias líneas, dos cosas cambian: la encapsulación de la cadena de documentación debe escribirse entre comillas simples o dobles triples, y la estructura de la cadena de documentación en sí tiene un significado más profundo que se asigna a todo el texto.

La primera línea de la cadena de documentación se interpreta como un resumen o una descripción breve, y se recomienda escribirla de la misma manera que una cadena de documentación de una sola línea. Una línea vacía a continuación se interpreta como un separador entre el resumen y la descripción completa a continuación. El Listado 2 amplía el Listado 1 y no utiliza un formato específico para la descripción, como se menciona a continuación.

Listado 2: Cadena de documentos de varias líneas

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
def set_temperature(self, temp):
    """Set the temperature value.

    The value of the temp parameter is stored as a value in
    the class variable temperature. The given value is converted
    into a float value if not yet done.
    """

    self.temperature = float(temp)
    return

Se recomienda encarecidamente seguir la estructura docstring para cadenas de varias líneas, ya que las herramientas de indexación automatizadas evalúan estos textos y, por lo tanto, confían en el cumplimiento del orden de bloqueo.

Formatos de cadena de documentación {#formatos de cadena de documentación}

Es de esperar que solo haya un formato de cadena de documentación vinculante. Desafortunadamente, hay más de uno, y todas estas variantes de formato funcionan con cadenas de documentos de varias líneas.

  • texto reestructurado (reST) / Sphinx: Esta es la versión oficial Documentación estándar de Python. Utiliza la sintaxis del texto reestructurado del lenguaje de marcado ligero (reST), que es similar en uso a Reducción.
  • Cadenas de documentación de Google: estilo de docstring de Google
  • NumPy/SciPy Docstrings: una combinación de texto reestructurado (reST) y Google Docstrings. Usable por Sphinx también, y bastante detallado.

Listado 3 muestra cómo escribir la cadena de documentación usando reST. Las palabras clave que puedes utilizar son las siguientes:

  • param y type: Parámetro y su tipo de variable
  • return y rtype: especifique tanto el valor de retorno como el tipo de función o método
  • .. ver también::: Lecturas adicionales
  • .. notas::: Añadir una nota
  • .. advertencia::: Agregar una advertencia

El orden de las entradas no es fijo, pero respete el mismo orden a lo largo de todo el proyecto. Las entradas para ver también, notas y advertencia son opcionales.

Listado 3: Cadena de documentación multilínea con datos reST

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
def set_temperature(self, temp):
    """Set the temperature value.

    The value of the temp parameter is stored as a value in
    the class variable temperature. The given value is converted
    into a float value if not yet done.

    :param temp: the temperature value
    :type temp: float
    :return: no value
    :rtype: none
    """

    self.temperature = float(temp)
    return

Para comprender las cadenas de documentación de Google, puede echar un vistazo al Listado 4. El formato es menos denso y utiliza más espacio horizontal.

Listado 4: Cadena de documentos de varias líneas (formato de Google)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
def set_temperature(self, temp):
    """Set the temperature value.

    The value of the temp parameter is stored as a value in
    the class variable temperature. The given value is converted
    into a float value if not yet done.

    Args:
        temp (float): the temperature value

    Returns:
        no value
    """

    self.temperature = float(temp)
    return

Finalmente, Listado 5 muestra el mismo método en formato docstring NumPy. Utiliza más espacio vertical y parece más fácil de leer que el formato original.

Listado 5: Cadena de documentos de varias líneas (formato NumPy)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
def set_temperature(self, temp):
    """Set the temperature value.

    The value of the temp parameter is stored as a value in
    the class variable temperature. The given value is converted
    into a float value if not yet done.

    Parameters
    ----------
    temp : float
        the temperature value

    Returns
    -------
    no value
    """

    self.temperature = float(temp)
    return

Acceso a cadenas de documentos {#acceso a cadenas de documentos}

En el sistema de ayuda interactivo de Python, la cadena de documentación está disponible a través del atributo __doc__. El Listado 6 muestra cómo usar el código para acceder a la cadena de documentación, que en nuestro ejemplo se basa en el Listado 1.

Listado 6: Acceso al valor de la cadena de documentación

1
2
3
4
5
6
7
>>> def set_temperature (self, temp):
...     """Set the temperature value."""
...     temperature = float(temp)
...     return
... 
>>> print(set_temperature.__doc__)
Set the temperature value.

Herramientas para usar las cadenas de documentos {#herramientas para usar las cadenas de documentos}

Hay una serie de herramientas que generan documentación automáticamente a partir de cadenas de documentación, como Sphinx, Epydoc, doxígeno, PyDoc, pdoc y [autodoc](http:/ /www.sphinx-doc.org/en/master/usage/extensions/autodoc.html) extensión para Sphinx. La mayoría de ellos generan documentos HTML para uso local.

Pydoc es parte de la distribución de Python y obtiene información sobre un módulo para la consola, un navegador web o como un documento HTML. Dentro del shell de Python, use la función help() para obtener más información sobre un módulo, función, clase o método. La Figura 1 muestra el docstring del Listado 1 a través del Sistema de ayuda de Python.

Figura 1: La cadena de documentación extraída

pydoc python shell{.img-responsive}

Para ver la documentación integrada de todos los módulos de Python que están instalados localmente, puede ejecutar pydoc como un servidor web local. El uso del parámetro -p seguido del número de puerto inicia un pequeño servidor web al que se puede acceder mediante el puerto dado. Listado 7 inicia el servidor pydoc en el puerto 1234, y la Figura 2 muestra la información extraída y puesta a disposición por pydoc.

Listado 7: Ejecutando pydoc como un servidor web

1
2
3
4
5
$ pydoc3 -p 1234
Server ready at http://localhost:1234/
Server commands: [b]rowser, [q]uit
server>
...

Figura 2: La cadena de documentación extraída en un servidor web local

pydoc{.img-responsive}

Conclusión

Seguir las pautas para la documentación lo ayuda a usted y a otros a comprender el código fuente hoy y en el futuro. Los docstrings se utilizan para más que eso, por ejemplo, para la generación de manuales. Esta idea en mente permite proyectos a mayor escala.

Licensed under CC BY-NC-SA 4.0