Cadenas de documentos de Python

    Como ya se señaló en un artículo anterior titulado Comentar el código de Python, ha aprendido que la documentación es un paso esencial y continuo en el proceso de desarrollo de software. El artículo mencionado anteriormente presentó brevemente el concepto de cadenas de documentos, 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 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 utilizan en la práctica, seguidos del acceso a una cadena de documentos desde su secuencia de comandos de Python. Y por último, le presentamos una serie de herramientas para utilizar y evaluar cadenas de documentos.

    Bucear en Docstrings

    El término docstring es una abreviatura de cadena de documentación 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 tiene el siguiente aspecto 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 Python con una cadena de documentos de una sola línea

    class Device:
        def __init__(self, temp=0.0):
            "Initialize the Device object with the given temperature value."
            
            self.set_temperature(temp)
            return
    

    Para escribir correctamente una cadena de documentos, siga una serie de convenciones. Estas convenciones se explican con más detalle en la PEP 257, que son las siglas de Python Enhancement Proposal.

    Docstrings de una sola línea

    Debido a la simplicidad, la cadena de documentos utilizada en el Listado 1 viene como un comentario de una sola línea. Recuerde comenzar el texto de una cadena de documentos con una letra mayúscula y terminarlo con un punto. Basado en el hecho de que el código generalmente 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:

        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 cotizaciones finales estén en la misma línea que las cotizaciones iniciales. Además, no agregue líneas vacías antes o después del texto de la cadena de documentos.

    Docstrings multilínea

    Además, una cadena de documentos 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 documentos debe escribirse en comillas triples simples o dobles, y la estructura de la cadena de documentos en sí tiene un significado más profundo que se asigna a todo el texto.

    La primera línea de la cadena de documentos se interpreta como un resumen o una descripción breve, y se recomienda que se escriba de la misma manera que una cadena de documentos de una sola línea. Una línea vacía que sigue 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

    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 de la cadena de documentos 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 cadenas de documentos

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

    • texto reestructurado (descanso) / Esfinge: Este es el estándar de documentación oficial de Python. Utiliza la sintaxis del texto reestructurado del lenguaje de marcado ligero (reST) que es similar en uso a Markdown.
    • Google Docstrings: Estilo de cadena de documentos de Google
    • NumPy /Ciencia Docstrings: una combinación de texto reestructurado (reST) y Google Docstrings. Utilizable también por Sphinx, y bastante detallado.

    El Listado 3 muestra cómo escribir la cadena de documentos usando reST. Las palabras clave que puede 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
    • .. seealso::: Otras lecturas
    • .. notes::: Agrega una nota
    • .. warning::: Agregar una advertencia

    El orden de las entradas no es fijo, pero sigue el mismo orden durante todo el proyecto. Las entradas para seealso, notesy warning son opcionales.

    Listado 3: cadena de documentos de varias líneas con datos reST

    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)

    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, el Listado 5 muestra el mismo método en formato de cadena de documentos 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)

    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
    

    Accediendo a Docstrings

    En el sistema de ayuda interactiva de Python, la cadena de documentos está disponible a través del __doc__ atributo. 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: Accediendo al valor de la cadena de documentos

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

    Hay una serie de herramientas que generan automáticamente documentación a partir de cadenas de documentos, como Sphinx, Epydoc, Doxygen, PyDoc, pdoc, y el autodoc 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 deriva información sobre un módulo para la consola, un navegador web o como un documento HTML. Dentro del shell de Python use el help() función para aprender más sobre un módulo, función, clase o método. La Figura 1 muestra la cadena de documentos del Listado 1 a través del sistema de ayuda de Python.

    Figura 1: La cadena de documentos extraída

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

    Listado 7: Ejecución de pydoc como servidor web

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

    Figura 2: la cadena de documentos extraída en un servidor web local

    Conclusión

    Seguir las pautas para la documentación le ayudará a usted y a otras personas a comprender el código fuente hoy y en el futuro. Las cadenas de documentos se utilizan para más que eso, por ejemplo, para la generación de manuales. Esta idea en mente permite proyectos a mayor escala.

     

    Etiquetas:

    Deja una respuesta

    Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *