Documentación en Python con docstrings y PEP 257

Clase 15 de 25 • Curso de Python Intermedio para Entornos virtuales y PEP8

Resumen

La documentación en Python no es un lujo: es una herramienta para leer y entender tu propio código en el futuro. Con docstrings bien escritos, podrás saber qué hace cada función o clase sin adivinar. Aquí verás cómo usar las tres comillas, qué indica el PEP 257, cómo consultar la ayuda con doc y help, y cómo apoyarte en IA para documentar rápido y bien.

¿Qué es un docstring en Python y por qué documentar código?

Documentar evita confusiones al releer código. La mayoría de las veces no vuelves a cambiar el código: lo vuelves a leer. Un docstring es un texto entre tres comillas que describe módulos, funciones o clases.

Tres comillas permiten múltiples líneas en una sola cadena de texto.
Cada archivo puede empezar con un docstring de módulo claro.
Funciones y clases deben tener docstrings que expliquen propósito y uso.

¿Cómo iniciar con triple comillas?

"""
Explicación de docstrings en Python.
Permite escribir documentación multilínea para archivos, funciones y clases.
"""

# Ejemplo sin docstring
def saludo():
    return "Hola"

# Ejemplo con docstring
def saludo_doc():
    """Esta función devuelve un saludo.

    Retorno:
        str: un saludo en español.
    """
    return "Hola"

Usa múltiples líneas para dar claridad.
Evita textos crípticos: sé directo y específico.

¿Cómo se escriben y consultan docstrings según PEP 257?

El PEP 257 propone la anatomía de una buena documentación. Empieza con una descripción corta, luego opcionalmente una explicación larga, parámetros, retorno, excepciones y ejemplos. Además, puedes consultar esa ayuda desde consola o el editor.

¿Cómo estructurar el docstring según PEP 257?

def limpiar_texto(texto: str) -> str:
    """Limpia y normaliza el texto removiendo espacios y convirtiendo a minúsculas.

    Descripción:
        esta función toma la cadena de texto y realiza operaciones de limpieza.

    Parámetros:
        texto (str): cadena de texto que se va a limpiar y normalizar.

    Retorno:
        str: texto limpio y normalizado.

    Excepciones:
        TypeError: si texto no es de tipo str.

    Ejemplos:
        >>> limpiar_texto("  Hola, mundo  ")
        'hola, mundo'
    """
    if not isinstance(texto, str):
        raise TypeError("texto debe ser str")
    return texto.strip().lower()

Tipos explícitos ayudan al editor y a quien lee (ver typing y anotaciones como texto: str y -> str).
Ejemplos tipo doctest (>>>) muestran entradas y salidas esperadas.

¿Cómo consultar la documentación en consola y editor?

print(saludo_doc.__doc__)   # Accede al atributo protegido __doc__
help(saludo_doc)            # Abre la guía interactiva; presiona Q para salir

Con __doc__ obtienes el texto del docstring directamente.
Con help() ves firma, retorno y la ayuda completa.
En el editor, al pasar el cursor, se muestra la firma, el retorno y la documentación con tipos.

¿Cómo usar IA y buenas prácticas para documentar?

Puedes aprovechar Cloud Code u otro entorno para pedir a un LLM que redacte docstrings completos. Proporciona el código y el contexto del PEP 257 para que genere descripción, parámetros, retorno, excepciones y ejemplos en español cuando lo necesites.

¿Qué prompt usar para generar un docstring?

Genera un docstring completo en español. Sigue el PEP 257 para esta función.
Incluye: descripción, parámetros, retorno, excepciones y ejemplos.

Recomendación general: se sugiere inglés, pero usar español facilita para hispanohablantes.
Verifica la salida: debe reflejar lo que realmente hace la función.

¿Qué buenas prácticas elevan la calidad?

Sé conciso y claro: pide menos relleno y más precisión.
Mantén la documentación actualizada: ajusta cuando cambie la funcionalidad.
Documenta ejemplos: facilitan entender el comportamiento real.

¿Ya documentaste tus funciones del curso? Comparte en comentarios tus técnicas y los prompts que mejor te funcionan para generar docstrings útiles y consistentes.

Samuel Steven Bernal Martínez

student•

Normalmente en un entorno real se documentan al completo todas las funciones o su mayoría? o normalmente se documenta solo las que son "difíciles" o que puedan confundir?, o quiza se documenta parcialmente y solo a las que son dificiles se le agrega todo lo de PEP 257, me gustaría saber eso de cara a proyectos reales.

Cesar Augusto Mora Castilo

student•

Por experiencia propia le puedo sugerir que lo mejor es documentar todo, porque pasa que luego de unas semanas o meses uno olvida detalles de la implementación del código, además se documenta pensando en el futuro (mejoras, escalado), y en otros programadores que pudieran tener que trabajar con ese código y tengan más fácil el trabajo de comprenderlo.

Juan David Santamaria Gomez

student•

Lo mejor es dejar siempre documentado todo el codigo, por experiencia la vida es mucho mas facil, y te ganas horas leyendo y entendiendo el codigo de un tercero

Gabriel Obregón

student•

🐍✨Docstrings en Python

🧠 Idea Clave

