Tutorial Python Docstrings : Ejemplos y Formato de Cadenas Doc Pydoc, Numpy, Sphinx

Si te estás iniciando en Python y quieres aprender más, sigue el curso Introducción a la Ciencia de Datos en Python de DataCamp.

Practica Docstrings en Python con este ejercicio práctico.

¿Qué son las Docstrings de Python? 

La cadena de documentación de Python, comúnmente conocida como docstring, es un literal de cadena, y se utiliza en la definición de clases, módulos, funciones o métodos. Las docstrings son accesibles desde el atributo doc (__doc__) para cualquiera de los objetos Python y también con la función incorporada help(). El docstring de un objeto se define incluyendo una constante de cadena como primera declaración en la definición del objeto.

A diferencia de los comentarios normales, que explican líneas individuales de código, las docstrings proporcionan descripciones de alto nivel de lo que hace una función, clase o módulo. Los docstrings bien escritos mejoran la legibilidad del código, su mantenimiento y la colaboración, lo que los convierte en una práctica recomendada para documentar tu código Python como desarrollador de Python.

Los Docstrings te ayudan a comprender las capacidades de un módulo o una función. Por ejemplo, supongamos que has instalado la biblioteca scikit-learn, y quieres saber todo sobre el paquete sklearn, como la descripción, los módulos del paquete, etc., sólo tienes que utilizar la función help para obtener toda la información.

Vamos a importar rápidamente el paquete.

import sklearn

help(sklearn)

Verás un resultado similar al que se muestra a continuación:

Docstrings Python vs. Docstrings Python Comentando

Las docstrings son similares en espíritu a los comentarios, pero son versiones mejoradas, más lógicas y útiles de los comentarios. Las docstrings actúan como documentación de la clase, el módulo y los paquetes.

Por otro lado, los Comentarios se utilizan principalmente para explicar partes no evidentes del código y pueden ser útiles para comentar la corrección de errores y las tareas pendientes.

Las cadenas de texto se representan con comillas de cierre y apertura, mientras que los comentarios comienzan con un # al principio.

Ten en cuenta que no se puede acceder a los comentarios con el atributo incorporado doc y la función help. Veamos qué ocurre si intentas hacerlo:

def string_reverse(str1):
    #Returns the reversed String.

    #Parameters:
    #    str1 (str):The string which is to be reversed.

    #Returns:
    #    reverse(str1):The string which gets reversed.   

    reverse_str1 = ''
    i = len(str1)
    while i > 0:
        reverse_str1 += str1[i - 1]
        i = i- 1
    return reverse_str1

print(string_reverse.__doc__)

None

help(string_reverse)

Help on function string_reverse in module __main__:

string_reverse(str1)

Hay un par de formas de escribir o utilizar una Docstring, a saber: one-line docstring y multi-line docstring. Aprendámoslos uno a uno.

Docstring de una línea

