https://github.com/jarhill0/santa

Assign a secret santa over email
https://github.com/jarhill0/santa

email python secret-santa

Last synced: 6 months ago
JSON representation

Assign a secret santa over email

• Host: GitHub
• URL: https://github.com/jarhill0/santa
• Owner: jarhill0
• License: unlicense
• Created: 2017-11-16T18:52:36.000Z (almost 8 years ago)
• Default Branch: master
• Last Pushed: 2022-06-22T20:37:46.000Z (over 3 years ago)
• Last Synced: 2025-03-24T08:39:22.471Z (7 months ago)
• Topics: email, python, secret-santa
• Language: Python
• Homepage: https://pypi.python.org/pypi/santa/
• Size: 16.6 KB
• Stars: 6
• Watchers: 1
• Forks: 1
• Open Issues: 2
• Metadata Files:
  • Readme: README.rst
  • License: LICENSE

Awesome Lists containing this project

README

          
Santa

=====

A Python project to randomly pair Secret Santa gifters and recipients, following a set of constraints, and email

them, all without the operator seeing the assignments.

Requirements

------------

- yagmail

Installation

------------

Install with ``pip3 install santa`` or ``python3 -m pip install santa``. Precede either command with ``sudo`` if it

fails due to insufficient permissions.

Usage

-----

1. Create `Person` objects for all participants with their names and addresses:

.. code-block:: python

    import santa

    john = santa.Person('John Doe', 'jdoe@example.com')

    sally = santa.Person('Sally Salamander', 'sally@mander.com')

    linus = santa.Person('Linus Torvalds', 'torvalds@transmeta.com')

    guido = santa.Person('Guido van Rossum', 'guido@python.org')

2. Put them into a list:

.. code-block:: python

    people = [john, sally, linus, guido]

3. If any participants have restrictions on who they can give to (say, John and Sally are married and will be getting

   each other gifts regardless), create a dictionary with the giver as the key and the banned recipients in a list as the 

   value:

 

.. code-block:: python

    # not only are John and Sally married, but Sally hates Linus and will not get him a gift.

    restrictions = {john: [sally],

                    sally: [john, linus]}

4. Pass these into the function ``santa.run(person_list, invalid_links=None, *, message='', subject='Secret Santa')``. 

   This will match people and send emails. If a match is not found, the program will raise ``santa.SolvingError``. If

   you haven't already `configured yagmail `_, it will prompt you for a username and password.

.. code-block:: python

    santa.run(people, restrictions, message='Thank you for participating.')

5. If there are any errors sending emails, they will be printed to the console in the form of a list of tuples of

   ``(gifter, recipient)``. You, the operator, must decide how to handle this.

Options

-------

By default, santa will solve using the ``'loop'`` strategy, which results in a "gifting loop." As of version 0.2,

santa can also solve with the method ``'draw'``, which simulates drawing tickets from a hat. This method will not

necessarily result in a loop, but it will be possible for "pairs" of two gifters giving to each other to occur.

To set a solving mode, pass it into ``santa.run()`` like so:

.. code-block:: python

    santa.run(people, restrictions, solve_mode='loop')

The current list of solving modes is as follows:

- ``'loop'`` (default)

- ``'draw'``

Santa also has options for output modes. By default, it will email recipients. But as of version 0.2, it also has the

option to save output to text files in the current working directory. These can be attached to emails and sent

without the operator having to find out who is assigned to whom.

To set an output mode, pass it into ``santa.run()`` like so:

.. code-block:: python

    santa.run(people, restrictions, out_mode='text')

The current list of output modes is as follows:

- ``'email'`` (default)

- ``'text'``