Overview

The Secret Santa Organizer is a Python tool designed to simplify the process of organizing a Secret Santa event. It allows users to randomly assign Secret Santa pairs from a group of people. The assignments are handled discreetly, ensuring no one knows who their Secret Santa is.

This tool operates using a .tsv file generated from Google Sheet export, containing participants informations. The Secret Santa assignments are shared via email, but it is possible to also use individual .txt files.

For full explanations on emails, see the appropriate section below.

How It Works

1. Prepare the Input File:

   • Export a spreadsheet as .tsv containing the same columns as the example.

   • Exclusions must contains names identical as in the Name column. Multiple names can be used.

   • Example of spreadsheet you need to export (see example.tsv file for the export result) :

     Name	Email	Exclusions	Gifts ideas
     Alice	alice@example.com		Books
     Bob	bob@example.com	Charlie
     Charlie	charlie@example.com		Cinema tickets
     Daisy	daisy@example.com	Alice Bob

2. Update the code and personnalize your text:

   • Replace at least "sending address" in main.py by your address registered in yagmail.
   • All text are written in the christmas_message function in email_manager.py so feel free to change them.
   • If you change the columns names, be sure to modify them in christmas_friends.py and email_manager.py.

3. Test the assignments, export and emails:

   • Make some test with run_simulation main.py to check if everything works well.
   • Try sending emails to yourself using test_email.

4. Share the Assignments:

   • Everything should work fine at this point.

If an error occur during email sending, you can use reload_and_send_emails to load your attributions and continue sending emails after debugging.

Libraries

• yagmail and keyring for email sending.

To install all librairies :

pip install yagmail keyring

Sending email with Python using yagmail

I suggest you to create a new gmail account for this purpose. You will always use the same with Python and you will not expose your real account. You need to register your email and password into yagmail only once to send email (therefore, once done, you don't need to write your password directly in the code). But this password IS NOT the password of your gmail account. This password used by yagmail is unique and given by your gmail account specifically for this usage.

Protocol for getting your password:

1. Get a 2-step Verification for your account (e.g. add a phone number)
2. Go to app passwords - search "app" if you don't find it, the link should be: myaccount.google.com/apppasswords
3. Set a name for the password (e.g. Python yagmail) - This step is blocked if your account doesn't have a 2-step Verification
4. Copy the password - be careful, it cannot be seen again afterward, but can be deleted of course

There are many tutorials for this on the web (e.g. Google Gmail Remove Allow Less Secure Apps Option Alternative Solution by Geeky Shows). When you have your password, follow "Python implementation" steps ONE TIME in order to be able to send email.

Python implementation:

1. Install yagmail and keyring.
2. Register you email address and password : yagmail.register("your-python-email@gmail.com", "yourpassword").
3. Put "your-python-email@gmail.com" in the the file config.json at "sending address".
4. Test if you can send an email to one of your email adress with test_email.py.

Now you can use yagmail without explicitely write your password in your code as the following example :

mail = yagmail.SMTP("your-python-email@gmail.com")
mail.send("receiver@example.com", "Test yagmail python", "Hello World")
mail.close()

To delete a password, use keyring.delete_password("yagmail", "your-python-email@gmail.com").

Acknowledgement

This code takes its inspiration from santa by jarhill0 - PyPI - GitHub