py-connect-4 0.1.2
Play connect 4 in your terminal or online with your friends
Requires Python: >=3.13

# py-connect-4

This is a simple Python script to play connect 4.

Uses rich to represent the board!

Play locally OR online with your friends.

## Installation

- With uv (recommended)

```bash
❯ uv tool install py-connect-4
❯ py-connect-4 --help
```

Or simply run it via uvx

```bash
❯ uvx py-connect-4 --help
```

- With pip

```bash
❯ pip install py-connect-4
❯ py-connect-4 --help
```

## Usage

### Locally

```bash
❯ uvx py-connect-4 local
❯ # or after installation via pip
❯ py-connect-4 local
```
Then play in turns in 1 shell prompt.

### Online

One of you needs to spawn 2 processes to **HOST** and also **JOIN** the game:

**Host**:

```bash
❯ uvx py-connect-4 online host
❯ # or after installation via pip
❯ py-connect-4 online host
```

**Client**:

```bash
❯ uvx connect-4 online join
❯ # or after installation via pip
❯ py-connect-4 online join
```

You'll be prompted to enter the HOST IP or fall back to "0.0.0.0"

### Game example
<details>
<summary>This is an example for a local game</summary>

```bash
❯ uvx py-connect-4 local
┏━━━┳━━━┳━━━┳━━━┳━━━┳━━━┳━━━┓
┃ 0 ┃ 1 ┃ 2 ┃ 3 ┃ 4 ┃ 5 ┃ 6 ┃
┡━━━╇━━━╇━━━╇━━━╇━━━╇━━━╇━━━┩
│   │   │   │   │   │   │   │
├───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │   │   │   │
├───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │   │   │   │
├───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │   │   │   │
├───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │   │   │   │
├───┼───┼───┼───┼───┼───┼───┤
│   │   │   │   │   │   │   │
└───┴───┴───┴───┴───┴───┴───┘
Player 🟠. Col: 6
┏━━━┳━━━┳━━━┳━━━┳━━━┳━━━┳━━━━┓
┃ 0 ┃ 1 ┃ 2 ┃ 3 ┃ 4 ┃ 5 ┃ 6  ┃
┡━━━╇━━━╇━━━╇━━━╇━━━╇━━━╇━━━━┩
│   │   │   │   │   │   │    │
├───┼───┼───┼───┼───┼───┼────┤
│   │   │   │   │   │   │    │
├───┼───┼───┼───┼───┼───┼────┤
│   │   │   │   │   │   │    │
├───┼───┼───┼───┼───┼───┼────┤
│   │   │   │   │   │   │    │
├───┼───┼───┼───┼───┼───┼────┤
│   │   │   │   │   │   │    │
├───┼───┼───┼───┼───┼───┼────┤
│   │   │   │   │   │   │ 🟠 │
└───┴───┴───┴───┴───┴───┴────┘
Player 🔵. Col: 6
┏━━━┳━━━┳━━━┳━━━┳━━━┳━━━┳━━━━┓
┃ 0 ┃ 1 ┃ 2 ┃ 3 ┃ 4 ┃ 5 ┃ 6  ┃
┡━━━╇━━━╇━━━╇━━━╇━━━╇━━━╇━━━━┩
│   │   │   │   │   │   │    │
├───┼───┼───┼───┼───┼───┼────┤
│   │   │   │   │   │   │    │
├───┼───┼───┼───┼───┼───┼────┤
│   │   │   │   │   │   │    │
├───┼───┼───┼───┼───┼───┼────┤
│   │   │   │   │   │   │    │
├───┼───┼───┼───┼───┼───┼────┤
│   │   │   │   │   │   │ 🔵 │
├───┼───┼───┼───┼───┼───┼────┤
│   │   │   │   │   │   │ 🟠 │
└───┴───┴───┴───┴───┴───┴────┘
Player 🟠. Col: 5
┏━━━┳━━━┳━━━┳━━━┳━━━┳━━━━┳━━━━┓
┃ 0 ┃ 1 ┃ 2 ┃ 3 ┃ 4 ┃ 5  ┃ 6  ┃
┡━━━╇━━━╇━━━╇━━━╇━━━╇━━━━╇━━━━┩
│   │   │   │   │   │    │    │
├───┼───┼───┼───┼───┼────┼────┤
│   │   │   │   │   │    │    │
├───┼───┼───┼───┼───┼────┼────┤
│   │   │   │   │   │    │    │
├───┼───┼───┼───┼───┼────┼────┤
│   │   │   │   │   │    │    │
├───┼───┼───┼───┼───┼────┼────┤
│   │   │   │   │   │    │ 🔵 │
├───┼───┼───┼───┼───┼────┼────┤
│   │   │   │   │   │ 🟠 │ 🟠 │
└───┴───┴───┴───┴───┴────┴────┘
Player 🔵. Col: 4
┏━━━┳━━━┳━━━┳━━━┳━━━━┳━━━━┳━━━━┓
┃ 0 ┃ 1 ┃ 2 ┃ 3 ┃ 4  ┃ 5  ┃ 6  ┃
┡━━━╇━━━╇━━━╇━━━╇━━━━╇━━━━╇━━━━┩
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │    │ 🔵 │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │ 🔵 │ 🟠 │ 🟠 │
└───┴───┴───┴───┴────┴────┴────┘
Player 🟠. Col: 5
┏━━━┳━━━┳━━━┳━━━┳━━━━┳━━━━┳━━━━┓
┃ 0 ┃ 1 ┃ 2 ┃ 3 ┃ 4  ┃ 5  ┃ 6  ┃
┡━━━╇━━━╇━━━╇━━━╇━━━━╇━━━━╇━━━━┩
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │ 🟠 │ 🔵 │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │ 🔵 │ 🟠 │ 🟠 │
└───┴───┴───┴───┴────┴────┴────┘
Player 🔵. Col: 5
┏━━━┳━━━┳━━━┳━━━┳━━━━┳━━━━┳━━━━┓
┃ 0 ┃ 1 ┃ 2 ┃ 3 ┃ 4  ┃ 5  ┃ 6  ┃
┡━━━╇━━━╇━━━╇━━━╇━━━━╇━━━━╇━━━━┩
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │ 🔵 │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │ 🟠 │ 🔵 │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │ 🔵 │ 🟠 │ 🟠 │
└───┴───┴───┴───┴────┴────┴────┘
Player 🟠. Col: 4
┏━━━┳━━━┳━━━┳━━━┳━━━━┳━━━━┳━━━━┓
┃ 0 ┃ 1 ┃ 2 ┃ 3 ┃ 4  ┃ 5  ┃ 6  ┃
┡━━━╇━━━╇━━━╇━━━╇━━━━╇━━━━╇━━━━┩
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │ 🔵 │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │ 🟠 │ 🟠 │ 🔵 │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │ 🔵 │ 🟠 │ 🟠 │
└───┴───┴───┴───┴────┴────┴────┘
Player 🔵. Col: 6
┏━━━┳━━━┳━━━┳━━━┳━━━━┳━━━━┳━━━━┓
┃ 0 ┃ 1 ┃ 2 ┃ 3 ┃ 4  ┃ 5  ┃ 6  ┃
┡━━━╇━━━╇━━━╇━━━╇━━━━╇━━━━╇━━━━┩
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │ 🔵 │ 🔵 │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │ 🟠 │ 🟠 │ 🔵 │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │ 🔵 │ 🟠 │ 🟠 │
└───┴───┴───┴───┴────┴────┴────┘
Player 🟠. Col: 6
┏━━━┳━━━┳━━━┳━━━┳━━━━┳━━━━┳━━━━┓
┃ 0 ┃ 1 ┃ 2 ┃ 3 ┃ 4  ┃ 5  ┃ 6  ┃
┡━━━╇━━━╇━━━╇━━━╇━━━━╇━━━━╇━━━━┩
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │    │ 🟠 │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │ 🔵 │ 🔵 │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │ 🟠 │ 🟠 │ 🔵 │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │ 🔵 │ 🟠 │ 🟠 │
└───┴───┴───┴───┴────┴────┴────┘
Player 🔵. Col: 4
┏━━━┳━━━┳━━━┳━━━┳━━━━┳━━━━┳━━━━┓
┃ 0 ┃ 1 ┃ 2 ┃ 3 ┃ 4  ┃ 5  ┃ 6  ┃
┡━━━╇━━━╇━━━╇━━━╇━━━━╇━━━━╇━━━━┩
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │    │ 🟠 │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │ 🔵 │ 🔵 │ 🔵 │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │ 🟠 │ 🟠 │ 🔵 │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │ 🔵 │ 🟠 │ 🟠 │
└───┴───┴───┴───┴────┴────┴────┘
Player 🟠. Col: 5
┏━━━┳━━━┳━━━┳━━━┳━━━━┳━━━━┳━━━━┓
┃ 0 ┃ 1 ┃ 2 ┃ 3 ┃ 4  ┃ 5  ┃ 6  ┃
┡━━━╇━━━╇━━━╇━━━╇━━━━╇━━━━╇━━━━┩
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │    │    │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │    │ 🟠 │ 🟠 │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │ 🔵 │ 🔵 │ 🔵 │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │ 🟠 │ 🟠 │ 🔵 │
├───┼───┼───┼───┼────┼────┼────┤
│   │   │   │   │ 🔵 │ 🟠 │ 🟠 │
└───┴───┴───┴───┴────┴────┴────┘
Player 🔵. Col: 3
┏━━━┳━━━┳━━━┳━━━━┳━━━━┳━━━━┳━━━━┓
┃ 0 ┃ 1 ┃ 2 ┃ 3  ┃ 4  ┃ 5  ┃ 6  ┃
┡━━━╇━━━╇━━━╇━━━━╇━━━━╇━━━━╇━━━━┩
│   │   │   │    │    │    │    │
├───┼───┼───┼────┼────┼────┼────┤
│   │   │   │    │    │    │    │
├───┼───┼───┼────┼────┼────┼────┤
│   │   │   │    │    │ 🟠 │ 🟠 │
├───┼───┼───┼────┼────┼────┼────┤
│   │   │   │    │ 🔵 │ 🔵 │ 🔵 │
├───┼───┼───┼────┼────┼────┼────┤
│   │   │   │    │ 🟠 │ 🟠 │ 🔵 │
├───┼───┼───┼────┼────┼────┼────┤
│   │   │   │ 🔵 │ 🔵 │ 🟠 │ 🟠 │
└───┴───┴───┴────┴────┴────┴────┘
Player 🟠. Col: 4
┏━━━┳━━━┳━━━┳━━━━┳━━━━┳━━━━┳━━━━┓
┃ 0 ┃ 1 ┃ 2 ┃ 3  ┃ 4  ┃ 5  ┃ 6  ┃
┡━━━╇━━━╇━━━╇━━━━╇━━━━╇━━━━╇━━━━┩
│   │   │   │    │    │    │    │
├───┼───┼───┼────┼────┼────┼────┤
│   │   │   │    │    │    │    │
├───┼───┼───┼────┼────┼────┼────┤
│   │   │   │    │ 🟠 │ 🟠 │ 🟠 │
├───┼───┼───┼────┼────┼────┼────┤
│   │   │   │    │ 🔵 │ 🔵 │ 🔵 │
├───┼───┼───┼────┼────┼────┼────┤
│   │   │   │    │ 🟠 │ 🟠 │ 🔵 │
├───┼───┼───┼────┼────┼────┼────┤
│   │   │   │ 🔵 │ 🔵 │ 🟠 │ 🟠 │
└───┴───┴───┴────┴────┴────┴────┘
Player 🔵. Col: 2
┏━━━┳━━━┳━━━━┳━━━━┳━━━━┳━━━━┳━━━━┓
┃ 0 ┃ 1 ┃ 2  ┃ 3  ┃ 4  ┃ 5  ┃ 6  ┃
┡━━━╇━━━╇━━━━╇━━━━╇━━━━╇━━━━╇━━━━┩
│   │   │    │    │    │    │    │
├───┼───┼────┼────┼────┼────┼────┤
│   │   │    │    │    │    │    │
├───┼───┼────┼────┼────┼────┼────┤
│   │   │    │    │ 🟠 │ 🟠 │ 🟠 │
├───┼───┼────┼────┼────┼────┼────┤
│   │   │    │    │ 🔵 │ 🔵 │ 🔵 │
├───┼───┼────┼────┼────┼────┼────┤
│   │   │    │    │ 🟠 │ 🟠 │ 🔵 │
├───┼───┼────┼────┼────┼────┼────┤
│   │   │ 🔵 │ 🔵 │ 🔵 │ 🟠 │ 🟠 │
└───┴───┴────┴────┴────┴────┴────┘
Player 🟠. Col: 1
┏━━━┳━━━━┳━━━━┳━━━━┳━━━━┳━━━━┳━━━━┓
┃ 0 ┃ 1  ┃ 2  ┃ 3  ┃ 4  ┃ 5  ┃ 6  ┃
┡━━━╇━━━━╇━━━━╇━━━━╇━━━━╇━━━━╇━━━━┩
│   │    │    │    │    │    │    │
├───┼────┼────┼────┼────┼────┼────┤
│   │    │    │    │    │    │    │
├───┼────┼────┼────┼────┼────┼────┤
│   │    │    │    │ 🟠 │ 🟠 │ 🟠 │
├───┼────┼────┼────┼────┼────┼────┤
│   │    │    │    │ 🔵 │ 🔵 │ 🔵 │
├───┼────┼────┼────┼────┼────┼────┤
│   │    │    │    │ 🟠 │ 🟠 │ 🔵 │
├───┼────┼────┼────┼────┼────┼────┤
│   │ 🟠 │ 🔵 │ 🔵 │ 🔵 │ 🟠 │ 🟠 │
└───┴────┴────┴────┴────┴────┴────┘
Player 🔵. Col: 2
┏━━━┳━━━━┳━━━━┳━━━━┳━━━━┳━━━━┳━━━━┓
┃ 0 ┃ 1  ┃ 2  ┃ 3  ┃ 4  ┃ 5  ┃ 6  ┃
┡━━━╇━━━━╇━━━━╇━━━━╇━━━━╇━━━━╇━━━━┩
│   │    │    │    │    │    │    │
├───┼────┼────┼────┼────┼────┼────┤
│   │    │    │    │    │    │    │
├───┼────┼────┼────┼────┼────┼────┤
│   │    │    │    │ 🟠 │ 🟠 │ 🟠 │
├───┼────┼────┼────┼────┼────┼────┤
│   │    │    │    │ 🔵 │ 🔵 │ 🔵 │
├───┼────┼────┼────┼────┼────┼────┤
│   │    │ 🔵 │    │ 🟠 │ 🟠 │ 🔵 │
├───┼────┼────┼────┼────┼────┼────┤
│   │ 🟠 │ 🔵 │ 🔵 │ 🔵 │ 🟠 │ 🟠 │
└───┴────┴────┴────┴────┴────┴────┘
Player 🟠. Col: 2
┏━━━┳━━━━┳━━━━┳━━━━┳━━━━┳━━━━┳━━━━┓
┃ 0 ┃ 1  ┃ 2  ┃ 3  ┃ 4  ┃ 5  ┃ 6  ┃
┡━━━╇━━━━╇━━━━╇━━━━╇━━━━╇━━━━╇━━━━┩
│   │    │    │    │    │    │    │
├───┼────┼────┼────┼────┼────┼────┤
│   │    │    │    │    │    │    │
├───┼────┼────┼────┼────┼────┼────┤
│   │    │    │    │ 🟠 │ 🟠 │ 🟠 │
├───┼────┼────┼────┼────┼────┼────┤
│   │    │ 🟠 │    │ 🔵 │ 🔵 │ 🔵 │
├───┼────┼────┼────┼────┼────┼────┤
│   │    │ 🔵 │    │ 🟠 │ 🟠 │ 🔵 │
├───┼────┼────┼────┼────┼────┼────┤
│   │ 🟠 │ 🔵 │ 🔵 │ 🔵 │ 🟠 │ 🟠 │
└───┴────┴────┴────┴────┴────┴────┘
Player 🔵. Col: 0
┏━━━━┳━━━━┳━━━━┳━━━━┳━━━━┳━━━━┳━━━━┓
┃ 0  ┃ 1  ┃ 2  ┃ 3  ┃ 4  ┃ 5  ┃ 6  ┃
┡━━━━╇━━━━╇━━━━╇━━━━╇━━━━╇━━━━╇━━━━┩
│    │    │    │    │    │    │    │
├────┼────┼────┼────┼────┼────┼────┤
│    │    │    │    │    │    │    │
├────┼────┼────┼────┼────┼────┼────┤
│    │    │    │    │ 🟠 │ 🟠 │ 🟠 │
├────┼────┼────┼────┼────┼────┼────┤
│    │    │ 🟠 │    │ 🔵 │ 🔵 │ 🔵 │
├────┼────┼────┼────┼────┼────┼────┤
│    │    │ 🔵 │    │ 🟠 │ 🟠 │ 🔵 │
├────┼────┼────┼────┼────┼────┼────┤
│ 🔵 │ 🟠 │ 🔵 │ 🔵 │ 🔵 │ 🟠 │ 🟠 │
└────┴────┴────┴────┴────┴────┴────┘
Player 🟠. Col: 3
┏━━━━┳━━━━┳━━━━┳━━━━┳━━━━┳━━━━┳━━━━┓
┃ 0  ┃ 1  ┃ 2  ┃ 3  ┃ 4  ┃ 5  ┃ 6  ┃
┡━━━━╇━━━━╇━━━━╇━━━━╇━━━━╇━━━━╇━━━━┩
│    │    │    │    │    │    │    │
├────┼────┼────┼────┼────┼────┼────┤
│    │    │    │    │    │    │    │
├────┼────┼────┼────┼────┼────┼────┤
│    │    │    │    │ 🟠 │ 🟠 │ 🟠 │
├────┼────┼────┼────┼────┼────┼────┤
│    │    │ 🟠 │    │ 🔵 │ 🔵 │ 🔵 │
├────┼────┼────┼────┼────┼────┼────┤
│    │    │ 🔵 │ 🟠 │ 🟠 │ 🟠 │ 🔵 │
├────┼────┼────┼────┼────┼────┼────┤
│ 🔵 │ 🟠 │ 🔵 │ 🔵 │ 🔵 │ 🟠 │ 🟠 │
└────┴────┴────┴────┴────┴────┴────┘
Player 🔵. Col: 3 
┏━━━━┳━━━━┳━━━━┳━━━━┳━━━━┳━━━━┳━━━━┓
┃ 0  ┃ 1  ┃ 2  ┃ 3  ┃ 4  ┃ 5  ┃ 6  ┃
┡━━━━╇━━━━╇━━━━╇━━━━╇━━━━╇━━━━╇━━━━┩
│    │    │    │    │    │    │    │
├────┼────┼────┼────┼────┼────┼────┤
│    │    │    │    │    │    │    │
├────┼────┼────┼────┼────┼────┼────┤
│    │    │    │    │ 🟠 │ 🟠 │ 🟠 │
├────┼────┼────┼────┼────┼────┼────┤
│    │    │ 🟠 │ 🔵 │ 🔵 │ 🔵 │ 🔵 │
├────┼────┼────┼────┼────┼────┼────┤
│    │    │ 🔵 │ 🟠 │ 🟠 │ 🟠 │ 🔵 │
├────┼────┼────┼────┼────┼────┼────┤
│ 🔵 │ 🟠 │ 🔵 │ 🔵 │ 🔵 │ 🟠 │ 🟠 │
└────┴────┴────┴────┴────┴────┴────┘
WINNER IS PLAYER 🔵
❯ 
```
</details>