{"id":13809200,"url":"https://github.com/sethblack/python-gift-exchange","last_synced_at":"2025-04-06T22:10:18.593Z","repository":{"id":62580588,"uuid":"218174803","full_name":"sethblack/python-gift-exchange","owner":"sethblack","description":"pyge: Holiday Gift Exchange Picker","archived":false,"fork":false,"pushed_at":"2021-11-26T16:18:10.000Z","size":414,"stargazers_count":250,"open_issues_count":2,"forks_count":12,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-30T21:08:13.014Z","etag":null,"topics":["euclidean-distances","gift-exchange","holidays","machine-learning","python","python3","random","secret-santa","unsupervised-learning","weighted-random"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sethblack.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-10-29T01:00:54.000Z","updated_at":"2025-01-21T09:22:49.000Z","dependencies_parsed_at":"2022-11-03T21:53:39.233Z","dependency_job_id":null,"html_url":"https://github.com/sethblack/python-gift-exchange","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethblack%2Fpython-gift-exchange","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethblack%2Fpython-gift-exchange/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethblack%2Fpython-gift-exchange/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sethblack%2Fpython-gift-exchange/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sethblack","download_url":"https://codeload.github.com/sethblack/python-gift-exchange/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247557767,"owners_count":20958047,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["euclidean-distances","gift-exchange","holidays","machine-learning","python","python3","random","secret-santa","unsupervised-learning","weighted-random"],"created_at":"2024-08-04T01:02:07.826Z","updated_at":"2025-04-06T22:10:18.566Z","avatar_url":"https://github.com/sethblack.png","language":"Python","readme":"# Python Gift Exchange Picker\n\n[![The Rest by taleas.com](https://www.taleascomic.com/static/images/comics/the-rest-of-my-presents.jpg \"The Rest by taleas.com\")](https://www.taleascomic.com/comics/the-rest-of-the-christmas-presents.html)\n\nMy wife is in charge of our families' annual Secret Santa Gift Exchange. Because she, unfortunately, knows about my background in math and computer science her requirements have become more extreme. A hat containing folded pieces of paper with hand-written names is no longer sufficient. Python Gift Exchange Picker (pyge) is my third and best implementation of my wife's requirements:\n\n- It must match each person to a different person.\n- The match should not be in the same household.\n- The match should not be the same gender.\n- The match should not be in the same age group.\n- The match must not happen again for at least three years.\n\nTo accomplish this, pyge imports a list of participants along with their feature sets and transforms each participant's feature set into numerical values. Each value is then vectorized and a pairwise euclidean distance between each participant is computed; this can be represented as either a graph or a matrix - I chose a matrix. The distances are then multiplied by a per-participant \"qualifier\" coefficient and the results are used to build a weighted distribution. The pairs of participants are then randomly matched using the weighted distribution until either all participants have been matched or no matches can be made. If no matches can be made and there are still participants pyge will backtrack until all participants can be successfully matched or it is discovered that it is impossible to match the given set of participants.\n\nIf you're interested, you can read a more detailed description [here](https://www.sethserver.com/python/secret-santa-gift-exchange.html).\n\n## Installation\n\n```sh\npip install pyge\n```\n\n## Basic Usage\n\nPyge has only one required argument: the path to a csv file containing the people who are participating in the gift exchange. An example csv file, [jazz.csv](https://github.com/sethblack/py-gift-exchange/blob/master/jazz.csv) has been provided.\n\n\n```sh\n$ pyge /path/to/jazz.csv\nHerbie Hancock, Billie Holiday\nElla Fitzgerald, Herbie Hancock\nCharlie Parker, Nina Simone\nNina Simone, Bill Evans\nMiles Davis, Duke Ellington\nJohn Coltrane, Sarah Vaughan\nSarah Vaughan, Louis Armstrong\nLouis Armstrong, Ella Fitzgerald\nBillie Holiday, Charlie Parker\nDuke Ellington, John Coltrane\nDizzy Gillespie, Miles Davis\nBill Evans, Dizzy Gillespie\n```\n\n### Input CSV File Format\n\n```\nname, date of birth, sex, \"city, state or province or territory\"\n```\n\nAny column containing a comma should be quoted with double-quotes, for example, `\"Austin, TX\"`.\n\nThe `Date of Birth` field is in `MM/DD/YYYY` format.\n\n`Sex` can be `M`, `F` or `N`.\n\n`City` by default only includes cities in the United States. See [Using Other Country Databases](https://github.com/sethblack/py-gift-exchange#using-other-country-databases) for more information on changing the country.\n\n## Saving History\n\nPyge saves a historical list of pairings which is used to ensure participants will not be paired for at a minimum of three exchanges. Saving history can be toggled with the `--save-history` and `--no-history` flags. The minimum number of exchanges can be modified with the `--history-length` argument.\n\n## Using Other Country Databases\n\nYou can pass a different city weight database file by using the `--citydb` argument. The city weight database is a csv file in the following format:\n\n```\ncity, state or province or territory, normalized latitude, normalized longitude\n```\n\nWhere normalized latitude and longitude are the values normalized between -1 and +1 (divided by 180).\n\n## Full Usage\n\n```\nusage: pyge [-h] [-s] [-n] [-c citydb] [-l historylength] file\n\nGenerates a list of people pairings for a holiday gift exchange.\n\npositional arguments:\n  file                  path to the csv containing a list of people who want\n                        to be part of the celebration\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -s, --save-history    save a history file of matches\n  -n, --no-history      do not save a history file of matches\n  -c citydb, --citydb citydb\n                        path to city csv for distance calculations\n  -l historylength, --history-length historylength\n                        number of cycles before people can be paired again\n```\n\n---\n\nCities database provided by [https://simplemaps.com/data/us-cities](https://simplemaps.com/data/us-cities).","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsethblack%2Fpython-gift-exchange","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsethblack%2Fpython-gift-exchange","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsethblack%2Fpython-gift-exchange/lists"}