Metadata-Version: 2.4
Name: connect4-game
Version: 0.1.4
Summary: Connect 4 game with pygame UI
Requires-Python: <3.14,>=3.13
Description-Content-Type: text/markdown
Requires-Dist: pytest>=8.0.0
Requires-Dist: black>=24.0.0
Requires-Dist: pygame>=2.6.0

# 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.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 <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'`

PyPI **0.1.2+** ships a fixed launcher; the error almost always means the **`connect4` script on your PATH was not updated** (often `pip` installs to a different Python than the one that runs `connect4`).

1. **Run with the same interpreter you use to install** (replace `python` with your `python3.14` / `pyenv` shim if needed):

   ```bash
   python -m pip install --upgrade --force-reinstall connect4-game
   python -m pip show connect4-game   # expect Version: 0.1.2 or newer
   head -n 5 "$(which connect4)"
   ```

   The last line should show `from ux.view import run_cli`, not `from main import main`.

2. **Workaround** (no console script): after install, run:

   ```bash
   python -m ux
   ```

3. **Still stuck:** uninstall and reinstall with the same `python -m pip`:

   ```bash
   python -m pip uninstall -y connect4-game
   python -m pip install connect4-game
   ```

Or reinstall from this repo: `uv pip install -e .`.
