# Connect 4 (Python + pygame)

https://pypi.org/project/connect4-game/

## Summary

A desktop **Connect 4** game with a **pygame** UI. Game rules, sessions, bots, and the engine live under `src/game/`; shared types are in `src/base_models.py`; the public API surface is `src/api.py` so the UI can depend on stable contracts without importing `game/` directly. The pygame front end is under `src/ux/`. Unit tests cover backend logic under `tests/unit/`; end-to-end grid scenarios are under `tests/e2e/`.

**Features:** 
* two players (human or bot)
* bot difficulties (easy / medium / hard)
* player session stats across games
* win-line highlighting


---

## Requirements

- **Python 3.13.x** (3.14+ is not supported yet: pygame 2.6.x hits a font-module circular import on 3.14; see [pygame#4795](https://github.com/pygame/pygame/issues/4795).)
- **[uv](https://docs.astral.sh/uv/)** (recommended) or another virtualenv + pip workflow
- **SDL2** (usually bundled with pygame wheels; on some Linux setups you may need system SDL packages)

---

## Build and run from this repository

From the project root (the directory that contains `pyproject.toml`):

```bash
git clone https://github.com/appraveen/connect4.git connect4
cd connect4
uv sync
```

Run the game using either the installed console script or the module:

```bash
uv run connect4
```

or:

```bash
uv run python -m main
```

---

## Tests and formatting (optional)

```bash
uv run pytest
```

```bash
uv run black src tests
```

---

## 5. Run without cloning the code (install from PyPI)

Ensure you are in python environment 3.13.*

```bash
# pip install connect4-game
# connect4

pyenv install 3.13.2   # or latest 3.13.x
pyenv local 3.13.2     # in the project, or: pyenv global 3.13.2
python -m pip install -U connect4-game
connect4
```
