Documentación de Funciones Python con Docstrings

Introducción

En este laboratorio, aprenderá la importancia de documentar su código Python utilizando docstrings. Exploraremos cómo acceder a los docstrings existentes para funciones integradas (built-in) utilizando la función help() y el atributo __doc__.

Además, obtendrá experiencia práctica en la escritura de sus propios docstrings para funciones personalizadas y en la verificación de su accesibilidad, haciendo que su código sea más comprensible y mantenible tanto para usted como para otros.

Acceder a la Documentación con help()

Un docstring es una cadena literal que aparece como la primera sentencia en la definición de un módulo, función, clase o método. Se utiliza para documentar lo que hace el código. La función integrada de Python help() es una herramienta excelente para ver esta documentación en un formato limpio y legible. La función help() está diseñada para uso interactivo.

Comencemos viendo la documentación de la función integrada print().

Primero, abra una terminal en el WebIDE. Puede hacerlo haciendo clic en el menú Terminal en la parte superior de la pantalla y seleccionando New Terminal.

En la terminal, inicie el shell interactivo de Python escribiendo el siguiente comando y presionando Enter:

python

Verá el prompt de Python (>>>). Ahora, use la función help() para obtener información sobre print():

help(print)

La terminal mostrará la documentación para la función print.

Help on built-in function print in module builtins:

print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
    Prints the values to a stream, or to sys.stdout by default.

    Optional keyword arguments:
    file:  a file-like object (stream); defaults to the current sys.stdout.
    sep:   string inserted between values, default a space.
    end:   string appended after the last value, default a newline.
    flush: whether to forcibly flush the stream.

(END)

Esta salida explica lo que hace la función, qué parámetros acepta y sus valores predeterminados. Presione la tecla q para salir del visor de ayuda y volver al prompt de Python.

Ahora, salga del shell interactivo de Python escribiendo:

exit()

Acceder a Docstrings Crudos con __doc__

Mientras que help() es excelente para el uso interactivo, también puede acceder al docstring crudo (raw) de un objeto programáticamente utilizando su atributo especial __doc__. Este atributo contiene el docstring como una cadena de texto simple (plain string).

Veamos esto en acción. En el explorador de archivos del WebIDE a la izquierda, busque y abra el archivo llamado access_docstring.py.

Agregue el siguiente código Python al archivo. Este código imprimirá el docstring de la función integrada len().

## This script prints the docstring of the len() function.
print(len.__doc__)

Guarde el archivo (puede usar el atajo Ctrl+S).

Ahora, regrese a la terminal y ejecute el script con el siguiente comando:

python access_docstring.py

La salida será el docstring crudo para la función len.

Return the number of items in a container.

Como puede ver, __doc__ le proporciona el contenido de cadena directo de la documentación, lo cual puede ser útil para herramientas o scripts personalizados que procesan documentación.

Escribir un Docstring de Función Personalizado

Documentar sus propias funciones es una práctica fundamental para escribir código limpio y mantenible. Un buen docstring explica el propósito de la función, sus parámetros y lo que devuelve.

Escribamos una función y documentémosla. Abra el archivo my_function.py desde el explorador de archivos.

Primero, agregue la siguiente definición de función al archivo:

def greet(name, greeting="Hello"):
    print(f"{greeting}, {name}!")

Ahora, agreguemos un docstring. El docstring debe colocarse inmediatamente después de la línea def y debe tener la misma sangría que el código de la función. Usaremos comillas triples ("""...""") para un docstring multilínea.

Modifique my_function.py para incluir el docstring. También agregaremos una línea para imprimir el docstring y verificar que funciona.

def greet(name, greeting="Hello"):
    """Greets a person with a given message.

    Args:
        name (str): The name of the person to greet.
        greeting (str, optional): The greeting message. Defaults to "Hello".
    """
    print(f"{greeting}, {name}!")

## Print the docstring of our greet function
print(greet.__doc__)

Guarde el archivo. Ahora, ejecute el script desde su terminal:

python my_function.py

Verá su docstring personalizado impreso en la consola.

Greets a person with a given message.

    Args:
        name (str): The name of the person to greet.
        greeting (str, optional): The greeting message. Defaults to "Hello".

Esto confirma que ha documentado con éxito su función y puede acceder a su docstring utilizando el atributo __doc__.

Usar help() con Su Función Personalizada

En el paso anterior, accedimos a nuestro docstring personalizado usando __doc__. Ahora, usemos la función help() para ver una vista más pulida y amigable de nuestra documentación, tal como lo hicimos con la función integrada print().

Importaremos nuestra función greet en el shell interactivo de Python para usar help().

En su terminal, inicie el shell de Python nuevamente:

python

Una vez que vea el prompt >>>, importe la función greet desde su módulo my_function (el nombre del archivo my_function.py se trata como un módulo llamado my_function).

from my_function import greet

Ahora, use help() para ver la documentación de su función greet:

help(greet)

Verá una salida bien formateada generada a partir de su docstring.

Help on function greet in module my_function:

greet(name, greeting='Hello')
    Greets a person with a given message.

    Args:
        name (str): The name of the person to greet.
        greeting (str, optional): The greeting message. Defaults to "Hello".

(END)

Observe cómo help() incluye automáticamente la firma de la función (greet(name, greeting='Hello')) y formatea el docstring para facilitar la lectura. Por eso escribir buenos docstrings es tan valioso: se integra directamente con el sistema de ayuda integrado de Python.

Presione q para salir del visor de ayuda y luego escriba exit() para abandonar el shell de Python.

Resumen

En este laboratorio, aprendió los fundamentos de la documentación del código Python mediante docstrings. Practicó el acceso a la documentación de funciones integradas utilizando la función interactiva help() y el atributo __doc__. Luego aplicó este conocimiento escribiendo sus propios docstrings de una sola línea y multilínea para una función personalizada, siguiendo las convenciones estándar. Finalmente, verificó que su documentación personalizada es accesible tanto a través de __doc__ como del sistema help() de Python, una habilidad clave para crear código legible, reutilizable y mantenible.