Las docstrings de una línea son descripciones breves que caben en una sola línea. Van entre comillas triples (''' o """), y las comillas de cierre deben estar en la misma línea.

Aunque tanto las comillas triples simples como las triples dobles funcionan, la convención estándar en Python es utilizar las comillas triples dobles (""").

He aquí un ejemplo: 

def square(a):
    """Returns the square of the given number."""
    return a ** 2  # Corrected exponentiation

# Accessing the docstring
print(square.__doc__)

Salida:

Returns the square of the given number.

También puedes recuperar esta documentación utilizando la función help() de Python:

help(square)

Salida:

Help on function square in module __main__:

square(a)
    Returns the square of the given number.

Docstring multilínea

Las Docstrings de varias líneas también contienen la misma línea de literales de cadena que las Docstrings de una línea, pero va seguida de un único espacio en blanco junto con el texto descriptivo.

El formato general para escribir una Docstring multilínea es el siguiente:

def some_function(argument1):
    """Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

   """

    return argument1

print(some_function.__doc__)

Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

help(some_function)

Help on function some_function in module __main__:

some_function(argument1)
    Summary or Description of the Function

    Parameters:
    argument1 (int): Description of arg1

    Returns:
    int:Returning value

Veamos el ejemplo que puede mostrar en detalle cómo se pueden utilizar las cadenas multilínea:

def string_reverse(str1):
    '''
    Returns the reversed String.

    Parameters:
        str1 (str):The string which is to be reversed.

    Returns:
        reverse(str1):The string which gets reversed.   
    '''

    reverse_str1 = ''
    i = len(str1)
    while i > 0:
        reverse_str1 += str1[i - 1]
        i = i- 1
    return reverse_str1

print(string_reverse('DeepLearningDataCamp'))

pmaCataDgninraeLpeeD

help(string_reverse)

Help on function string_reverse in module __main__:

string_reverse(str1)
    Returns the reversed String.

    Parameters:
        str1 (str):The string which is to be reversed.

    Returns:
        reverse(str1):The string which gets reversed.

Puedes ver arriba que la línea de resumen está en una sola línea y también está separada del resto del contenido por una sola línea en blanco. Hay que seguir esta convención, que es útil para las herramientas de indexación automática.

Docstring incorporado en Python

Veamos los Docstrings de Python incorporados.

Todas las funciones, clases y métodos incorporados tienen adjunta la descripción humana real. Puedes acceder a él de dos formas.

• atributo doc
• La función de ayuda

Observarás que la salida de la función help es más verbosa que la del atributo __doc__.

Por ejemplo:

import math
print(math.__doc__)

This module provides access to the mathematical functions
defined by the C standard.

Del mismo modo, puedes utilizar la función de ayuda:

help(math)

Python Docstring en las clases

En la definición de una clase, se puede utilizar un docstring para proporcionar documentación sobre la clase en su conjunto. Normalmente se coloca inmediatamente después de la definición de la clase, y va entre comillas triples ("""). Por ejemplo:

class MyClass:
    """This is the documentation for MyClass."""

    def __init__(self):
        """This is the documentation for the __init__ method."""
        pass

Se puede acceder a las docstrings mediante el atributo __doc__ de la clase o método. Por ejemplo, podrías acceder al docstring de MiClase utilizando MyClass.__doc__.

Veamos ahora algunos Formatos Docstring populares y entendámoslos en detalle.

Formatos Docstring de Python

Hay muchos formatos de Docstrings disponibles, pero siempre es mejor utilizar los formatos que reconoce fácilmente el analizador sintáctico de Docstrings y también los compañeros Científicos de Datos/programadores. No hay reglas ni normas para seleccionar un formato Docstring, pero es necesario que haya coherencia a la hora de elegir el mismo formato a lo largo del proyecto. Además, es preferible que utilices el tipo de formato que Sphinx admite mayoritariamente.

A continuación se enumeran los formatos más utilizados.

Puede haber diferentes cadenas de documentación disponibles. No debes preocuparte por el hecho de tener que reinventar la rueda para estudiarlo todo. Los formatos de todas las cadenas de Documentación son casi similares. Los patrones son similares, pero sólo hay cambios de fondo en cada formato. Revisarás el ejemplo de un formato popular de cadena de documentación disponible con su uso.

Al principio, verás el Estilo Esfinge en detalle, y luego podrás seguirlo fácilmente también con otros formatos.

Estilo Esfinge

Sphinx es el estilo fácil y tradicional, verborreico, y fue creado inicialmente específicamente para la documentación de Python. Sphinx utiliza un Texto Reestructurado, cuyo uso es similar al de Markdown.

class Vehicle(object):
    '''
    The Vehicle object contains lots of vehicles
    :param arg: The arg is used for ...
    :type arg: str
    :param `*args`: The variable arguments are used for ...
    :param `**kwargs`: The keyword arguments are used for ...
    :ivar arg: This is where we store arg
    :vartype arg: str
    '''


    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance, destination):
        '''We can't travel a certain distance in vehicles without fuels, so here's the fuels

        :param distance: The amount of distance traveled
        :type amount: int
        :param bool destinationReached: Should the fuels be refilled to cover required distance?
        :raises: :class:`RuntimeError`: Out of fuel

        :returns: A Car mileage
        :rtype: Cars
        '''  
        pass

Sphinx utiliza el keyword(reserved word); la mayor parte del lenguaje de programación lo hace. Pero en Sphinx se llama explícitamente role. En el código anterior, Sphinx tiene el rol param, y type es un rol, que es el tipo de datos de Sphinx para param. El rol type es opcional, pero param es obligatorio. Las funciones devueltas documentan el objeto devuelto. Es diferente de la función param. El rol de retorno no depende del rtype y viceversa. El rtype es el tipo de objeto devuelto por la función dada.

Google Style

Google Style es más fácil e intuitivo de usar. Puede utilizarse para la forma más breve de documentación. Es necesario configurar un archivo python para empezar, por lo que tienes que añadir sphinx.ext.napoleon o sphinxcontrib.napoleon a la lista de extensiones en conf.py.

class Vehicles(object):
    '''
    The Vehicle object contains a lot of vehicles

    Args:
        arg (str): The arg is used for...
        *args: The variable arguments are used for...
        **kwargs: The keyword arguments are used for...

    Attributes:
        arg (str): This is where we store arg,
    '''
    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance,destination):
        '''We can't travel distance in vehicles without fuels, so here is the fuels

        Args:
            distance (int): The amount of distance traveled
            destination (bool): Should the fuels refilled to cover the distance?

        Raises:
            RuntimeError: Out of fuel

        Returns:
            cars: A car mileage
        '''
        pass

El estilo Google es mejor que el estilo Esfinge. También tiene un inconveniente, es decir, en el código anterior, la descripción multilínea de la distancia quedaría desordenada. Por eso el Numpy puede utilizarse para la forma más extendida de documentación.

Estilo Numpy

El estilo Numpy tiene muchos detalles en la documentación. Es más prolija que otras documentaciones, pero es una opción excelente si quieres hacer una documentación detallada, es decir, una amplia documentación de todas las funciones y parámetros.

class Vehicles(object):
    '''
    The Vehicles object contains lots of vehicles

    Parameters
    ----------
    arg : str
        The arg is used for ...
    *args
        The variable arguments are used for ...
    **kwargs
        The keyword arguments are used for ...

    Attributes
    ----------
    arg : str
        This is where we store arg,
    '''
    def __init__(self, arg, *args, **kwargs):
        self.arg = arg

    def cars(self, distance, destination):
        '''We can't travel distance in vehicles without fuels, so here is the fuels

        Parameters
        ----------
        distance : int
            The amount of distance traveled
        destination : bool
            Should the fuels refilled to cover the distance?

        Raises
        ------
        RuntimeError
            Out of fuel

        Returns
        -------
        cars
            A car mileage
        '''
        pass

El ejemplo anterior es más prolijo que cualquier otra documentación. Es más largo y sólo podría utilizarse para la documentación larga y detallada.

PyDoc

Como ya has aprendido, los docstrings son accesibles a través del atributo incorporado de Python __doc__ y de la función help(). También puedes utilizar el módulo integrado conocido como Pydoc, que es muy diferente en cuanto a las características y funcionalidades que posee en comparación con el atributo doc y la función de ayuda.

Pydoc es una herramienta que te resultará útil cuando quieras compartir el código con tus colegas o hacerlo de código abierto, en cuyo caso te dirigirás a un público mucho más amplio. Puede generar páginas web a partir de tu documentación en Python y también puede lanzar un servidor web.

Veamos cómo funciona.

La forma más fácil y cómoda de ejecutar el módulo Pydoc es ejecutarlo como un script. Para ejecutarlo dentro de la celda jupyter lab, utilizarías el carácter de exclamación (!).

• Pydoc como módulo

!python -m pydoc

pydoc - the Python documentation tool

pydoc <name> ...
    Show text documentation on something.  <name> may be the name of a
    Python keyword, topic, function, module, or package, or a dotted
    reference to a class or function within a module or module in a
    package.  If <name> contains a '\', it is used as the path to a
    Python source file to document. If name is 'keywords', 'topics',
    or 'modules', a listing of these things is displayed.

pydoc -k <keyword>
    Search for a keyword in the synopsis lines of all available modules.

pydoc -n <hostname>
    Start an HTTP server with the given hostname (default: localhost).

pydoc -p <port>
    Start an HTTP server on the given port on the local machine.  Port
    number 0 can be used to get an arbitrary unused port.

pydoc -b
    Start an HTTP server on an arbitrary unused port and open a Web browser
    to interactively browse documentation.  This option can be used in
    combination with -n and/or -p.

pydoc -w <name> ...
    Write out the HTML documentation for a module to a file in the current
    directory.  If <name> contains a '\', it is treated as a filename; if
    it names a directory, documentation is written for all the contents.

Si te fijas en la salida anterior, el primer uso de Pydoc es mostrar documentación de texto sobre una función, módulo, clase, etc., así que vamos a ver cómo puedes aprovechar eso mejor que la función de ayuda.

!python -m pydoc glob

Help on module glob:

NAME
    glob - Filename globbing utility.

MODULE REFERENCE
    https://docs.python.org/3.7/library/glob

    The following documentation is automatically generated from the Python
    source files.  It may be incomplete, incorrect or include features that
    are considered implementation detail and may vary between Python
    implementations.  When in doubt, consult the module reference at the
    location listed above.

FUNCTIONS
    escape(pathname)
        Escape all special characters.

    glob(pathname, *, recursive=False)
        Return a list of paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

    iglob(pathname, *, recursive=False)
        Return an iterator which yields the paths matching a pathname pattern.

        The pattern may contain simple shell-style wildcards a la
        fnmatch. However, unlike fnmatch, filenames starting with a
        dot are special cases that are not matched by '*' and '?'
        patterns.

        If recursive is true, the pattern '**' will match any files and
        zero or more directories and subdirectories.

DATA
    __all__ = ['glob', 'iglob', 'escape']

FILE
    c:\users\hda3kor\.conda\envs\test\lib\glob.py

Ahora, vamos a extraer la documentación de glob utilizando la función de ayuda.

help(glob)

---------------------------------------------------------------------------

NameError                                 Traceback (most recent call last)

<ipython-input-6-6f504109e3a2> in <module>
----> 1 help(glob)


NameError: name 'glob' is not defined

Pues bien, como puedes ver, arroja un error de nombre, ya que glob no está definido. Por tanto, para que puedas utilizar la función de ayuda para extraer la documentación, primero tienes que importar ese módulo, cosa que no ocurre en Pydoc.

• Pydoc como servicio web

Vamos a explorar la característica más interesante del módulo Pydoc, es decir, ejecutar Pydoc como un servicio web.

Para ello, basta con ejecutar el Pydoc como un script, pero con un argumento -b que iniciará un servidor HTTP en un puerto arbitrario no utilizado y abrirá un navegador Web para navegar interactivamente por la documentación. Esto es útil, sobre todo cuando tienes otros servicios funcionando en tu sistema, y no recuerdas qué puerto estaría en estado inactivo.

!python -m pydoc -b

^C

En el momento en que ejecutes la celda anterior, se abrirá una nueva ventana en un número de puerto arbitrario, y el navegador web tendrá un aspecto similar al que se muestra a continuación.

Veamos la documentación del módulo h5py, que es un formato de archivo utilizado para almacenar pesos de la arquitectura de redes neuronales.

Comparación de formatos docstring 

En la tabla siguiente, puedes ver una comparación de los distintos tipos de formatos docstring que hemos mencionado anteriormente: 

• Estilo Esfinge: Suele utilizarse en grandes proyectos en los que se requiere una documentación exhaustiva. Se integra bien con el generador de documentación de Sphinx.
• Google Style: Ideal para proyectos en los que se prioriza la sencillez y la legibilidad, especialmente en organizaciones que utilizan las guías de estilo de Google.
• Estilo NumPy: El más adecuado para proyectos que requieren una documentación detallada y extensa, habitual en la ciencia de datos y la informática científica.
• PyDoc: Útil para generar documentación de texto y HTML, pero carece del formato estructurado de otros.

Conclusión

Enhorabuena por terminar el tutorial de docstring en Python.

Este tutorial se centra principalmente en iniciarte en el uso de docstrings, cubriendo los temas esenciales. Sin embargo, Docstrings es un tema muy amplio, y es posible que algunos conceptos hayan quedado sin explorar. Si quieres saber más, consulta nuestro tutorial sobre cadenas en Python y nuestro curso sobre cómo escribir funciones en Python.

Si te estás iniciando en Python y quieres aprender más, sigue el curso Introducción a la Ciencia de Datos en Python de DataCamp. También puedes seguir uno de nuestros itinerarios profesionales de Python y comenzar tu viaje para convertirte en Desarrollador Python o Científico de Datos con Python.