Tutorial de Docstrings 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.

Practica Docstrings en Python con este ejercicio práctico.

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 integrada help(). La docstring de un objeto se define incluyendo una constante de cadena como primera sentencia en la definición del objeto.

Las docstrings son estupendas para comprender la funcionalidad de la mayor parte del código, es decir, la finalidad general de cualquier clase, módulo o función, mientras que los comentarios se utilizan para código, sentencias y expresiones, que suelen ser pequeños. Son textos descriptivos escritos por un programador principalmente para que él mismo sepa lo que hace la línea de código o expresión y también para el desarrollador que desee contribuir a ese proyecto. Es una parte esencial porque documentar tu código Python sirve para escribir código limpio y programas bien escritos.

Las 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.: solo 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 de Python frente a comentarios

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 que hay que hacer.

Las Docstrings se representan con comillas de cierre y apertura, mientras que los comentarios comienzan con #.

Ten en cuenta que no se puede acceder a los comentarios con el atributo integrado 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: docstring one-line y docstring multi-line. Aprendámoslas una a una.

Docstring de una línea

Las Docstrings de una línea son las Docstrings que caben enteras en una línea. Puedes utilizar una de las comillas (es decir, triple simple o triple doble) y las comillas de apertura y las de cierre tienen que ser iguales. En las Docstrings de una línea, las comillas de cierre van en la misma línea que las de apertura. Además, la convención estándar es utilizar las comillas triples dobles.

def square(a):
    '''Returned argument a is squared.'''
    return a**a

print (square.__doc__)

Returned argument a is squared.

help(square)

Help on function square in module __main__:

square(a)
    Returned argument a is squared.

En la salida Docstring anterior, puedes observar que:

• En este caso, la línea comienza con una letra mayúscula (es decir, R) y termina con un punto (.).
• Las comillas de cierre están en la misma línea que las de apertura. Esto parece mejor para las de una sola línea.
• Una práctica recomendada es no dejar ninguna línea en blanco ni antes ni después de la Docstring, como se muestra en el ejemplo anterior.
• La salida del atributo __doc__ es menos prolija que la de la función help().

Docstring multilínea

Las Docstrings multilínea 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 en detalle el ejemplo que puede mostrar 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 integrada en Python

Veamos las Docstrings integradas en Python.

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

• Atributo doc
• Función de ayuda

Observarás que la salida de la función help es más prolija 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)

Docstring de Python en clases

En la definición de clase se puede utilizar una docstring para proporcionar documentación sobre la clase en su conjunto. Normalmente se coloca justo después de la definición de 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 a la docstring de MyClass utilizando MyClass.__doc__.

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

Formatos de Docstring de Python

Hay muchos formatos de Docstrings disponibles, pero siempre es mejor utilizar los formatos que reconocen fácilmente el analizador de Docstrings y también los compañeros científicos de datos/programadores. No hay reglas ni normas para seleccionar un formato de Docstring, pero es necesario elegir el mismo formato a lo largo del proyecto. Además, es preferible que utilices el tipo de formato que Sphinx admite en la mayoría de los casos.

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

Puede haber diferentes cadenas de documentación disponibles. No debes preocuparte por tener que reinventar la rueda para estudiarlo todo. Los formatos de todas las cadenas de documentación son similares. Los patrones son similares, pero hay cambios esenciales 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 seguir fácilmente con otros formatos.

Estilo Sphinx

Sphinx es el estilo fácil y tradicional, prolijo, y fue creado inicialmente de forma específica para la documentación de Python. Sphinx utiliza ReStructuredText, 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 keyword(reserved word); casi todos los lenguajes de programación lo hacen. Sin embargo, 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 de devolución documentan el objeto devuelto. Es diferente del rol param. El rol de devolución no depende de rtype, y viceversa. rtype es el tipo de objeto devuelto por la función dada.

Estilo Google

El estilo Google es más fácil 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 Sphinx. También tiene un inconveniente: en el código anterior, la descripción multilínea de la distancia quedaría desordenada. Por eso 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 prolijo 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 solo podría utilizarse para la documentación larga y detallada.

PyDoc

Como ya has aprendido, las docstrings son accesibles a través del atributo integrado 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 funciones que posee, del 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 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 script. Para ejecutarlo dentro de la celda JupyterLab, utilizarías el carácter de cierre 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 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

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 servicio web.

Para ello, basta con ejecutar Pydoc como 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 ejecutándose en tu sistema y no recuerdas qué puerto está 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.

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, las Docstrings son 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.