sinterbot is a little command line program (Python 3.5+) that helps to manage secret santa assignments. With sinterbot you can generate a valid secret santa assignment for a list of people and email each person their assigned gift recipient without ever revealing to anybody (including the operator of sinterbot) the full secret list of assignments.
For some of the theory and motivation behind sinterbot, see my weblog post Deranged Sinterklaas: The Math and Algorithms of Secret Santa
sinterbot allows specifying some extra constraints such as minimum cycle length or a blacklist of people who should not be assigned to each other.
Use the package manager pip to install sinterbot.
pip install sinterbotFirst create a config file with a list of participants' names and email addresses. The config file may also specify constraints for minimum cycle length and a blacklist. See sample.conf for a full example:
# xmas2020.conf
Santa A: [email protected]
Santa B: [email protected]
Santa C: [email protected]
Santa D: [email protected]
Santa E: [email protected]
The format is Name: emailaddress. Only the email addresses needs to be unique.
Then run sinterbot derange to compute a valid assignment and save it to the config file:
$ sinterbot derange xmas2020.conf
Derangement info successfully added to config file.
Use `sinterbot send sample.conf -c smtp.conf` to send emails!sinterbot will not allow you to re-derange a config file without passing the --force flag.
Now if you want you can view the secret santa assignments with sinterbot view xmas2020.conf. However, if you're a participant that would ruin the suprise for you! Instead you can email each person their assignment without ever seeing them yourself:
$ sinterbot send xmas2020.conf -c smtp.conf
Send message to [email protected]!
Send message to [email protected]!
Send message to [email protected]!
Send message to [email protected]!
Send message to [email protected]!Before you can run the sinterbot send you need to create a file for your SMTP credentials:
# smtp.conf
#
# These settings are used to send the assignment emails. SMTPEmail will appear
# as the 'From:' address in the sent emails
#
# If SMTPUser is blank, SMTPEmail will be used as the user credentials.
#
# If SMTPPass is blank, the program will look for it in an environment variable
# called "sinter_smtp_pass" instead.
SMTPEmail: [email protected]
#SMTPUser:
SMTPPass: yourgmailpassword
SMTPServer: smtp.gmail.com
SMTPPort: 587(If you do not know what SMTP server to use but you have a gmail account, you can use gmail's SMTP server using values like those exemplified above (you will need to generate an app password.)
To get full usage info run sinterbot --help. You can also pass --help to each subcommand:
$ sinterbot --help
usage: sinterbot [-h] {derange,check,send,view} ...
positional arguments:
{derange,check,send,view}
derange Read .config file and add derangement information to
it.
check Check that the config file contains a valid
derangement
send Send every santa an email with the name of their
assigned recipient.
view Show the list of secret santa assignments.
optional arguments:
-h, --help show this help message and exitPlease feel free to use the Github issues to report bugs, ask questions, or make suggestions.
Clone repo:
$ git clone https://github.com/cristoper/sinterbot.git
$ cd sinterbot/Run tests:
$ python -m unittest discoverCheck types:
mypy sinterbot/*.py bin/*.py