Mejores Prácticas de Scripting de Sistemas

Los scripts en los que puedes confiar sin supervisión siguen las mismas reglas de operabilidad que los servicios de producción: modos de fallo predecibles, valores predeterminados seguros y registros que los operadores pueden buscar a las 3 a.m.

Cómo Usar Esta Lista

• Aplica antes de programar cualquier script en cron o CI.
• Bloquea la revisión si faltan --dry-run para herramientas mutables.
• Revisa después de cualquier incidente causado por reejecuciones de automatización o trabajos superpuestos.

A - Estructura y CLI

• Usa if __name__ == "__main__" y una función main() -> int. Mantiene los módulos importables y testeables.
• Analiza argumentos con argparse o typer. Documenta las flags en --help y README.
• Soporta --dry-run para acciones destructivas. Imprime los cambios previstos sin efectos secundarios.
• Reserva stdout para salida de máquina; registra para humanos en stderr. Permite canalizar líneas JSON limpiamente.
• Devuelve códigos de salida documentados. 0 ok, 2 uso, 1 fallo - coincide con las convenciones de la organización.

B - Archivos y Datos

• Usa pathlib para todas las operaciones de rutas. Evita uniones de rutas de cadenas.
• Especifica encoding="utf-8" en archivos de texto. Previene sorpresas con la configuración predeterminada de la plataforma.
• Escribe salidas atómicamente (temporal + reemplazo). Los lectores nunca ven archivos medio escritos.
• Valida las entradas antes de la mutación. Falla rápidamente en directorios vacíos, variables de entorno faltantes, flags incorrectas.
• Haz que las reejecuciones sean idempotentes. Superposición segura de cron o comportamiento explícito de flock/skip.

C - Procesos y Red

• Llama a subprocess con listas de argv, no cadenas de shell. Elimina la inyección a menos que sea una excepción documentada.
• Establece tiempos de espera para subprocess y HTTP. Los trabajos colgados no deben bloquear cron para siempre.
• Reintenta errores transitorios con un límite de retroceso (backoff cap). Registra el fallo final con contexto.
• Nunca registres secretos, tokens o URLs pre-firmadas. Redacta las cabeceras Authorization.
• Verifica las firmas de las webhooks antes de procesar el cuerpo. Rechaza eventos entrantes sin firmar.

D - Programación y Operaciones

• Usa rutas absolutas al python de venv en crontab. Incluye cd a la raíz del proyecto.
• Previene ejecuciones superpuestas con un bloqueo de archivo o distribuido. Sale con 0 al omitir instancias duplicadas si es apropiado.
• Emite registros estructurados (JSON) para scripts de producción. Incluye acción, ruta, duración, ID de correlación.
• Monitoriza externamente el latido de la última ejecución exitosa. Detecta fallos silenciosos de cron.
• Versiona los scripts en git con CI ejecutando ruff/pytest. La misma puerta de calidad que el código de la aplicación.

E - Remoto y Escalado

• Prefiere Ansible sobre bucles ssh ad-hoc para flotas. Usa scripts ssh solo para casos de emergencia.
• Rechaza claves de host SSH desconocidas en la automatización. known_hosts o certificados gestionados.
• Limita las operaciones remotas paralelas. Evita activar límites de tasa y bloqueos.
• Transmite archivos de registro grandes línea por línea. No leas archivos de varios GB en memoria.
• Promociona scripts estables a CLIs empaquetadas. Puntos de entrada pyproject.toml cuando el alcance crece.

Preguntas Frecuentes

Relacionados

• Scripts Robustos - patrón completo de operabilidad
• Conceptos Básicos de Scripting - puntos de entrada y CLI
• Programación y Cron - higiene de cron
• subprocess e Interoperabilidad de Shell - ejecución segura de comandos
• Mejores Prácticas del SDK de la Nube - AWS desde scripts

Versiones de la Pila: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.