PyPollyanna

Christmas is almost here and it's time to pick who's gifting to whom this Christmas. You can always get your group together and pick names out of a hat, but the problem is that sometimes people will pick their significant other (so why have a Pollyanna for them), or they pick themselves and have to draw again. So what to do? How about let the computer make sure that everything is fine?

That's where PyPollyanna comes in. I wrote it for my own family's yearly Pollyanna and we're currently using it this year. The program reads a list of participants from a CSV file, parses it into a list of people, and then pairs them up according to their parameters (who their spouse is, who they feel like they always get, etc.). It then creates an email to each of them and sends them a personalized email with their partner's name and amazon wish list.

Requirements

Runtime Requirements

• 
• 
• 
• 
• 

Development Requirements

• 
• 
• 

Recommended Environment

• 
• 

Recommended VSCode Plugins

• Auto Close Tag
• Auto Rename Tag
• autoDocstring - Python Docstring Generator
• Better Jinja
• Code Spell Checker
• Comment Anchors
• Importmagic
• Ini for VSCode
• IntelliCode
• IntelliCode Completions
• markdownlint
• Pylance
• Python

Code Documentation

1. Main.py
2. Person.py
3. SendEmail.py
4. Templates.py
5. Tests
6. Data.csv
7. Creds.conf

Getting Started

1. You need your participants to register with you to fill out the CSV. I recommend sending them all a link to a google form with some questions (Who do you always get, what's your amazon wish list, etc). Then download the data and arrange it into a CSV file with the format described in the section "CSV".
2. You put the csv file in the project directory with the name "data.csv".
3. Create an ini file named "creds.conf" following the format in the section "Credential Config File" in the project directory.
4. Change the templates to include proper descriptions of your event and parameters.
5. Download the requirements from pip using requirements.txt; You must be on Python 3.9 or above to run the program.
6. And you're ready. Go ahead and run main.py in the terminal, and follow the prompts.

That's it! You've got a Pollyanna list and all of your participants have been emailed with whom they should buy a gift for.

CSV File (data.csv)

The CSV File, data.csv, includes the information needed for the participants in the Pollyanna. The good news is that this can be adapted from a CSV export of a Google Form which is how I conducted the survey for the information.

The format for the file is a CSV meaning it's separated by commas and must contain a header. The header MUST BE:

ID,Name,Full Name,I ALWAYS Get,Spouse,Email Address,Amazon Wishlist

Otherwise, the program will not load it correctly. Each entry must be on a separate line. An example might look like:

ID,Name,Full Name,I ALWAYS Get,Spouse,Email Address,Amazon Wishlist
1,Gino,Gino Contoso,-1,2,gino@contoso.com,https://www.amazon.com/wishlist
2,Cella,Marcela Contoso,-1,1,cella@contoso.com,https://www.amazon.com/wishlist

You can also open CSV files in Excel or OpenOffice/LibreOffice Calc. In that case it will be a table like this:

ID	Name	Full Name	I ALWAYS Get	Spouse	Email Address	Amazon Wishlist
1	Gino	Gino Contoso	-1	2	gino@contoso.com	https://www.amazon.com/wishlist
2	Cella	Marcela Contoso	-1	1	cella@contoso.com	https://www.amazon.com/wishlist

You will need a minimum of three unmarried people or two couples since built into the rules is the assumption that you cannot get your spouse for Pollyanna. This is because it is assumed that spouses will separately get each other gifts regardless the Pollyanna.

The fields which aren't obvious are explained below:

• "ID" - This is a unique number, easiest just to start at 1 and increase from there
• "I ALWAYS Get" - This is the ID of someone the person feels like they get every year or most years. The program will try to avoid assigning that person to them.
• "Spouse" - This is the ID of the person's spouse. Note: Both spouses should list the other partner.

Credential Config File (creds.conf)

The creds.conf file contains a listing of the information needed to make a secure connection to an email SMTP server to send out the notification emails to your participants so they know who has which participant for gift exchange, and what that person's amazon wishlist link is. The file is formatted like an INI file from windows config files and must contain the following section and keys (and your own settings rather than the contrived data below):

[DEFAULT]
Email = youremailaddress@gmail.com
Password = app_password_generated_by_gmail
SMTPServer = smtp.gmail.com
SMTPPort = 587
SMTPSecurity = TLS

[FACILITATOR]
Name = My Name
Event = Christmas 2022

The Email must be the email address that you use to log into the server. The Password is an app password generated by your email service or a regular password chosen by you for your email service. The SMTPServer, SMTPPort, and SMTPSecurity are values provided by your email service. SMTPSecurity can be one of the following:

• "TLS"
• "None"

The Facilitator section includes the name of the facilitator and the name of the event they are facilitating a Pollyanna for. It also specifies the prize/reward for winning the contest.

Templates

There are two templates in the "Template" folder and these are used for the email that is sent to everyone. The two template.[txt|html].jinja files indicate the formatting for both the html and text only versions of the email. The master.jinja file indicates the text common to both as well as the variables used by its sections and the templates.

Master Template

The Master Template contains all of the common text between both types of emails. The defaults for the variables can be edited by the user and the information omitted but that's not the preferred way to handle changes to the information. Facilitator for examples can be specified on the command line, gained from the config file, or obtained interactively by the program.

• reward - The default email contains an invitation to participate in a voted gift wrapping contest. The participants are told the winner will receive this reward.
• event_name - The default email begins by announcing the beginning of the Pollyanna for a particular event (Christmas, Hanukkah, Etc.). This is where you name that event.
• spending_limit - A string describing the dollar amount total a gift or gifts should be to keep the gift giving fair.
• facilitator - The name of the person facilitating the event and thus sending the email.
• due_date - The cut-off after which people can buy gifts for each other. It's a last chance to edit your wishlist before the recipient of the list begins buying gifts for their assignment.

HTML Template

The HTML template is for the rich-text version of the email. By default, it has some colors and images and the CSS for the email all in one file. It also has variables at the top that can be modified to contain more appropriate information. The variables not defined at the top of the template are used by the program to fill in for each individual recipient. They are:

• background_color & background_color_2 - Hex code as a string for the colors used for the background of the email.
• text_color - color for the text to contrast against the backgrounds.

Text Template

Some Email clients are unable to render HTML or the email service might not support HTML Emails. In that case, a plaintext version is sent along with the message so that those clients can correctly render the information for the user.

It includes all of the same variables as the HTML Template except the colors.

Command Line Interface

Most people will just write the files themselves and run the program as is. But if you want to, you may specify some information on the command-line. The command is in the format:

main.py [-h] [-t] [-f FACILITATOR] [-q] [-n | -p PRIZE]

• -h, --help - Shows the help message and exits
• -t, --test - Do not send the final Emails, instead save them into a file
• -f FACILITATOR, --facilitator FACILITATOR - The name of the person facilitating the Pollyanna
• -q, --quiet - Determines whether or not to display sample emails
• -n, --no-contest - Whether or not to host the gift-wrapping contest. Cannot use with -p
• -p PRIZE, --prize PRIZE - The winner of the gift-wrapping contest receives this (e.g. "A $100 Amazon Gift Card")

Road Map

1. Finish Documentation of all code and type annotations
2. Add command-line options to specify config files
3. Prompt the user to enter people and generate the source CSV file manually if it's empty, missing, insufficient¹, or improperly formatted².
4. Allow the end user to specify additional variables to use for the templates
5. Automatically test email system before attempting to send emails.
6. Make more options specified on the command line.

Footnotes

1. "insufficient" means that it doesn't reflect enough people. ↩

2. "improperly formatted* means that it doesn't have all of the columns it must have at minimum. ↩