Saltar al contenido

Cadenas de documentos de Python – PythonForBeginners.com

¿Qué es una Docstring?

Las cadenas de documentación de Python (o cadenas de documentos) proporcionan una forma conveniente de asociar la documentación con módulos, funciones, clases y métodos de Python.

La documentación de un objeto se define mediante la inclusión de una constante de cadena como la primera declaración en la definición del objeto. Se especifica en el código fuente que se usa, como un comentario, para documentar un segmento específico de código.

A diferencia de los comentarios del código fuente convencional, la cadena de documentos debe describir qué hace la función, no cómo.

Todas las funciones deben tener una cadena de documentos. Esto permite que el programa inspeccione estos comentarios en tiempo de ejecución, por ejemplo, como un sistema de ayuda interactivo o como metadatos.

Se puede acceder a las cadenas de documentos mediante el atributo __doc__ en los objetos.

¿Cómo debería verse una Docstring?

La línea de la cadena de documentos debe comenzar con una letra mayúscula y terminar con un punto. La primera línea debe ser una descripción breve.

No escriba el nombre del objeto. Si hay más líneas en la cadena de documentación, la segunda línea debe estar en blanco, separando visualmente el resumen del resto de la descripción.

Las siguientes líneas deben ser uno o más párrafos que describan las convenciones de llamada del objeto, sus efectos secundarios, etc.

Ejemplo de cadena de documentos

Vamos a mostrar cómo un ejemplo de una cadena de documentos de varias líneas:

def my_function():
    """Do nothing, but document it.

    No, really, it doesn't do anything.
    """
    pass

Veamos cómo se vería esto cuando lo imprimimos.

>>> print my_function.__doc__
Do nothing, but document it.

    No, really, it doesn't do anything.

Declaración de cadenas de documentos

El siguiente archivo de Python muestra la declaración de cadenas de documentos dentro de un archivo fuente de Python:

"""
Assuming this is file mymodule.py, then this string, being the
first statement in the file, will become the "mymodule" module's
docstring when the file is imported.
"""
 
class MyClass(object):
    """The class's docstring"""
 
    def my_method(self):
        """The method's docstring"""
 
def my_function():
    """The function's docstring"""

Cómo acceder a Docstring

La siguiente es una sesión interactiva que muestra cómo se puede acceder a las cadenas de documentos

>>> import mymodule
>>> help(mymodule)

Suponiendo que este es el archivo mymodule.py, entonces esta cadena, siendo la primera declaración en el archivo, se convertirá en la cadena de documentos de los módulos mymodule cuando se importe el archivo.

>>> help(mymodule.MyClass)
The class's docstring

>>> help(mymodule.MyClass.my_method)
The method's docstring

>>> help(mymodule.my_function)
The function's docstring

Más lectura

Entrenamiento de Python recomendado

Para el entrenamiento de Python, nuestra principal recomendación es DataCamp.