games.connect4.state¶

Connect4 game state module.

This module defines the core state representation for Connect4 games, including board representation, move tracking, and game status.

Example

>>> from haive.games.connect4.state import Connect4State
>>> from haive.games.connect4.models import Connect4Move
>>>
>>> # Initialize a new game
>>> state = Connect4State.initialize()
>>> state.board_string  # Get string representation
>>>
>>> # Check game properties
>>> state.is_column_full(3)  # Check if column is full
>>> state.get_next_row(3)    # Get next available row in column

Classes¶

Connect4State

State representation for a Connect4 game.

Module Contents¶

class games.connect4.state.Connect4State(/, **data)¶

Bases: haive.games.framework.base.state.GameState

State representation for a Connect4 game.

This class represents the complete state of a Connect4 game, including:

  • Board representation (6x7 grid)

  • Current player’s turn

  • Game status and winner

  • Move history

  • Position analysis for both players

The board is represented as a 6x7 grid of cells, where each cell can be:

  • None: Empty cell

  • “red”: Red player’s piece

  • “yellow”: Yellow player’s piece

Parameters:

data (Any)

board¶

6x7 board representation (rows x columns)

Type:

list[list[str | None]]

turn¶

Current player’s turn

Type:

Literal[“red”, “yellow”]

game_status¶

Game status

Type:

Literal[“ongoing”, “red_win”, “yellow_win”, “draw”]

move_history¶

History of moves made in the game

Type:

list[Connect4Move]

red_analysis¶

Analysis history for the red player

Type:

list[dict]

yellow_analysis¶

Analysis history for the yellow player

Type:

list[dict]

winner¶

Winner of the game, if any

Type:

Optional[str]

error_message¶

Error message from the last operation

Type:

Optional[str]

Examples

>>> state = Connect4State.initialize()
>>> state.turn
'red'
>>> state.is_column_full(3)
False

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

get_next_row(column)¶

Get the next available row in a column.

Returns the row index where a piece would land if dropped in the specified column, or None if the column is full.

Parameters:

column (int) – Column index (0-6)

Returns:

Row index for the next piece, or None if column is full

Return type:

Optional[int]

Example

>>> state = Connect4State.initialize()
>>> state.get_next_row(3)
5  # Bottom row (gravity effect)
classmethod initialize()¶

Initialize a new Connect4 game.

Creates a new Connect4 game state with an empty board, red player starting, and game status set to ongoing.

Returns:

A new game state

Return type:

Connect4State

Example

>>> state = Connect4State.initialize()
>>> state.turn
'red'
>>> state.game_status
'ongoing'
is_column_full(column)¶

Check if a column is full.

Parameters:

column (int) – Column index to check (0-6)

Returns:

True if the column is full, False otherwise

Return type:

bool

Example

>>> state = Connect4State.initialize()
>>> state.is_column_full(3)
False
classmethod validate_board_dimensions(board)¶

Validate board dimensions are 6x7.

Parameters:

board – Board to validate

Returns:

Validated board

Return type:

list[list[str | None]]

Raises:

ValueError – If board dimensions are invalid

property board_string: str¶

Get a string representation of the board.

Returns a formatted string representation of the current board state, with column and row indices, cell contents, and borders.

Returns:

String representation of the board

Return type:

str

Example

>>> state = Connect4State.initialize()
>>> # state.board_string displays:
  0 1 2 3 4 5 6
  -------------
0| | | | | | | |
1| | | | | | | |
2| | | | | | | |
3| | | | | | | |
4| | | | | | | |
5| | | | | | | |
  -------------
  0 1 2 3 4 5 6