From 995a9f53f1b3353d24bbcb855b831c269c1b7088 Mon Sep 17 00:00:00 2001 From: Manuel Vergara Date: Sun, 15 Nov 2026 18:38:36 +0100 Subject: [PATCH] feat: update app for 2026/2027 --- catch-all/10_amigo_invisible/README.md | 221 ++++-------------- catch-all/10_amigo_invisible/secret_santa.py | 3 +- .../10_amigo_invisible/templates/body.txt | 31 +-- .../10_amigo_invisible/templates/subject.txt | 2 +- 4 files changed, 67 insertions(+), 190 deletions(-) diff --git a/catch-all/10_amigo_invisible/README.md b/catch-all/10_amigo_invisible/README.md index 740cdc5..9d8c7f5 100644 --- a/catch-all/10_amigo_invisible/README.md +++ b/catch-all/10_amigo_invisible/README.md @@ -1,139 +1,53 @@ -# README - Amigo Invisible (Secret Santa) +# Amigo Invisible -Este es un script en Python diseñado para organizar un intercambio de regalos de "Amigo Invisible" de manera automática. Permite generar asignaciones de personas de forma aleatoria, asegurándose de que no haya emparejamientos invalidos, como asignar a alguien a sí mismo o asignar a alguien con exclusiones especificadas. +`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. -Además, si se habilita la opción de enviar correos electrónicos, el script enviará un correo a cada participante notificándole a quién le ha tocado regalar, usando plantillas personalizables. +> **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. -## Requisitos +## Preparación -* Python 3.x -* Paquetes de Python requeridos: - - * `csv` - * `random` - * `argparse` - * `smtplib` - * `os` - * `logging` - * `email` - * `dotenv` - -Puedes instalar las dependencias necesarias ejecutando el siguiente comando: +El proyecto incluye un entorno virtual `venv`. Desde esta carpeta, actívalo e instala las dependencias en él: ```bash -pip install python-dotenv +source venv/bin/activate +python -m pip install -r requirements.txt ``` -Si usas un entorno virtual, asegúrate de activarlo antes de instalar las dependencias. +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. -## Descripción de Funcionalidades +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: -### Entradas +```bash +deactivate +python3 -m venv --upgrade venv +source venv/bin/activate +python -m pip install -r requirements.txt +``` -El script toma como entrada un archivo CSV que contiene la lista de participantes. El archivo CSV debe tener las siguientes columnas: +`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`. -* `name`: Nombre del participante. -* `email`: Correo electrónico del participante. -* `exclusions`: (Opcional) Lista de participantes a los que **no** pueden ser asignados como "Amigo Invisible". Los valores deben estar separados por punto y coma. +## Participantes -Ejemplo de archivo CSV `participants.csv`: +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 -Juan,juan@example.com, -María,maria@example.com,juan@example.com -Pedro,pedro@example.com,juan@example.com +Sergio,sergio@example.com, +María,maria@example.com,sergio@example.com +Pedro,pedro@example.com,María ``` -En el caso de que un participante no tenga exclusiones, se deja en blanco la columna `exclusions`. +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. -### Opciones del Script +## Correo y plantillas -Este es el uso básico del script: - -```bash -python secret_santa.py --input participants.csv -``` - -#### Opciones disponibles: - -* `--input PATH` - Ruta al archivo CSV de entrada (por defecto `participants.csv`). - -* `--output PATH` - Ruta al archivo CSV de salida donde se guardarán las asignaciones (por defecto `assignments.csv`). - -* `--seed INT` - Semilla para la generación aleatoria. Esto permite hacer el proceso reproducible. - -* `--send` - Habilita el envío de correos electrónicos. Si no se incluye, los correos no se enviarán. - -* `--smtp-server HOST` - Servidor SMTP para el envío de correos (por defecto, `smtp.gmail.com`). - -* `--smtp-port PORT` - Puerto SMTP (por defecto, 587). - -* `--smtp-user USER` - Usuario SMTP (requiere autenticación). - -* `--smtp-pass PASS` - Contraseña SMTP. **Es recomendable utilizar una variable de entorno en lugar de escribir la contraseña directamente.** - -* `--subject-template` - Ruta al archivo de plantilla del asunto del correo. - -* `--body-template` - Ruta al archivo de plantilla del cuerpo del correo. - -* `--max-attempts N` - Número máximo de intentos para generar emparejamientos aleatorios (por defecto, 10000). - -## Flujo de Trabajo - -1. **Leer Participantes:** - El script lee el archivo `participants.csv` y extrae los datos de los participantes, incluyendo sus exclusiones. - -2. **Generación de Asignaciones:** - Se genera un emparejamiento aleatorio entre los participantes. El script se asegura de que: - - * Un participante no se empareje con sí mismo. - * Un participante no sea asignado a una persona de su lista de exclusiones. - - Si no se puede encontrar una asignación válida después de varios intentos (por defecto, 10000), el script usa un algoritmo de **backtracking** para intentar encontrar una solución. - -3. **Guardar Asignaciones:** - Las asignaciones generadas se guardan en un archivo CSV con el formato: - - ```csv - giver_name,giver_email,recipient_name,recipient_email - ``` - -4. **Enviar Correos Electrónicos (Opcional):** - Si se habilita la opción `--send`, el script enviará un correo electrónico a cada participante notificándole a quién le ha tocado regalar. - - Los correos electrónicos usan plantillas personalizables para el asunto y el cuerpo del mensaje. Puedes crear estos archivos como plantillas y proporcionarlas al script a través de los parámetros `--subject-template` y `--body-template`. - -### Estructura de Archivos - -La estructura recomendada para el proyecto es la siguiente: - -``` -. -├── secret_santa.py # Script principal -├── .env # Variables de entorno (por ejemplo, SMTP credentials) -├── participants.csv # Lista de participantes -├── assignments.csv # Archivo generado con las asignaciones -├── templates/ -│ ├── subject.txt # Plantilla de asunto para los correos -│ └── body.txt # Plantilla de cuerpo para los correos -└── secret_santa.log # Archivo de registro (log) -``` - -#### Archivos `.env` - -El archivo `.env` debe contener las variables necesarias para la autenticación SMTP. Este archivo **no debe ser subido a repositorios públicos** (asegúrate de que esté en el archivo `.gitignore`). Un ejemplo de `.env` podría ser: +El script carga las variables SMTP desde un archivo `.env` de esta carpeta. Por ejemplo: ```env SMTP_SERVER=smtp.gmail.com @@ -143,74 +57,33 @@ SMTP_PASS=tu_contraseña LOG_LEVEL=INFO ``` -#### Plantillas de Correo +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`. -Las plantillas para el **asunto** y el **cuerpo** del correo se deben almacenar en archivos de texto en la carpeta `templates/`. Estos archivos pueden contener variables que se reemplazarán dinámicamente con los datos de cada participante. +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. -Ejemplo de archivo `templates/subject.txt`: +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. -``` -¡Tu Amigo Invisible es {recipient_name}! -``` +## Ejecución -Ejemplo de archivo `templates/body.txt`: - -``` -¡Hola {giver_name}! - -Te ha tocado regalar a {recipient_name}, cuyo correo es {recipient_email}. - -¡Suerte con la compra de tu regalo! - -Atentamente, -El equipo de Amigo Invisible -``` - -## Uso - -### Ejemplo Básico - -Si quieres realizar el emparejamiento sin enviar correos electrónicos: +Con el entorno virtual activado, el CSV, las plantillas y el SMTP preparados: ```bash python secret_santa.py --input participants.csv --output assignments.csv ``` -### Ejemplo con Correos +**Este comando guarda las asignaciones e intenta enviar los correos.** `--send` existe, pero actualmente no cambia ese comportamiento. -Si deseas enviar correos electrónicos a los participantes, usa la opción `--send`: +Opciones útiles: -```bash -python secret_santa.py --input participants.csv --output assignments.csv --send --smtp-user "tu_correo@gmail.com" --smtp-pass "tu_contraseña" -``` +| 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`. | -### Personalización de Plantillas +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 prefieres personalizar el asunto y el cuerpo de los correos, puedes hacerlo editando los archivos de plantilla: - -* `templates/subject.txt` -* `templates/body.txt` - -Luego, solo necesitas especificar las rutas a estos archivos con las opciones `--subject-template` y `--body-template` al ejecutar el script. - -## Registros - -El script genera un archivo de log llamado `secret_santa.log`, donde se registran todas las actividades realizadas. Puedes revisar este archivo para obtener detalles sobre el proceso de asignación, cualquier error o advertencia, y las actividades de envío de correos. - -## Excepciones y Errores - -El script maneja diversas excepciones, como errores de lectura de archivo CSV, errores al enviar correos electrónicos, o si no se encuentran suficientes participantes. - -Si un error ocurre, el script terminará su ejecución con un mensaje de error detallado. - -## Contribuciones - -Si deseas realizar mejoras o reportar problemas, por favor abre un **Issue** o envía un **Pull Request**. ¡Cualquier contribución será bienvenida! - -## Licencia - -Este proyecto está bajo la Licencia MIT. Ver el archivo [LICENSE](LICENSE) para más detalles. - ---- - -Este `README` proporciona una guía completa para el uso de este script, la configuración de los parámetros y el manejo de excepciones. Si tienes más dudas o necesitas personalizar algún aspecto del script, no dudes en preguntarme. ¡Feliz organización de tu Amigo Invisible! 🎁 +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. diff --git a/catch-all/10_amigo_invisible/secret_santa.py b/catch-all/10_amigo_invisible/secret_santa.py index f2a1190..dee2508 100644 --- a/catch-all/10_amigo_invisible/secret_santa.py +++ b/catch-all/10_amigo_invisible/secret_santa.py @@ -195,7 +195,8 @@ def send_emails(pairs: List[Tuple[Dict,Dict]], smtp_config: Dict, subject_templa giver_name=giver['name'], giver_email=giver['email'], recipient_name=recipient['name'].upper(), - recipient_email=recipient['email'] + recipient_email=recipient['email'], + participants_list='\n'.join([f"- {p['name']}" for p, _ in pairs]) ) msg['Subject'] = subject msg['From'] = user or server_host diff --git a/catch-all/10_amigo_invisible/templates/body.txt b/catch-all/10_amigo_invisible/templates/body.txt index e59c70f..55b6920 100644 --- a/catch-all/10_amigo_invisible/templates/body.txt +++ b/catch-all/10_amigo_invisible/templates/body.txt @@ -1,26 +1,29 @@ -¡Hola **{giver_name}**! 😎 +¡Hola {giver_name}! 😎 -Manu ha creado esta fabulosa app para enviarte el resultado del sorteo del **"Amigo INVISIBLE" edición 2025/2026**. +Manu ha creado esta fabulosa app para enviarte el resultado del sorteo del "Amigo INVISIBLE" edición 2026/2027. -El regalo se entregará la próxima noche del **24 de diciembre de 2025** y tendrá un valor superior a **100 €**. +El regalo se entregará la próxima noche del 24 de diciembre de 2026 y tendrá un valor superior a 25 €. -Por favor, **NO SE LO DIGAS A NADIE**. Te ha tocado hacerle un regalo a **nada más y nada menos que a...** +Te ha tocado hacerle un regalo a nada más y nada menos que a... ⬇️⬇️⬇️⬇️⬇️⬇️⬇️⬇️ -✨ **{recipient_name}** ✨ + +✨ {recipient_name} ✨ 📧 {recipient_email} + ⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️ ---- +Lista de participantes: +{participants_list} -**CONSEJOS:** -- **No se lo digas a nadie** 🤐 -- Aprovecha el **Black Friday** 🏴 [https://amzn.to/4osrLQL](https://amzn.to/4osrLQL) -- Da **pistas** de los regalos que quieres por si te escuchan 🕵️‍♀️ -- **Busca algo original**, ¡y que no huela a “último minuto”! 😂 **Intenta regalar cosas útiles** +----- -Espero que entiendas que si **revelas tu amigo invisible** no tiene gracia. 🙏 **COMPRA TU EL REGALO** y **no envíes a nadie a por él**. +CONSEJOS: +- No se lo digas a nadie 🤐 Aunque disimules se nota y pierde la gracia. +- Aprovecha el Black Friday 🏴 https://amzn.to/4osrLQL +- Da pistas de los regalos que quieres por si te escuchan 🕵️‍♀️ +- Busca algo original, ¡y que no huela a “último minuto”! 😂 Intenta regalar cosas útiles. ---- +Espero que entiendas que si revelas tu amigo invisible no tiene gracia. 🙏 COMPRA TÚ EL REGALO y no envíes a nadie a por él. -¡Felices fiestas y que viva el misterio del **Amigo Invisible**! 🎅 +¡Felices fiestas y que viva el misterio del Amigo Invisible! 🎅 diff --git a/catch-all/10_amigo_invisible/templates/subject.txt b/catch-all/10_amigo_invisible/templates/subject.txt index 59bee56..52d240f 100644 --- a/catch-all/10_amigo_invisible/templates/subject.txt +++ b/catch-all/10_amigo_invisible/templates/subject.txt @@ -1 +1 @@ -[Navidades 2025/2026] 🎁 {giver_name}, ¡Correo con tu AMIGO INVISIBLE! \ No newline at end of file +[Navidades 2026/2027] 🎁 ¡Correo con el AMIGO INVISIBLE de {giver_name}! \ No newline at end of file