Las docstrings bien escritas pueden convertirse en ayuda interactiva, páginas de terminal y documentación HTML sin instalar un sistema externo. pydoc en Python inspecciona módulos, clases, funciones y métodos y genera documentación a partir de __doc__, firmas, herencia y miembros documentables.
Pydoc resulta útil para explorar bibliotecas, revisar APIs internas, crear referencia rápida y entender objetos durante el desarrollo. No sustituye todas las funciones de Sphinx o MkDocs y exige cuidado porque importa los módulos documentados, ejecutando su código de nivel superior. Esta guía cubre comandos, docstrings, HTML, búsqueda, servidor local, help(), selección de entorno e imports seguros.
El contenido complementa nuestras guías sobre inspect, types, sysconfig, platform y py_compile.
Cómo encuentra la documentación
Para módulos, clases, funciones y métodos, pydoc lee la docstring y recorre sus miembros documentables. Si no existe docstring, puede intentar obtener un bloque de comentarios inmediatamente anterior mediante inspect.getcomments().
Las docstrings son la fuente predecible. Los comentarios normales deben explicar implementación; las docstrings deben describir el contrato público.
Una docstring sencilla
def calcular_total(valores, tasa=0):
"""Devuelve la suma de los valores más una tasa porcentual.
Args:
valores: Secuencia de números.
tasa: Porcentaje adicional.
Returns:
Total calculado.
"""
subtotal = sum(valores)
return subtotal * (1 + tasa / 100)Pydoc muestra el texto y la firma. No valida que la documentación coincida con el comportamiento real.
Usar help dentro de Python
help(calcular_total)
help("json")
help(str.split)La función built-in help() usa el sistema de pydoc para renderizar texto en la consola. Acepta objetos y nombres.
Ejecutar pydoc en terminal
python -m pydoc json
python -m pydoc pathlib.Path
python -m pydoc mi_paquete.modulo.funcionEl argumento puede ser módulo, paquete, clase, método, función o referencia con puntos. La salida recuerda a una página de manual.
Documentar un archivo por ruta
Si el argumento contiene el separador de rutas y apunta a un archivo Python existente, pydoc puede documentarlo.
python -m pydoc ./herramientas/informe.pyUsa rutas controladas. Un servicio no debe permitir que usuarios seleccionen archivos arbitrarios del servidor.
Importante: pydoc importa módulos
Para localizar objetos, pydoc importa el módulo objetivo. Todo código de nivel superior puede ejecutarse.
# Efectos peligrosos durante import
conexion = abrir_base_produccion()
iniciar_worker()Generar documentación podría abrir conexiones, iniciar threads, modificar archivos o enviar peticiones.
Protección con __main__
def main():
ejecutar_aplicacion()
if __name__ == "__main__":
main()Coloca la ejecución detrás del guard. Los imports deben definir objetos y realizar una inicialización mínima.
Los imports pueden fallar
Dependencias opcionales ausentes, variables obligatorias, bibliotecas nativas incompatibles y red durante el import pueden impedir la generación.
Diseña módulos con imports seguros y mensajes que identifiquen la dependencia sin revelar secretos.
Paginación
Para una salida larga, pydoc intenta usar un paginador. MANPAGER y PAGER seleccionan el programa, con prioridad para MANPAGER.
CI y redirecciones pueden comportarse de otra forma. La automatización no debe depender de interacción.
Generar HTML
python -m pydoc -w mi_paqueteLa opción -w escribe HTML en el directorio actual. Confirma el destino y los permisos antes de ejecutar.
Usa un directorio de build limpio para no mezclar páginas antiguas.
Generar varias páginas
python -m pydoc -w paquete.modulo_a paquete.modulo_bPara un sitio grande, un generador dedicado ofrece navegación, temas, referencias cruzadas y publicación más controladas.
Buscar módulos por sinopsis
python -m pydoc -k databaseLa opción -k busca en las líneas de sinopsis de módulos disponibles. La sinopsis suele ser la primera línea de la docstring del módulo.
Escribe una primera línea corta e informativa.
Docstring de módulo
"""Genera informes financieros en CSV y PDF.
El módulo contiene validadores, formateadores y exportadores.
"""Separa la sinopsis del resto mediante una línea vacía.
Servidor HTTP local
python -m pydoc -p 1234El comando inicia un servidor en localhost. La puerta cero elige una puerta libre.
python -m pydoc -p 0La interfaz ofrece índices de módulos, tópicos, keywords y búsqueda.
Abrir el navegador
python -m pydoc -bLa opción inicia el servidor y abre el índice en el navegador predeterminado.
Elegir hostname
python -m pydoc -n 0.0.0.0 -p 8000Un host no local puede permitir acceso desde otra máquina, útil en un container de desarrollo. También aumenta la exposición.
El servidor no es de producción
La documentación oficial limita el servidor HTTP al desarrollo local. No ofrece autenticación, autorización, TLS, límites, hardening ni observabilidad de producción.
No expongas módulos internos o detalles de la aplicación en una interfaz pública.
El entorno selecciona la versión
Pydoc utiliza el sys.path y el entorno activos. Documenta exactamente la versión que importaría ese intérprete.
python -c "import sys; print(sys.executable)"
python -m pydoc mi_paqueteActiva el virtualenv correcto y verifica el ejecutable.
Varias instalaciones de Python
Invocar un comando pydoc independiente puede seleccionar otra instalación. Prefiere python -m pydoc con el intérprete requerido.
PYTHONDOCS
Para la biblioteca estándar, pydoc supone que la documentación está en docs.python.org/X.Y/library/. PYTHONDOCS puede apuntar a otra URL o directorio local.
Controla esta variable en entornos reproducibles.
Firmas de funciones
Pydoc usa inspect.signature(). Los decorators que no preservan metadatos pueden ocultar la interfaz.
from functools import wraps
def registrar(funcion):
@wraps(funcion)
def wrapper(*args, **kwargs):
return funcion(*args, **kwargs)
return wrapperwraps() conserva nombre, docstring, anotaciones y metadatos.
Clases y herencia
La documentación puede mostrar métodos, atributos, bases y comportamiento heredado. La docstring de clase debe explicar responsabilidad, invariantes, construcción y ciclo de vida.
class Cliente:
"""Representa un cliente validado de la aplicación."""Properties y descriptors
Properties y descriptors pueden aparecer en la salida. La introspección no debería ejecutar trabajo destructivo. Mantén seguro el acceso a nivel de clase.
Type hints
Las anotaciones mejoran las firmas, pero pydoc no es un verificador estático. Documenta unidades, rangos, excepciones, mutación y efectos secundarios.
Excepciones
def dividir(a, b):
"""Divide a entre b.
Raises:
ZeroDivisionError: Si b es cero.
"""
return a / bDescribe errores que los llamadores pueden manejar.
APIs públicas y privadas
Los nombres con underscore comunican uso interno, pero la introspección aún puede encontrarlos. Define __all__ y organiza claramente los imports públicos.
No incluir secretos
No pongas tokens reales, URLs privadas, datos de clientes o credenciales en docstrings. La documentación puede distribuirse automáticamente.
Ejemplos ejecutables
Pydoc solo muestra ejemplos. doctest puede ejecutarlos de forma separada. Mantén ejemplos deterministas y sin efectos de producción.
Probar la generación
Una etapa de CI puede importar módulos y generar HTML para detectar fallos.
python -m pydoc -w mi_paquete.moduloEjecuta en aislamiento, sin credenciales de producción y con red bloqueada cuando corresponda.
pydoc frente a Sphinx
Pydoc es excelente para exploración y referencia rápida. Sphinx ofrece páginas narrativas, referencias cruzadas, extensiones, temas y publicación estructurada.
Ambos pueden coexistir: buenas docstrings benefician pydoc, IDEs y generadores mayores.
pydoc frente a help
help() es la interfaz interactiva. python -m pydoc añade comandos, búsqueda, HTML y servidor local.
Errores frecuentes
- Ejecutar efectos de producción durante import.
- Generar docs con el Python equivocado.
- Exponer el servidor HTTP públicamente.
- Escribir docstrings sin sinopsis clara.
- Perder firmas en decorators.
- Incluir secretos en ejemplos.
- Suponer que pydoc valida la corrección.
- Escribir HTML en el directorio incorrecto.
Buenas prácticas
- Mantén imports seguros y ligeros.
- Usa el guard
__main__. - Ejecuta con
python -m pydoc. - Activa y verifica el entorno.
- Escribe docstrings centradas en el contrato.
- Conserva firmas con
wraps(). - Restringe el servidor al desarrollo.
- Prueba la generación en CI aislado.
Conclusión
pydoc en Python convierte docstrings e introspección en ayuda de terminal, HTML, búsqueda y navegación local. Es una herramienta práctica para explorar APIs y generar referencia rápidamente.
Como importa el código, los módulos deben ser seguros durante import y el servidor debe permanecer como utilidad de desarrollo. Consulta la documentación oficial de pydoc y la PEP 257 para convenciones de docstrings.
