A program to manage secret santa assignments.
Project description
Sinterbot2020
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.
Installation
Use the package manager pip to install sinterbot.
pip install sinterbot
Usage
First 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: user1@email.tld
Santa B: user2@email.tld
Santa C: user3@email.tld
Santa D: user4@email.tld
Santa E: user5@email.tld
The format is Name: emailaddress
. Only the email addresses need 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 user1@email.tld!
Send message to user2@email.tld!
Send message to user3@email.tld!
Send message to user4@email.tld!
Send message to user5@email.tld!
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: yourname@gmail.com
#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 exit
Feedback
Please feel free to use the Github issues to report bugs, ask questions, or make suggestions.
Hacking
Clone repo:
$ git clone https://github.com/cristoper/sinterbot.git
$ cd sinterbot/
Run tests:
$ python -m unittest discover
Check types:
mypy sinterbot/*.py bin/*.py
License
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sinterbot-0.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 505a5bb3190c84e92f4b91ff037bbb4dacd5f272d0c38728aab6704fb72b5148 |
|
MD5 | fc9aff90bc311fdcd47de0969abfd0aa |
|
BLAKE2b-256 | a0747d997be90264c672dba03a967e8f3ba1b1ed514438b3eabcd386f907c915 |