gale-shapley-algorithm 1.1.2

A Python implementation of the celebrated Gale-Shapley Algorithm.

 

This is a Python implementation of the celebrated Gale-Shapley (a.k.a. the Deferred Acceptance) Algorithm.

Time complexity is O(n^2), space complexity is O(n).

 

 

User Guide

Requirements

• Python >= 3.12
• OS: Ubuntu, MacOS, Windows

Installation

There are three easy ways to install the package.

Install from PyPI

pip install gale-shapley-algorithm

For CLI support:

pip install "gale-shapley-algorithm[cli]"

For the GUI:

pip install "gale-shapley-algorithm[gui]"

Using Docker

An easy way to run the project is to use Docker. First, install Docker. Then, run the following command in the project directory.

docker build -t gale-shapley .

This will build the Docker image. After the image is built, the following are some examples of how to run the project.

docker run --rm -it \
-v $(pwd)/config/example_config_custom_input.yaml:/app/config/config.yaml \
-v $(pwd)/logs:/app/logs \
gale-shapley

The -v option mounts the specified config file and logs directory to the container. The --rm option removes the container after it exits. The -it option is for interactive mode.

To run the GUI instead:

docker run --rm -p 8000:8000 gale-shapley uv run uvicorn gale_shapley._api.app:app --host 0.0.0.0 --port 8000

Using Git

If you have git installed, simply run

git clone https://github.com/oedokumaci/gale-shapley-algorithm

to clone the repository locally. After cloning, install the dependencies using uv:

1. pip install uv
2. cd gale-shapley
3. uvx --from taskipy task setup

Usage

Configuration

First edit the ./config/config.yaml to your liking. Example config files can be found at ./config/example_config_*.

Quick Start

After configuring the ./config/config.yaml, simply run the following command in the project directory.

uvx --from taskipy task run

Detailed Usage

For a list of all the CLI arguments and options, run

uvx --from taskipy task run -- --help

A sample output with currently implemented CLI arguments and options is shown below.

 

Developer Guide

Setup

This project is managed with uv and uses taskipy for task running. First install uv, then clone the project and run uvx --from taskipy task setup in the project directory to install all dependencies.

Development

Pre-commit Hooks

The project uses pre-commit hooks. Run

uv run pre-commit install

in the project directory to install hooks to your local .git.