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 *