# Connect 4 (Python + pygame)

## 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+**
- **[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 <repository-url> 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)

After the package is **published** to PyPI under the name defined in `pyproject.toml` (`connect4-game`), anyone can install and run it without a checkout:

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

Use `pipx install connect4-game` if you prefer an isolated CLI install.

> **Note:** The exact PyPI package name must match what you publish; adjust `pip install …` if you choose a different name on PyPI.

If `connect4` fails with `No module named 'main'`, reinstall so you get the current console entry point: `pip install --upgrade --force-reinstall connect4-game` (or reinstall from this repo with `uv pip install -e .`).
