Created script.

.gitignore

@@ -1,3 +1,7 @@
+secret.py
+data.json
+output.json
+
 # ---> Python
 # Byte-compiled / optimized / DLL files
 __pycache__/

README.md

@@ -1,2 +1,122 @@
-# secret-santa
+# README
 
+This is a Python script for running a secret Santa draw.
+
+This script:
+
+- Ingests participant data in JSON format,
+- Automates the randomised pairing of people to buy gifts for,
+- Includes information about preferences or restrictions for gifts that participants may have,
+- Automatically emails participants via GMail SMTP (requires external set-up), and
+- Creates an output file of gift pairings for troubleshooting later.
+
+The script only uses standard libraries that come bundled with Python distributions, and does not require installing any dependencies.
+
+## Set Up
+
+### GMail SMTP
+
+This app uses GMail as an SMTP provider.
+
+- This is because GMail accounts are free and easy to create,
+- The server is trusted by spam filters and is unlikely to be flagged as junk, and
+- The app can authenticate without using any external libraries.
+
+This means that there will be a few steps of external set up.
+
+- [ ] Create `secret.py` from a copy of `secret.py.bak`.
+- [ ] Log in to (or create) a GMail account (a standard, free account should suffice).
+- [ ] Enable two-factor authentication on the account.
+- [ ] Under the two-factor authentication section, generate an `App Password`.
+- [ ] Enter your GMail username and the generated app password in `secret.py`.
+
+`secret.py`
+
+```py
+USERNAME = '<username>@gmail.com'
+PASSWORD = '<app password>'
+```
+
+You can get more information on [how to do this in the GMail documentation](https://support.google.com/mail/answer/185833?hl=en-GB).
+
+#### Using a Different SMTP Server
+
+You can set up a different SMTP provider by editing the server information in `config.py` and providing the appropriate username and password in `secret.py`.
+
+### Data
+
+The script ingests data as a JSON file.
+Create a file `data.json` (matching the file path in `config.py`) in the following format:
+
+`data.json`
+
+```json
+{
+    "name0": {
+        "email": "string",
+        "preference": "string"
+    },
+    "name1": {
+        "email": "string",
+        "preference": "string"
+    }
+}
+```
+
+> [!NOTE]
+> **Punctuation**: Comma after every entry, except the last entry.
+
+JSON syntax is very fragile and can break if not entered correctly.
+
+> [!TIP]  
+> **Email Addresses**: If you have provided an `EMAIL_DOMAIN` value in `config.py`, then you do not need to add the full email address, and can just provide the username before the `@`.
+If you do provide a full email address for a participant in the data file, it will override the domain name given.
+
+### Configuration
+
+You can configure the app to send the draw for the secret Santa, including the greeting and the sign-off used, via the values in `config.py`.
+You can also edit the files in the `./templates` directory to customise the email message to include any additional instructions or text as needed.
+
+The most important configurations, however, are the credentials in `secret.py` and the data in `data.json`
+
+## Running the script
+
+Because this script should work using standard libraries in Python 3, you should be able to execute the script using whatever Python 3 interpreter you have.
+
+`PowerShell`
+
+```powershell
+> python app.py
+```
+
+`Bash`
+
+```bash
+$ python3 app.py
+```
+
+## The Algorithm
+
+The algorithm I used for the secret santa draw is a very elegant one, as [illustrated by Prof Hannah Fry](https://www.youtube.com/watch?v=GhnCj7Fvqt0).
+
+- Randomise the order of participants.
+- Generate a derangement from the randomised order by shifting the top name to the bottom of the list.
+- Match participants between the randomised list and derangement to pair who is buying for whom.
+
+This ensures that:
+
+- People know whom they are buying for, but do not know who else is buying for whom, and
+- Everybody has an equal chance of buying for everybody else.
+- The person running the draw also does not know who is buying for them (unless they peek behind the curtain, as it were).
+
+## Troubleshooting
+
+If you do need to see who is buying for whom, you can check the `output.json` file, or check the sent emails from the SMTP server.
+
+## Isn't This an Over-Engineered Solution for a Trivial Problem?
+
+Of course it is.
+
+## Why Not Use an Existing Site for This?
+
+Because where is the fun in that?

app.py

@@ -0,0 +1,79 @@
+import json, os, random, smtplib, ssl
+from email.message import EmailMessage
+from string import Template
+
+from config import Config as Config
+from secret import USERNAME, PASSWORD
+
+context = ssl.create_default_context()
+
+# Load data file
+data_path = os.path.normpath(Config.DATA)
+with open(data_path, 'r') as data_file:
+    data = json.loads(data_file.read())
+
+print('Parsed data file.')
+
+if not data: raise Exception('Error: data file is empty.')
+
+# Randomise participants.
+participants = list(data.keys())
+random.shuffle(participants)
+
+# Create a derangement in the permutation by moving the first participant to the bottom
+derangement = list(participants)
+derangement.append(derangement.pop(0))
+
+# Create a dictionary pairing participants and gift recipients
+buying = {}
+for index, participant in enumerate(participants):
+    buying[participant] = derangement[index]
+buying = {key: value for key, value in sorted(buying.items())}
+
+# Create output file
+output_path = os.path.normpath(Config.OUTPUT)
+with open(output_path, 'w') as output:
+    output.write(json.dumps(buying, indent=4))
+
+# Parse Templates
+plain_path = os.path.normpath('./templates/plain.txt')
+with open(plain_path, 'r') as plain_file:
+    plain_template = Template(plain_file.read())
+rich_path = os.path.normpath('./templates/rich.html')
+with open(rich_path, 'r') as rich_file:
+    rich_template = Template(rich_file.read())
+
+def construct_message(participant, gift_recipient):
+    message = EmailMessage()
+    message['From'] = USERNAME
+    if '@' in data[participant]['email']:
+        participant_email = data[participant]['email']
+    elif hasattr(Config,'EMAIL_DOMAIN') and Config.EMAIL_DOMAIN:
+        participant_email = f'{data[participant]["email"]}@{Config.EMAIL_DOMAIN}'
+    else:
+        raise Exception(f'Error: Invalid email address for participant {participant}.')
+    if hasattr(Config,'OVERRIDE_RECIPIENT') and Config.OVERRIDE_RECIPIENT and hasattr(Config,'RECIPIENT_EMAIL') and Config.RECIPIENT_EMAIL:
+        message['To'] = Config.RECIPIENT_EMAIL
+    else: message['To'] = participant_email
+    message['Subject'] = Config.SUBJECT
+    preference = 'None' if not data[gift_recipient].get('preference') else data[gift_recipient].get('preference')
+    template_substitutions = {
+        'subject': Config.SUBJECT,
+        'greeting': Config.GREETING,
+        'participant': participant.title(),
+        'gift_recipient': gift_recipient.title(),
+        'preference': preference,
+        'sender': Config.SENDER
+    }
+    body_html = rich_template.substitute(template_substitutions)
+    body_plain = plain_template.substitute(template_substitutions)
+    message.set_content(body_plain)
+    message.add_alternative(body_html, subtype='html')
+    return message
+
+messages = [construct_message(participant=participant, gift_recipient=gift_recipient) for participant, gift_recipient in buying.items()]
+
+with smtplib.SMTP_SSL(Config.SERVER, Config.PORT, context=context) as smtp:
+    smtp.login(user=USERNAME, password=PASSWORD)
+    for message in messages: smtp.send_message(message)
+    smtp.quit()

config.py

@@ -0,0 +1,22 @@
+class Config(object):
+
+    # SMTP Configuration
+    SERVER = 'smtp.gmail.com' # Uses GMail SMTP by default
+    PORT = 465 # Default GMail SSL SMTP port
+
+    # Customisation
+    GROUP = '' # Group/Organisation Name
+    EMAIL_DOMAIN = 'bar.com' # Email domain for organisation
+    SUBJECT = f'{GROUP} Secret Santa Draw' if GROUP else 'Secret Santa Draw' # Email subject line
+    GREETING = 'Ho Ho Ho' # Email greeting
+    SENDER = 'The Secret Santa Elf' # Email sign-off
+
+    # App Configs
+    DATA = './data.json' # Data file
+    OUTPUT = './output.json' # Output file
+
+class Test(Config):
+
+    # Test Config
+    OVERRIDE_RECIPIENT = True # Override the recipient for all emails
+    RECIPIENT_EMAIL = '' # Test email address to receive all outgoing email

secret.bak.py

@@ -0,0 +1,2 @@
+USERNAME = '' # GMail Username
+PASSWORD = '' # 16-character 'App Password' (without spaces).

templates/plain.txt

@@ -0,0 +1,15 @@
+$subject
+
+$greeting $participant!
+
+You are buying a gift for $gift_recipient.
+
+That they have given the following preferences for their gift:
+
+$preference
+
+I hope you enjoy the secret Santa!
+
+$sender
+
+This is an automatically generated email. Please do not reply to this address as it will not be monitored.

templates/rich.html

@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>
+        $subject
+    </title>
+</head>
+<body>
+    <h1>
+        $subject
+    </h1>
+    <h2>
+        $greeting $participant!
+    </h2>
+    <p>
+        You are buying a gift for 
+        <strong>
+            $gift_recipient
+        </strong>
+        .
+    </p>
+    <p>
+        That they have given the following preferences for their gift:
+        <p>
+            <strong>
+                $preference
+            </strong>
+        </p>
+    </p>
+    <p>
+        I hope you enjoy the secret Santa!
+    </p>
+    <p>
+        $sender
+    </p>
+    <p>
+        <strong>
+            This is an automatically generated email.
+            Please do not reply to this address as it will not be monitored.
+        </strong>
+    </p>
+</body>
+</html>