La documentación no es opcional, es tu memoria a futuro.

Un docstring explica qué hace tu código, cómo y por qué.

📌 Beneficio: Leer tu propio código después será tan fácil como leer un resumen.

✍️ Qué es un Docstring

📖 Definición rápida: Un docstring es una cadena entre tres comillas """ ... """ que describe el propósito de un módulo, clase o función.

🧩 Dónde se usa:

Al inicio de un archivo → documenta el módulo
Dentro de funciones → explica qué hace y qué retorna
En clases → describe su comportamiento general

💡 Ejemplo básico

def saludo_doc():

"""Devuelve un saludo en español.

Retorno:

str: un saludo.

"""

return "Hola"

👉 Tips rápidos

Usa varias líneas si es necesario.
Evita frases vagas.
Sé directo, claro y útil.

📘 Guía PEP 257

📚 Propósito: establecer una forma estándar de escribir docstrings.

🧱 Estructura ideal

🟦 Descripción corta
🟨 Descripción larga (opcional)
🟩 Parámetros
🟧 Retorno
🟥 Excepciones
🟪 Ejemplos

Argenis Daniel Nieves Berroeta

student•

def fetch_news(api_name: str, *args, **kwargs):
    """Ejecuta el cliente de noticias especificado inyectando configuración por defecto.

    Args:
        api_name: Identificador del servicio ('newapi', 'guardian').
        *args: Argumentos posicionales requeridos por el cliente específico.
        **kwargs: Configuración opcional para sobrescribir la base.

    Returns:
        El resultado retornado por la función del cliente seleccionado.

    Raises:
        ValueError: Si `api_name` no coincide con ningún cliente registrado.
    """
    base_config = {
        "timeout": 30,
        "retries": 3,
    }

    config = {
        **base_config,
        **kwargs,
    }

    api_clients = {
        "newapi": newsapi_client,
        "guardian": guardian_client,
    }

    try:
        client = api_clients[api_name]
    except KeyError:
        # Falla de forma controlada indicando qué nombre fue incorrecto
        raise ValueError(f"Cliente '{api_name}' no soportado. Disponibles: {list(api_clients.keys())}")

    return client(*args, **config)

Samuel Alejandro Hurtado

student•

def clean_text(text: str) -> str:

"""

Clean text by removing punctuation and converting to lowercase.

This function removes punctuation and converts text to lowercase.

Args:

text (str): Text to clean.

Returns:

str: Cleaned text.

Raises:

TypeError: If text is not a string.

Examples:

>>> clean_text("Hello World!")

'hello world'

>>> clean_text("Hello World! 123")

'hello world 123'

"""

if not isinstance(text, str):

raise TypeError("text must be a string")

return text.lower().strip()

def fetch_news(api_name: str, *args, **kwargs):
    """Ejecuta el cliente de noticias especificado inyectando configuración por defecto.

    Args:
        api_name: Identificador del servicio ('newapi', 'guardian').
        *args: Argumentos posicionales requeridos por el cliente específico.
        **kwargs: Configuración opcional para sobrescribir la base.

    Returns:
        El resultado retornado por la función del cliente seleccionado.

    Raises:
        ValueError: Si `api_name` no coincide con ningún cliente registrado.
    """
    base_config = {
        "timeout": 30,
        "retries": 3,
    }

    config = {
        **base_config,
        **kwargs,
    }

    api_clients = {
        "newapi": newsapi_client,
        "guardian": guardian_client,
    }

    try:
        client = api_clients[api_name]
    except KeyError:
        # Falla de forma controlada indicando qué nombre fue incorrecto
        raise ValueError(f"Cliente '{api_name}' no soportado. Disponibles: {list(api_clients.keys())}")

    return client(*args, **config)

Documentación en Python con docstrings y PEP 257

Código Pythónico y Funcional

Python intermedio: prácticas profesionales con app de noticias e IA

Configuración de PEP 8 y formateo automático con Ruff en Python

Sintaxis de list, dict y set comprehensions en Python

Comprensiones anidadas para agrupar y filtrar datos en Python

Formateo de strings con f-strings en Python

Modificadores de formato avanzados en FStrings para números y fechas

Calidad y Profesionalismo del Código

Argumentos dinámicos *args en funciones Python

Uso de kwargs para crear un cliente de APIs flexible

Integración de Python con News API usando parámetros dinámicos

Control de errores en Python con try y except

Manejo de Datos y Recursos

Uso del bloque finally para liberar recursos en Python

Creación de excepciones personalizadas en Python

Anotaciones de tipo con type hints en Python

Tipado de funciones y estructuras de datos en Python

Documentación en Python con docstrings y PEP 257

Optimización y Pruebas

Entornos virtuales en Python: qué son y por qué los necesitas

Creación y gestión de entornos virtuales con venv en Python

Creación de entornos virtuales en Windows con Python

Creación de Aplicaciones de Consola

Gestión moderna de dependencias Python con UV y pyproject

Modularización de código Python con responsabilidad única

Paquetes Python: de estructura plana a código modular

Función enumerate en Python para indexar listas automáticamente

Filtrado de listas con filter en Python

Función map para calcular tiempo de lectura en Python

Conexión de OpenAI API con variables de entorno en Python