Skip to main content

A program to manage secret santa assignments.

Project description

Sinterbot2020

Image of Santa from Futurama

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

MIT

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sinterbot-0.1.1.tar.gz (14.9 kB view details)

Uploaded Source

Built Distribution

sinterbot-0.1.1-py3-none-any.whl (12.7 kB view details)

Uploaded Python 3

File details

Details for the file sinterbot-0.1.1.tar.gz.

File metadata

  • Download URL: sinterbot-0.1.1.tar.gz
  • Upload date:
  • Size: 14.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.6.1 requests/2.25.0 setuptools/44.0.0 requests-toolbelt/0.9.1 tqdm/4.54.1 CPython/3.7.7

File hashes

Hashes for sinterbot-0.1.1.tar.gz
Algorithm Hash digest
SHA256 c4a1231abcc75b44cfa934a5d49a912c586bd8e9a67fb407311b70a932184e71
MD5 4f4c78222ba136c3b55890d542dc0684
BLAKE2b-256 79f04b7b5eff928c4ceb3c2384cf9f872eb90d6ff10423b27dc41e500e2730cb

See more details on using hashes here.

File details

Details for the file sinterbot-0.1.1-py3-none-any.whl.

File metadata

  • Download URL: sinterbot-0.1.1-py3-none-any.whl
  • Upload date:
  • Size: 12.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.6.1 requests/2.25.0 setuptools/44.0.0 requests-toolbelt/0.9.1 tqdm/4.54.1 CPython/3.7.7

File hashes

Hashes for sinterbot-0.1.1-py3-none-any.whl
Algorithm Hash digest
SHA256 c366f6dc423a82c63ee5e5db24fa43abe024fc90d66f4bf0eaab171d0b4400f0
MD5 b5ec7ddcd8ff29fb07faa4ca02669c1f
BLAKE2b-256 a56a31faf15ae0b452b59695953b922a61ea8ac42018d90121d957ad900b02e3

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page