Files
Curso-lenguaje-python/catch-all/10_amigo_invisible/README.md
T

90 lines
4.8 KiB
Markdown

# Amigo Invisible
`secret_santa.py` lee un CSV de participantes, genera una asignación aleatoria que respeta las exclusiones, guarda el resultado en otro CSV y envía a cada participante un correo con su destinatario.
> **Atención:** en la versión actual, el envío está activado por defecto. El script intenta enviar correos aunque no se indique `--send`. No dispone de una opción para generar el sorteo sin enviar mensajes. Comprueba el CSV, las plantillas y la configuración SMTP antes de ejecutarlo.
## Preparación
El proyecto incluye un entorno virtual `venv`. Desde esta carpeta, actívalo e instala las dependencias en él:
```bash
source venv/bin/activate
python -m pip install -r requirements.txt
```
Si el entorno virtual no está disponible en tu equipo, créalo primero con `python3 -m venv venv`. La única dependencia externa es `python-dotenv`; los demás módulos que usa el script forman parte de la biblioteca estándar de Python.
Si `python -m pip` responde `No module named pip`, puede que el `venv` se creara con otra versión de Python. Actualízalo con el Python actual y vuelve a instalar las dependencias:
```bash
deactivate
python3 -m venv --upgrade venv
source venv/bin/activate
python -m pip install -r requirements.txt
```
`pip3` es el nombre de un ejecutable, no de un módulo para usar con `python -m`. Puedes comprobar el entorno con `python -V` y `python -m pip --version`.
## Participantes
El archivo de entrada, `participants.csv` por defecto, debe estar codificado en UTF-8 y tener estas columnas:
| Columna | Contenido |
| --- | --- |
| `name` | Nombre del participante. |
| `email` | Correo del participante. |
| `exclusions` | Opcional. Nombres o correos de personas a las que no puede regalar, separados por `;`. |
```csv
name,email,exclusions
Sergio,sergio@example.com,
María,maria@example.com,sergio@example.com
Pedro,pedro@example.com,María
```
Las exclusiones se comparan sin distinguir mayúsculas y minúsculas. Escribe cada nombre o correo exactamente como aparece en otra fila, salvo por las mayúsculas: el script no avisa si una exclusión no coincide con ningún participante. Usa correos distintos para cada persona y revisa que no haya campos vacíos; el script no valida estos datos antes del sorteo.
## Correo y plantillas
El script carga las variables SMTP desde un archivo `.env` de esta carpeta. Por ejemplo:
```env
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=tu_correo@gmail.com
SMTP_PASS=tu_contraseña
LOG_LEVEL=INFO
```
Usa las credenciales que correspondan a tu proveedor SMTP. El script conecta por SMTP, inicia STARTTLS y se autentica con `SMTP_USER` y `SMTP_PASS`. También puedes pasar estos valores mediante `--smtp-server`, `--smtp-port`, `--smtp-user` y `--smtp-pass`. Es preferible guardar la contraseña en `.env` en vez de ponerla en el comando, donde puede quedar en el historial de la terminal. No compartas el archivo `.env`.
El asunto se lee de `templates/subject.txt` y el cuerpo de `templates/body.txt`. Puedes indicar otros archivos con `--subject-template` y `--body-template`. Ambos admiten `{giver_name}`, `{giver_email}`, `{recipient_name}` y `{recipient_email}`. Solo el cuerpo admite `{participants_list}`, una lista de nombres, uno por línea. En el cuerpo, `{recipient_name}` aparece en mayúsculas porque así lo transforma el script.
Mantén el asunto en una sola línea y comprueba que todos los marcadores estén escritos correctamente. Las plantillas se rellenan durante el envío; un error puede interrumpirlo después de haber enviado algunos mensajes.
## Ejecución
Con el entorno virtual activado, el CSV, las plantillas y el SMTP preparados:
```bash
python secret_santa.py --input participants.csv --output assignments.csv
```
**Este comando guarda las asignaciones e intenta enviar los correos.** `--send` existe, pero actualmente no cambia ese comportamiento.
Opciones útiles:
| Opción | Descripción |
| --- | --- |
| `--input PATH` | CSV de participantes; por defecto, `participants.csv`. |
| `--output PATH` | CSV de asignaciones; por defecto, `assignments.csv`. |
| `--seed INT` | Semilla para repetir el sorteo con la misma entrada y configuración. |
| `--max-attempts N` | Intentos aleatorios antes de recurrir a una búsqueda exhaustiva; por defecto, `10000`. |
| `--subject-template PATH` | Plantilla del asunto; por defecto, `templates/subject.txt`. |
| `--body-template PATH` | Plantilla del cuerpo; por defecto, `templates/body.txt`. |
La salida contiene `giver_name,giver_email,recipient_name,recipient_email`. Contiene el sorteo completo: mantenla privada. El script registra su actividad en `secret_santa.log`.
Si el envío falla a mitad, consulta el registro y el CSV de salida antes de repetir el comando. Una nueva ejecución genera otras asignaciones y sobrescribe el CSV; quienes ya hayan recibido un correo podrían recibir un destinatario diferente.