Skip to content

board

This module defines the Board class for managing the state of a Connect Four game.

Classes:

Name Description
Board

Represents the state of a Connect Four board. Mostly a thin wrapper around BoardCore.

Board 

Board(init_with: Sequence[Sequence[int]] | Sequence[int] | str | None = None)

Represents the state of a Connect Four board. Mostly a thin wrapper around BoardCore.

Parameters:

Name Type Description Default

init_with

Sequence[Sequence[int]] | Sequence[int] | str | None

Optional initial board state. Accepts: - 2D array (list, tuple, numpy-array) with shape 7x6 or 6x7 - 1D sequence of ints: a move sequence of columns (e.g., [0, 0, 2, 2, 3, 3]) - String: A move sequence of columns as string (e.g., "002233") - None for an empty board

 None

Raises:

Type Description
ValueError

If the provided initial board state is invalid.
Example

You can initialize an empty board in multiple ways: 

import bitbully as bb

# Create an empty board using the default constructor.
board = bb.Board()  # Starts with no tokens placed.

# Alternatively, initialize the board explicitly from a 2D list.
# Each inner list represents a column (7 columns total, 6 rows each).
# A value of 0 indicates an empty cell; 1 and 2 would represent player tokens.
board = bb.Board([[0] * 6 for _ in range(7)])  # Equivalent to an empty board.

# You can also set up a specific board position manually using a 6 x 7 layout,
# where each inner list represents a row instead of a column.
# (Both layouts are accepted by BitBully for convenience.)
# For more complex examples using 2D arrays, see the examples below.
board = bb.Board([[0] * 7 for _ in range(6)])  # Also equivalent to an empty board.

# Display the board in text form.
# The __repr__ method shows the current state (useful for debugging or interactive use).
board
Expected output: 
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _

The recommended way to initialize an empty board is simply Board().

Example

You can also initialize a board with a sequence of moves: 

import bitbully as bb

# Initialize a board with a sequence of moves played in the center column.

# The list [3, 3, 3] represents three moves in column index 3 (zero-based).
# Moves alternate automatically between Player 1 (yellow, X) and Player 2 (red, O).
# After these three moves, the center column will contain:
#   - Row 0: Player 1 token (bottom)
#   - Row 1: Player 2 token
#   - Row 2: Player 1 token
board = bb.Board([3, 3, 3])

# Display the resulting board.
# The textual output shows the tokens placed in the center column.
board

Expected output: 

_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  X  _  _  _
_  _  _  O  _  _  _
_  _  _  X  _  _  _

Example

You can also initialize a board using a string containing a move sequence: 

import bitbully as bb

# Initialize a board using a compact move string.

# The string "33333111" represents a sequence of eight moves:
#   3 3 3 3 3 → five moves in the center column (index 3)
#   1 1 1 → three moves in the second column (index 1)
#
# Moves are applied in order, alternating automatically between Player 1 (yellow, X)
# and Player 2 (red, O), just as if you had called `board.play()` repeatedly.
#
# This shorthand is convenient for reproducing board states or test positions
# without having to provide long move lists.

board = bb.Board("33333111")

# Display the resulting board.
# The printed layout shows how the tokens stack in each column.
board
Expected output: 
_  _  _  _  _  _  _
_  _  _  X  _  _  _
_  _  _  O  _  _  _
_  O  _  X  _  _  _
_  X  _  O  _  _  _
_  O  _  X  _  _  _

Example

You can also initialize a board using a 2D array (list of lists): 

import bitbully as bb

# Use a 6 x 7 list (rows x columns) to set up a specific board position manually.

# Each inner list represents a row of the Connect-4 grid.
# Convention:
#   - 0 → empty cell
#   - 1 → Player 1 token (yellow, X)
#   - 2 → Player 2 token (red, O)
#
# The top list corresponds to the *top row* (row index 5),
# and the bottom list corresponds to the *bottom row* (row index 0).
# This layout matches the typical visual display of the board.

board_array = [
    [0, 0, 0, 0, 0, 0, 0],  # Row 5 (top)
    [0, 0, 0, 1, 0, 0, 0],  # Row 4: Player 1 token in column 3
    [0, 0, 0, 2, 0, 0, 0],  # Row 3: Player 2 token in column 3
    [0, 2, 0, 1, 0, 0, 0],  # Row 2: tokens in columns 1 and 3
    [0, 1, 0, 2, 0, 0, 0],  # Row 1: tokens in columns 1 and 3
    [0, 2, 0, 1, 0, 0, 0],  # Row 0 (bottom): tokens stacked lowest
]

# Create a Board instance directly from the 2D list.
# This allows reconstructing arbitrary positions (e.g., from test data or saved states)
# without replaying the move sequence.
board = bb.Board(board_array)

# Display the resulting board state in text form.
board
Expected output: 
_  _  _  _  _  _  _
_  _  _  X  _  _  _
_  _  _  O  _  _  _
_  O  _  X  _  _  _
_  X  _  O  _  _  _
_  O  _  X  _  _  _

Example

You can also initialize a board using a 2D (7 x 6) array with columns as inner lists: 

import bitbully as bb

# Use a 7 x 6 list (columns x rows) to set up a specific board position manually.

# Each inner list represents a **column** of the Connect-4 board, from left (index 0)
# to right (index 6). Each column contains six entries — one for each row, from
# bottom (index 0) to top (index 5).
#
# Convention:
#   - 0 → empty cell
#   - 1 → Player 1 token (yellow, X)
#   - 2 → Player 2 token (red, O)
#
# This column-major layout matches the internal representation used by BitBully,
# where tokens are dropped into columns rather than filled row by row.

board_array = [
    [0, 0, 0, 0, 0, 0],  # Column 0 (leftmost)
    [2, 1, 2, 0, 0, 0],  # Column 1
    [0, 0, 0, 0, 0, 0],  # Column 2
    [1, 2, 1, 2, 1, 0],  # Column 3 (center)
    [0, 0, 0, 0, 0, 0],  # Column 4
    [0, 0, 0, 0, 0, 0],  # Column 5
    [0, 0, 0, 0, 0, 0],  # Column 6 (rightmost)
]

# Create a Board instance directly from the 2D list.
# This allows reconstructing any arbitrary position (e.g., test cases, saved games)
# without replaying all moves individually.
board = bb.Board(board_array)

# Display the resulting board.
# The text output shows tokens as they would appear in a real Connect-4 grid.
board
Expected output: 
_  _  _  _  _  _  _
_  _  _  X  _  _  _
_  _  _  O  _  _  _
_  O  _  X  _  _  _
_  X  _  O  _  _  _
_  O  _  X  _  _  _

Referenced by: Returned by: Used by:

Methods:

Name Description
__eq__

Checks equality between two Board instances.
__hash__

Returns a hash of the Board instance for use in hash-based collections.
__ne__

Checks inequality between two Board instances.
__repr__

Returns a string representation of the Board instance.
__str__

Return a human-readable ASCII representation (same as to_string()).
all_positions

Find all positions reachable from the current position up to a given ply.
can_win_next

Checks if the current player can win in the next move.
copy

Creates a copy of the current Board instance.
count_tokens

Counts the total number of tokens currently placed on the board.
current_player

Returns the player whose turn it is to move.
from_array

Creates a board directly from a 2D array representation.
from_moves

Creates a board by replaying a sequence of moves from the empty position.
has_win

Checks if the current player has a winning position.
is_full

Checks whether the board has any empty cells left.
is_game_over

Checks whether the game has ended (win or draw).
is_legal_move

Checks if a move (column) is legal in the current position.
legal_moves

Returns a list of all legal moves (non-full columns) for the current board state.
mirror

Returns a new Board instance that is the mirror image of the current board.
moves_left

Returns the number of moves left until the board is full.
play

Plays one or more moves for the current player.
play_on_copy

Return a new board with the given move applied, leaving the current board unchanged.
random_board

Generates a random board state by playing a specified number of random moves.
reset_board

Resets the board or sets (overrides) the board to a specific state.
to_array

Returns the board state as a 2D array (list of lists).
to_huffman

Encode the current board position into a Huffman-compressed byte sequence.
to_string

Returns a human-readable ASCII representation of the board.
uid

Returns a unique identifier for the current board state.
winner

Returns the winning player, if the game has been won.

Attributes:

Name Type Description
N_COLUMNS int
N_ROWS int
Player
Source code in src/bitbully/board.py 
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
def __init__(self, init_with: Sequence[Sequence[int]] | Sequence[int] | str | None = None) -> None:
    """Initializes a Board instance.

    Args:
        init_with (Sequence[Sequence[int]] | Sequence[int] | str | None):
            Optional initial board state. Accepts:
            - 2D array (list, tuple, numpy-array) with shape 7x6 or 6x7
            - 1D sequence of ints: a move sequence of columns (e.g., [0, 0, 2, 2, 3, 3])
            - String: A move sequence of columns as string (e.g., "002233")
            - None for an empty board

    Raises:
        ValueError: If the provided initial board state is invalid.

    Example:
        You can initialize an empty board in multiple ways:
        ```python
        import bitbully as bb

        # Create an empty board using the default constructor.
        board = bb.Board()  # Starts with no tokens placed.

        # Alternatively, initialize the board explicitly from a 2D list.
        # Each inner list represents a column (7 columns total, 6 rows each).
        # A value of 0 indicates an empty cell; 1 and 2 would represent player tokens.
        board = bb.Board([[0] * 6 for _ in range(7)])  # Equivalent to an empty board.

        # You can also set up a specific board position manually using a 6 x 7 layout,
        # where each inner list represents a row instead of a column.
        # (Both layouts are accepted by BitBully for convenience.)
        # For more complex examples using 2D arrays, see the examples below.
        board = bb.Board([[0] * 7 for _ in range(6)])  # Also equivalent to an empty board.

        # Display the board in text form.
        # The __repr__ method shows the current state (useful for debugging or interactive use).
        board
        ```
        Expected output:
        ```text
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        ```

    The recommended way to initialize an empty board is simply `Board()`.

    Example:
        You can also initialize a board with a sequence of moves:
        ```python
        import bitbully as bb

        # Initialize a board with a sequence of moves played in the center column.

        # The list [3, 3, 3] represents three moves in column index 3 (zero-based).
        # Moves alternate automatically between Player 1 (yellow, X) and Player 2 (red, O).
        # After these three moves, the center column will contain:
        #   - Row 0: Player 1 token (bottom)
        #   - Row 1: Player 2 token
        #   - Row 2: Player 1 token
        board = bb.Board([3, 3, 3])

        # Display the resulting board.
        # The textual output shows the tokens placed in the center column.
        board
        ```

        Expected output:
        ```text
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  X  _  _  _
        _  _  _  O  _  _  _
        _  _  _  X  _  _  _
        ```

    Example:
        You can also initialize a board using a string containing a move sequence:
        ```python
        import bitbully as bb

        # Initialize a board using a compact move string.

        # The string "33333111" represents a sequence of eight moves:
        #   3 3 3 3 3 → five moves in the center column (index 3)
        #   1 1 1 → three moves in the second column (index 1)
        #
        # Moves are applied in order, alternating automatically between Player 1 (yellow, X)
        # and Player 2 (red, O), just as if you had called `board.play()` repeatedly.
        #
        # This shorthand is convenient for reproducing board states or test positions
        # without having to provide long move lists.

        board = bb.Board("33333111")

        # Display the resulting board.
        # The printed layout shows how the tokens stack in each column.
        board
        ```
        Expected output:
        ```text
        _  _  _  _  _  _  _
        _  _  _  X  _  _  _
        _  _  _  O  _  _  _
        _  O  _  X  _  _  _
        _  X  _  O  _  _  _
        _  O  _  X  _  _  _
        ```

    Example:
        You can also initialize a board using a 2D array (list of lists):
        ```python
        import bitbully as bb

        # Use a 6 x 7 list (rows x columns) to set up a specific board position manually.

        # Each inner list represents a row of the Connect-4 grid.
        # Convention:
        #   - 0 → empty cell
        #   - 1 → Player 1 token (yellow, X)
        #   - 2 → Player 2 token (red, O)
        #
        # The top list corresponds to the *top row* (row index 5),
        # and the bottom list corresponds to the *bottom row* (row index 0).
        # This layout matches the typical visual display of the board.

        board_array = [
            [0, 0, 0, 0, 0, 0, 0],  # Row 5 (top)
            [0, 0, 0, 1, 0, 0, 0],  # Row 4: Player 1 token in column 3
            [0, 0, 0, 2, 0, 0, 0],  # Row 3: Player 2 token in column 3
            [0, 2, 0, 1, 0, 0, 0],  # Row 2: tokens in columns 1 and 3
            [0, 1, 0, 2, 0, 0, 0],  # Row 1: tokens in columns 1 and 3
            [0, 2, 0, 1, 0, 0, 0],  # Row 0 (bottom): tokens stacked lowest
        ]

        # Create a Board instance directly from the 2D list.
        # This allows reconstructing arbitrary positions (e.g., from test data or saved states)
        # without replaying the move sequence.
        board = bb.Board(board_array)

        # Display the resulting board state in text form.
        board
        ```
        Expected output:
        ```text
        _  _  _  _  _  _  _
        _  _  _  X  _  _  _
        _  _  _  O  _  _  _
        _  O  _  X  _  _  _
        _  X  _  O  _  _  _
        _  O  _  X  _  _  _
        ```

    Example:
        You can also initialize a board using a 2D (7 x 6) array with columns as inner lists:
        ```python
        import bitbully as bb

        # Use a 7 x 6 list (columns x rows) to set up a specific board position manually.

        # Each inner list represents a **column** of the Connect-4 board, from left (index 0)
        # to right (index 6). Each column contains six entries — one for each row, from
        # bottom (index 0) to top (index 5).
        #
        # Convention:
        #   - 0 → empty cell
        #   - 1 → Player 1 token (yellow, X)
        #   - 2 → Player 2 token (red, O)
        #
        # This column-major layout matches the internal representation used by BitBully,
        # where tokens are dropped into columns rather than filled row by row.

        board_array = [
            [0, 0, 0, 0, 0, 0],  # Column 0 (leftmost)
            [2, 1, 2, 0, 0, 0],  # Column 1
            [0, 0, 0, 0, 0, 0],  # Column 2
            [1, 2, 1, 2, 1, 0],  # Column 3 (center)
            [0, 0, 0, 0, 0, 0],  # Column 4
            [0, 0, 0, 0, 0, 0],  # Column 5
            [0, 0, 0, 0, 0, 0],  # Column 6 (rightmost)
        ]

        # Create a Board instance directly from the 2D list.
        # This allows reconstructing any arbitrary position (e.g., test cases, saved games)
        # without replaying all moves individually.
        board = bb.Board(board_array)

        # Display the resulting board.
        # The text output shows tokens as they would appear in a real Connect-4 grid.
        board
        ```
        Expected output:
        ```text
        _  _  _  _  _  _  _
        _  _  _  X  _  _  _
        _  _  _  O  _  _  _
        _  O  _  X  _  _  _
        _  X  _  O  _  _  _
        _  O  _  X  _  _  _
        ```
    """
    self._board = bitbully_core.BoardCore()
    if init_with is not None and not self.reset_board(init_with):
        raise ValueError(
            "Invalid initial board state provided. Check the examples in the docstring for valid formats."
        )

N_COLUMNS class-attribute 

N_COLUMNS: int = N_COLUMNS

N_ROWS class-attribute 

N_ROWS: int = N_ROWS

Player class-attribute instance-attribute 

Player = Player

__eq__ 

__eq__(value: object) -> bool

Checks equality between two Board instances.

Notes
  • Equality checks in BitBully compare the exact board state (bit patterns), not just the move history.
  • Two different move sequences can still yield the same position if they result in identical token configurations.
  • This is useful for comparing solver states, verifying test positions, or detecting transpositions in search algorithms.

Parameters:

Name Type Description Default

value

object

The other Board instance to compare against.

 required

Returns:

Name Type Description
bool bool

True if both boards are equal, False otherwise.

Raises:

Type Description
NotImplementedError

If the other value is not a Board instance.
Example 
import bitbully as bb

# Create two boards that should represent *identical* game states.
board1 = bb.Board()
assert board1.play("33333111")

board2 = bb.Board()
# Play the same position step by step using a different but equivalent sequence.
# Internally, the final bitboard state will match `board1`.
assert board2.play("31133331")

# Boards with identical token placements are considered equal.
# Equality (`==`) and inequality (`!=`) operators are overloaded for convenience.
assert board1 == board2
assert not (board1 != board2)

# ------------------------------------------------------------------------------

# Create two boards that differ by one move.
board1 = bb.Board("33333111")
board2 = bb.Board("33333112")  # One extra move in the last column (index 2)

# Since the token layout differs, equality no longer holds.
assert board1 != board2
assert not (board1 == board2)
Referenced by:
Source code in src/bitbully/board.py 
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
def __eq__(self, value: object) -> bool:
    """Checks equality between two Board instances.

    Notes:
        - Equality checks in BitBully compare the *exact board state* (bit patterns),
          not just the move history.
        - Two different move sequences can still yield the same position if they
          result in identical token configurations.
        - This is useful for comparing solver states, verifying test positions,
          or detecting transpositions in search algorithms.

    Args:
        value (object): The other Board instance to compare against.

    Returns:
        bool: True if both boards are equal, False otherwise.

    Raises:
        NotImplementedError: If the other value is not a Board instance.

    Example:
        ```python
        import bitbully as bb

        # Create two boards that should represent *identical* game states.
        board1 = bb.Board()
        assert board1.play("33333111")

        board2 = bb.Board()
        # Play the same position step by step using a different but equivalent sequence.
        # Internally, the final bitboard state will match `board1`.
        assert board2.play("31133331")

        # Boards with identical token placements are considered equal.
        # Equality (`==`) and inequality (`!=`) operators are overloaded for convenience.
        assert board1 == board2
        assert not (board1 != board2)

        # ------------------------------------------------------------------------------

        # Create two boards that differ by one move.
        board1 = bb.Board("33333111")
        board2 = bb.Board("33333112")  # One extra move in the last column (index 2)

        # Since the token layout differs, equality no longer holds.
        assert board1 != board2
        assert not (board1 == board2)
        ```
    """
    if not isinstance(value, Board):
        raise NotImplementedError("Can only compare with another Board instance.")
    return bool(self._board == value._board)

__hash__ 

__hash__() -> int

Returns a hash of the Board instance for use in hash-based collections.

Returns:

Name Type Description
int int

The hash value of the Board instance.
Example 

import bitbully as bb

# Create two boards that represent the same final position.
# The first board is initialized directly from a move string.
board1 = bb.Board("33333111")

# The second board is built incrementally by playing an equivalent sequence of moves.
# Even though the order of intermediate plays differs, the final layout of tokens
# (and thus the internal bitboard state) will be identical to `board1`.
board2 = bb.Board()
board2.play("31133331")

# Boards with identical configurations produce the same hash value.
# This allows them to be used efficiently as keys in dictionaries or members of sets.
assert hash(board1) == hash(board2)

# Display the board's hash value.
hash(board1)
Expected output: 
971238920548618160

Source code in src/bitbully/board.py 
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
def __hash__(self) -> int:
    """Returns a hash of the Board instance for use in hash-based collections.

    Returns:
        int: The hash value of the Board instance.

    Example:
        ```python
        import bitbully as bb

        # Create two boards that represent the same final position.
        # The first board is initialized directly from a move string.
        board1 = bb.Board("33333111")

        # The second board is built incrementally by playing an equivalent sequence of moves.
        # Even though the order of intermediate plays differs, the final layout of tokens
        # (and thus the internal bitboard state) will be identical to `board1`.
        board2 = bb.Board()
        board2.play("31133331")

        # Boards with identical configurations produce the same hash value.
        # This allows them to be used efficiently as keys in dictionaries or members of sets.
        assert hash(board1) == hash(board2)

        # Display the board's hash value.
        hash(board1)
        ```
        Expected output:
        ```text
        971238920548618160
        ```
    """
    return self._board.hash()

__ne__ 

__ne__(value: object) -> bool

Checks inequality between two Board instances.

See the documentation for Board.eq for details.

Parameters:

Name Type Description Default

value

object

The other Board instance to compare against.

 required

Returns:

Name Type Description
bool bool

True if both boards are not equal, False otherwise.
Source code in src/bitbully/board.py 
283
284
285
286
287
288
289
290
291
292
293
294
def __ne__(self, value: object) -> bool:
    """Checks inequality between two Board instances.

    See the documentation for [Board.__eq__][src.bitbully.board.Board.__eq__] for details.

    Args:
        value (object): The other Board instance to compare against.

    Returns:
        bool: True if both boards are not equal, False otherwise.
    """
    return not self.__eq__(value)

__repr__ 

__repr__() -> str

Returns a string representation of the Board instance.

Source code in src/bitbully/board.py 
296
297
298
def __repr__(self) -> str:
    """Returns a string representation of the Board instance."""
    return f"{self._board}"

__str__ 

__str__() -> str

Return a human-readable ASCII representation (same as to_string()).

See the documentation for Board.to_string for details.

Source code in src/bitbully/board.py 
300
301
302
303
304
305
def __str__(self) -> str:
    """Return a human-readable ASCII representation (same as to_string()).

    See the documentation for [Board.to_string][src.bitbully.board.Board.to_string] for details.
    """
    return self.to_string()

all_positions 

all_positions(up_to_n_ply: int, exactly_n: bool) -> list[Board]

Find all positions reachable from the current position up to a given ply.

This is a high-level wrapper around bitbully_core.BoardCore.allPositions.

Starting from the current board, it generates all positions that can be reached by playing additional moves such that the resulting position has:

  • At most up_to_n_ply tokens on the board, if exactly_n is False.
  • Exactly up_to_n_ply tokens on the board, if exactly_n is True.
Note

The number of tokens already present in the current position is taken into account. If up_to_n_ply is smaller than self.count_tokens(), the result is typically empty.

This function can grow combinatorially with up_to_n_ply and the current position, so use it with care for large depths.

Parameters:

Name Type Description Default

up_to_n_ply

int

The maximum total number of tokens (ply) for generated positions. Must be between 0 and 42 (inclusive).

 required

exactly_n

bool

If True, only positions with exactly up_to_n_ply tokens are returned. If False, all positions with a token count between the current number of tokens and up_to_n_ply are included.

 required

Returns:

Type Description
list[Board]

list[Board]: A list of :class:Board instances representing all
list[Board]

reachable positions that satisfy the ply constraint.

Raises:

Type Description
ValueError

If up_to_n_ply is outside the range [0, 42].
Example

Compute all positions at exactly 3 ply from the empty board:

import bitbully as bb

# Start from an empty board.
board = bb.Board()

# Generate all positions that contain exactly 3 tokens.
positions = board.all_positions(3, exactly_n=True)

# According to OEIS A212693, there are exactly 238 distinct
# reachable positions with 3 played moves in standard Connect-4.
assert len(positions) == 238

Reference: - Number of distinct positions at ply n: https://oeis.org/A212693

Source code in src/bitbully/board.py 
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
def all_positions(self, up_to_n_ply: int, exactly_n: bool) -> list[Board]:
    """Find all positions reachable from the current position up to a given ply.

    This is a high-level wrapper around
    `bitbully_core.BoardCore.allPositions`.

    Starting from the **current** board, it generates all positions that can be
    reached by playing additional moves such that the resulting position has:

    - At most ``up_to_n_ply`` tokens on the board, if ``exactly_n`` is ``False``.
    - Exactly ``up_to_n_ply`` tokens on the board, if ``exactly_n`` is ``True``.

    Note:
        The number of tokens already present in the current position is taken
        into account. If ``up_to_n_ply`` is smaller than
        ``self.count_tokens()``, the result is typically empty.

        This function can grow combinatorially with ``up_to_n_ply`` and the
        current position, so use it with care for large depths.

    Args:
        up_to_n_ply (int):
            The maximum total number of tokens (ply) for generated positions.
            Must be between 0 and 42 (inclusive).
        exactly_n (bool):
            If ``True``, only positions with exactly ``up_to_n_ply`` tokens
            are returned. If ``False``, all positions with a token count
            between the current number of tokens and ``up_to_n_ply`` are
            included.

    Returns:
        list[Board]: A list of :class:`Board` instances representing all
        reachable positions that satisfy the ply constraint.

    Raises:
        ValueError: If ``up_to_n_ply`` is outside the range ``[0, 42]``.

    Example:
        Compute all positions at exactly 3 ply from the empty board:

        ```python
        import bitbully as bb

        # Start from an empty board.
        board = bb.Board()

        # Generate all positions that contain exactly 3 tokens.
        positions = board.all_positions(3, exactly_n=True)

        # According to OEIS A212693, there are exactly 238 distinct
        # reachable positions with 3 played moves in standard Connect-4.
        assert len(positions) == 238
        ```

        Reference:
            - Number of distinct positions at ply *n*:
              https://oeis.org/A212693

    """
    if not 0 <= up_to_n_ply <= 42:
        raise ValueError(f"up_to_n_ply must be between 0 and 42 (inclusive), got {up_to_n_ply}.")

    # Delegate to the C++ core, which returns a list of BoardCore objects.
    core_positions = self._board.allPositions(up_to_n_ply, exactly_n)

    # Wrap each BoardCore in a high-level Board instance.
    positions: list[Board] = []
    for core_board in core_positions:
        b = Board()  # start with an empty high-level Board
        b._board = core_board  # replace its internal BoardCore
        positions.append(b)

    return positions

can_win_next 

can_win_next(move: int | None = None) -> bool

Checks if the current player can win in the next move.

Parameters:

Name Type Description Default

move

int | None

Optional column to check for an immediate win. If None, checks all columns.

 None

Returns:

Name Type Description
bool bool

True if the current player can win next, False otherwise.

See also: Board.has_win.

Example 

import bitbully as bb

# Create a board from a move string.
# The string "332311" represents a short sequence of alternating moves
# that results in a nearly winning position for Player 1 (yellow, X).
board = bb.Board("332311")

# Display the current board state (see below)
print(board)

# Player 1 (yellow, X) — who is next to move — can win immediately
# by placing a token in either column 0 or column 4.
assert board.can_win_next(0)
assert board.can_win_next(4)

# However, playing in other columns does not result in an instant win.
assert not board.can_win_next(2)
assert not board.can_win_next(3)

# You can also call `can_win_next()` without arguments to perform a general check.
# It returns True if the current player has *any* winning move available.
assert board.can_win_next()
The board we created above looks like this: 
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  O  _  _  _
_  O  _  O  _  _  _
_  X  X  X  _  _  _

Referenced by:
Source code in src/bitbully/board.py 
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
def can_win_next(self, move: int | None = None) -> bool:
    """Checks if the current player can win in the next move.

    Args:
        move (int | None): Optional column to check for an immediate win. If None, checks all columns.

    Returns:
        bool: True if the current player can win next, False otherwise.

    See also: [`Board.has_win`][src.bitbully.board.Board.has_win].

    Example:
        ```python
        import bitbully as bb

        # Create a board from a move string.
        # The string "332311" represents a short sequence of alternating moves
        # that results in a nearly winning position for Player 1 (yellow, X).
        board = bb.Board("332311")

        # Display the current board state (see below)
        print(board)

        # Player 1 (yellow, X) — who is next to move — can win immediately
        # by placing a token in either column 0 or column 4.
        assert board.can_win_next(0)
        assert board.can_win_next(4)

        # However, playing in other columns does not result in an instant win.
        assert not board.can_win_next(2)
        assert not board.can_win_next(3)

        # You can also call `can_win_next()` without arguments to perform a general check.
        # It returns True if the current player has *any* winning move available.
        assert board.can_win_next()
        ```
        The board we created above looks like this:
        ```text
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  O  _  _  _
        _  O  _  O  _  _  _
        _  X  X  X  _  _  _
        ```
    """
    if move is None:
        return self._board.canWin()
    return bool(self._board.canWin(move))

copy 

copy() -> Board

Creates a copy of the current Board instance.

The copy() method returns a new Board object that represents the same position as the original at the time of copying. Subsequent changes to one board do not affect the other — they are completely independent.

Returns:

Name Type Description
Board Board

A new Board instance that is a copy of the current one.
Example

Create a board, copy it, and verify that both represent the same position: 

import bitbully as bb

# Create a board from a compact move string.
board = bb.Board("33333111")

# Create an independent copy of the current position.
board_copy = board.copy()

# Both boards represent the same position and are considered equal.
assert board == board_copy
assert hash(board) == hash(board_copy)
assert board.to_string() == board_copy.to_string()

# Display the board state.
print(board)
Expected output (both boards print the same position): 
_  _  _  _  _  _  _
_  _  _  X  _  _  _
_  _  _  O  _  _  _
_  O  _  X  _  _  _
_  X  _  O  _  _  _
_  O  _  X  _  _  _

Example

Modifying the copy does not affect the original: 

import bitbully as bb

board = bb.Board("33333111")

# Create a copy of the current position.
board_copy = board.copy()

# Play an additional move on the copied board only.
assert board_copy.play(0)  # Drop a token into the leftmost column.

# Now the boards represent different positions.
assert board != board_copy

# The original board remains unchanged.
print("Original:")
print(board)

print("Modified copy:")
print(board_copy)
Expected output: 
Original:

_  _  _  _  _  _  _
_  _  _  X  _  _  _
_  _  _  O  _  _  _
_  O  _  X  _  _  _
_  X  _  O  _  _  _
_  O  _  X  _  _  _

Modified copy:

_  _  _  _  _  _  _
_  _  _  X  _  _  _
_  _  _  O  _  _  _
_  O  _  X  _  _  _
_  X  _  O  _  _  _
X  O  _  X  _  _  _

Source code in src/bitbully/board.py 
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
def copy(self) -> Board:
    """Creates a copy of the current Board instance.

    The `copy()` method returns a new `Board` object that represents the
    *same position* as the original at the time of copying. Subsequent
    changes to one board do **not** affect the other — they are completely
    independent.

    Returns:
        Board: A new Board instance that is a copy of the current one.

    Example:
        Create a board, copy it, and verify that both represent the same position:
        ```python
        import bitbully as bb

        # Create a board from a compact move string.
        board = bb.Board("33333111")

        # Create an independent copy of the current position.
        board_copy = board.copy()

        # Both boards represent the same position and are considered equal.
        assert board == board_copy
        assert hash(board) == hash(board_copy)
        assert board.to_string() == board_copy.to_string()

        # Display the board state.
        print(board)
        ```
        Expected output (both boards print the same position):
        ```text
        _  _  _  _  _  _  _
        _  _  _  X  _  _  _
        _  _  _  O  _  _  _
        _  O  _  X  _  _  _
        _  X  _  O  _  _  _
        _  O  _  X  _  _  _
        ```

    Example:
        Modifying the copy does not affect the original:
        ```python
        import bitbully as bb

        board = bb.Board("33333111")

        # Create a copy of the current position.
        board_copy = board.copy()

        # Play an additional move on the copied board only.
        assert board_copy.play(0)  # Drop a token into the leftmost column.

        # Now the boards represent different positions.
        assert board != board_copy

        # The original board remains unchanged.
        print("Original:")
        print(board)

        print("Modified copy:")
        print(board_copy)
        ```
        Expected output:
        ```text
        Original:

        _  _  _  _  _  _  _
        _  _  _  X  _  _  _
        _  _  _  O  _  _  _
        _  O  _  X  _  _  _
        _  X  _  O  _  _  _
        _  O  _  X  _  _  _

        Modified copy:

        _  _  _  _  _  _  _
        _  _  _  X  _  _  _
        _  _  _  O  _  _  _
        _  O  _  X  _  _  _
        _  X  _  O  _  _  _
        X  O  _  X  _  _  _
        ```
    """
    new_board = Board()
    new_board._board = self._board.copy()
    return new_board

count_tokens 

count_tokens() -> int

Counts the total number of tokens currently placed on the board.

This method simply returns how many moves have been played so far in the current position — that is, the number of occupied cells on the 7x6 grid.

It does not distinguish between players; it only reports the total number of tokens, regardless of whether they belong to Player 1 or Player 2.

Returns:

Name Type Description
int int

The total number of tokens on the board (between 0 and 42).
Example

Count tokens on an empty board: 

import bitbully as bb

board = bb.Board()  # No moves played yet.
assert board.count_tokens() == 0

# The board is completely empty.
print(board)
Expected output: 
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _

Example

Count tokens after a few moves: 

import bitbully as bb

# Play three moves in the center column (index 3).
board = bb.Board()
assert board.play([3, 3, 3])

# Three tokens have been placed on the board.
assert board.count_tokens() == 3

print(board)
Expected output: 
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  X  _  _  _
_  _  _  O  _  _  _
_  _  _  X  _  _  _

Example

Relation to the length of a move sequence: 

import bitbully as bb

moves = "33333111"  # 8 moves in total
board = bb.Board(moves)

# The number of tokens on the board always matches
# the number of moves that have been played.
# (as long as the input was valid)
assert board.count_tokens() == len(moves)

Source code in src/bitbully/board.py 
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
def count_tokens(self) -> int:
    """Counts the total number of tokens currently placed on the board.

    This method simply returns how many moves have been played so far in the
    current position — that is, the number of occupied cells on the 7x6 grid.

    It does **not** distinguish between players; it only reports the total
    number of tokens, regardless of whether they belong to Player 1 or Player 2.

    Returns:
        int: The total number of tokens on the board (between 0 and 42).

    Example:
        Count tokens on an empty board:
        ```python
        import bitbully as bb

        board = bb.Board()  # No moves played yet.
        assert board.count_tokens() == 0

        # The board is completely empty.
        print(board)
        ```
        Expected output:
        ```text
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        ```

    Example:
        Count tokens after a few moves:
        ```python
        import bitbully as bb

        # Play three moves in the center column (index 3).
        board = bb.Board()
        assert board.play([3, 3, 3])

        # Three tokens have been placed on the board.
        assert board.count_tokens() == 3

        print(board)
        ```
        Expected output:
        ```text
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  X  _  _  _
        _  _  _  O  _  _  _
        _  _  _  X  _  _  _
        ```

    Example:
        Relation to the length of a move sequence:
        ```python
        import bitbully as bb

        moves = "33333111"  # 8 moves in total
        board = bb.Board(moves)

        # The number of tokens on the board always matches
        # the number of moves that have been played.
        # (as long as the input was valid)
        assert board.count_tokens() == len(moves)
        ```
    """
    return self._board.countTokens()

current_player 

current_player() -> int

Returns the player whose turn it is to move.

The current player is derived from the parity of the number of tokens on the board:

  • Player 1 (yellow, X) moves first on an empty board.
  • After an even number of moves → it is Player 1's turn.
  • After an odd number of moves → it is Player 2's turn.

Returns:

Name Type Description
int int

The player to move:

  • 1 → Player 1 (yellow, X)
  • 2 → Player 2 (red, O)
Example 
import bitbully as bb

# Empty board → Player 1 starts.
board = bb.Board()
assert board.current_player() == 1
assert board.count_tokens() == 0

# After one move, it's Player 2's turn.
assert board.play(3)
assert board.count_tokens() == 1
assert board.current_player() == 2

# After a second move, it's again Player 1's turn.
assert board.play(4)
assert board.count_tokens() == 2
assert board.current_player() == 1
Source code in src/bitbully/board.py 
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
def current_player(self) -> int:
    """Returns the player whose turn it is to move.

    The current player is derived from the **parity** of the number of tokens
    on the board:

    - Player 1 (yellow, ``X``) moves first on an empty board.
    - After an even number of moves → it is Player 1's turn.
    - After an odd  number of moves → it is Player 2's turn.

    Returns:
        int:
            The player to move:

            - ``1`` → Player 1 (yellow, ``X``)
            - ``2`` → Player 2 (red, ``O``)

    Example:
        ```python
        import bitbully as bb

        # Empty board → Player 1 starts.
        board = bb.Board()
        assert board.current_player() == 1
        assert board.count_tokens() == 0

        # After one move, it's Player 2's turn.
        assert board.play(3)
        assert board.count_tokens() == 1
        assert board.current_player() == 2

        # After a second move, it's again Player 1's turn.
        assert board.play(4)
        assert board.count_tokens() == 2
        assert board.current_player() == 1
        ```
    """
    # Empty board: Player 1
    return 1 if self.count_tokens() % 2 == 0 else 2

from_array classmethod 

from_array(arr: Sequence[Sequence[int]]) -> Board

Creates a board directly from a 2D array representation.

This is a convenience wrapper around the main constructor board.Board and accepts the same array formats:

  • Row-major: 6 x 7 ([row][column]), top row first.
  • Column-major: 7 x 6 ([column][row]), left column first.

Values must follow the usual convention:

  • 0 → empty cell
  • 1 → Player 1 token (yellow, X)
  • 2 → Player 2 token (red, O)

Parameters:

Name Type Description Default

arr

Sequence[Sequence[int]]

A 2D array describing the board state, either in row-major or column-major layout. See the examples in Board for details.

 required

Returns:

Name Type Description
Board Board

A new Board instance representing the given layout.
Example

Using a 6 x 7 row-major layout: 

import bitbully as bb

board_array = [
    [0, 0, 0, 0, 0, 0, 0],  # Row 5 (top)
    [0, 0, 0, 1, 0, 0, 0],  # Row 4
    [0, 0, 0, 2, 0, 0, 0],  # Row 3
    [0, 2, 0, 1, 0, 0, 0],  # Row 2
    [0, 1, 0, 2, 0, 0, 0],  # Row 1
    [0, 2, 0, 1, 0, 0, 0],  # Row 0 (bottom)
]

board = bb.Board.from_array(board_array)
print(board)

Example

Using a 7 x 6 column-major layout: 

import bitbully as bb

board_array = [
    [0, 0, 0, 0, 0, 0],  # Column 0
    [2, 1, 2, 1, 0, 0],  # Column 1
    [0, 0, 0, 0, 0, 0],  # Column 2
    [1, 2, 1, 2, 1, 0],  # Column 3
    [0, 0, 0, 0, 0, 0],  # Column 4
    [2, 1, 2, 0, 0, 0],  # Column 5
    [0, 0, 0, 0, 0, 0],  # Column 6
]

board = bb.Board.from_array(board_array)

# Round-trip via to_array:
assert board.to_array() == board_array

Source code in src/bitbully/board.py 
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
@classmethod
def from_array(cls, arr: Sequence[Sequence[int]]) -> Board:
    """Creates a board directly from a 2D array representation.

    This is a convenience wrapper around the main constructor [board.Board][src.bitbully.board.Board]
    and accepts the same array formats:

    - **Row-major**: 6 x 7 (``[row][column]``), top row first.
    - **Column-major**: 7 x 6 (``[column][row]``), left column first.

    Values must follow the usual convention:

    - ``0`` → empty cell
    - ``1`` → Player 1 token (yellow, ``X``)
    - ``2`` → Player 2 token (red, ``O``)

    Args:
        arr (Sequence[Sequence[int]]):
            A 2D array describing the board state, either in row-major or
            column-major layout. See the examples in
            [Board][src.bitbully.board.Board] for details.

    Returns:
        Board:
            A new `Board` instance representing the given layout.

    Example:
        Using a 6 x 7 row-major layout:
        ```python
        import bitbully as bb

        board_array = [
            [0, 0, 0, 0, 0, 0, 0],  # Row 5 (top)
            [0, 0, 0, 1, 0, 0, 0],  # Row 4
            [0, 0, 0, 2, 0, 0, 0],  # Row 3
            [0, 2, 0, 1, 0, 0, 0],  # Row 2
            [0, 1, 0, 2, 0, 0, 0],  # Row 1
            [0, 2, 0, 1, 0, 0, 0],  # Row 0 (bottom)
        ]

        board = bb.Board.from_array(board_array)
        print(board)
        ```

    Example:
        Using a 7 x 6 column-major layout:
        ```python
        import bitbully as bb

        board_array = [
            [0, 0, 0, 0, 0, 0],  # Column 0
            [2, 1, 2, 1, 0, 0],  # Column 1
            [0, 0, 0, 0, 0, 0],  # Column 2
            [1, 2, 1, 2, 1, 0],  # Column 3
            [0, 0, 0, 0, 0, 0],  # Column 4
            [2, 1, 2, 0, 0, 0],  # Column 5
            [0, 0, 0, 0, 0, 0],  # Column 6
        ]

        board = bb.Board.from_array(board_array)

        # Round-trip via to_array:
        assert board.to_array() == board_array
        ```
    """
    return cls(arr)

from_moves classmethod 

from_moves(moves: Sequence[int] | str) -> Board

Creates a board by replaying a sequence of moves from the empty position.

This is a convenience constructor around Board.play. It starts from an empty board and applies the given move sequence, assuming it is legal (no out-of-range columns, no moves in full columns, etc.).

Parameters:

Name Type Description Default

moves

Sequence[int] | str

The move sequence to replay from the starting position. Accepts:

  • A sequence of integers (e.g. [3, 3, 3, 1])
  • A string of digits (e.g. "3331")

Each value represents a column index (0-6). Players alternate automatically between moves.

 required

Returns:

Name Type Description
Board Board

A new Board instance representing the final position after all moves have been applied.
Example 
import bitbully as bb

# Create a position directly from a compact move string.
board = bb.Board.from_moves("33333111")

# Equivalent to:
# board = bb.Board()
# assert board.play("33333111")

print(board)
assert board.count_tokens() == 8
assert not board.has_win()
Source code in src/bitbully/board.py 
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
@classmethod
def from_moves(cls, moves: Sequence[int] | str) -> Board:
    """Creates a board by replaying a sequence of moves from the empty position.

    This is a convenience constructor around [Board.play][src.bitbully.board.Board.play].
    It starts from an empty board and applies the given move sequence, assuming
    it is **legal** (no out-of-range columns, no moves in full columns, etc.).

    Args:
        moves (Sequence[int] | str):
            The move sequence to replay from the starting position. Accepts:

            - A sequence of integers (e.g. ``[3, 3, 3, 1]``)
            - A string of digits (e.g. ``"3331"``)

            Each value represents a column index (0-6). Players alternate
            automatically between moves.

    Returns:
        Board:
            A new `Board` instance representing the final position
            after all moves have been applied.

    Example:
        ```python
        import bitbully as bb

        # Create a position directly from a compact move string.
        board = bb.Board.from_moves("33333111")

        # Equivalent to:
        # board = bb.Board()
        # assert board.play("33333111")

        print(board)
        assert board.count_tokens() == 8
        assert not board.has_win()
        ```
    """
    board = cls()
    assert board.play(moves)
    return board

has_win 

has_win() -> bool

Checks if the current player has a winning position.

Returns:

Name Type Description
bool bool

True if the current player has a winning position (4-in-a-row), False otherwise.

Unlike can_win_next(), which checks whether the current player could win on their next move, the has_win() method determines whether a winning condition already exists on the board. This method is typically used right after a move to verify whether the game has been won.

See also: Board.can_win_next.

Example 

import bitbully as bb

# Initialize a board from a move sequence.
# The string "332311" represents a position where Player 1 (yellow, X)
# is one move away from winning.
board = bb.Board("332311")

# At this stage, Player 1 has not yet won, but can win immediately
# by placing a token in either column 0 or column 4.
assert not board.has_win()
assert board.can_win_next(0)  # Check column 0
assert board.can_win_next(4)  # Check column 4
assert board.can_win_next()  # General check (any winning move)

# Simulate Player 1 playing in column 4 — this completes
# a horizontal line of four tokens and wins the game.
assert board.play(4)

# Display the updated board to visualize the winning position.
print(board)

# The board now contains a winning configuration:
# Player 1 (yellow, X) has achieved a Connect-4.
assert board.has_win()
Board from above, expected output: 
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  O  _  _  _
_  O  _  O  _  _  _
_  X  X  X  X  _  _

Referenced by:
Source code in src/bitbully/board.py 
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
def has_win(self) -> bool:
    """Checks if the current player has a winning position.

    Returns:
        bool: True if the current player has a winning position (4-in-a-row), False otherwise.

    Unlike `can_win_next()`, which checks whether the current player *could* win
    on their next move, the `has_win()` method determines whether a winning
    condition already exists on the board.
    This method is typically used right after a move to verify whether the game
    has been won.

    See also: [`Board.can_win_next`][src.bitbully.board.Board.can_win_next].

    Example:
        ```python
        import bitbully as bb

        # Initialize a board from a move sequence.
        # The string "332311" represents a position where Player 1 (yellow, X)
        # is one move away from winning.
        board = bb.Board("332311")

        # At this stage, Player 1 has not yet won, but can win immediately
        # by placing a token in either column 0 or column 4.
        assert not board.has_win()
        assert board.can_win_next(0)  # Check column 0
        assert board.can_win_next(4)  # Check column 4
        assert board.can_win_next()  # General check (any winning move)

        # Simulate Player 1 playing in column 4 — this completes
        # a horizontal line of four tokens and wins the game.
        assert board.play(4)

        # Display the updated board to visualize the winning position.
        print(board)

        # The board now contains a winning configuration:
        # Player 1 (yellow, X) has achieved a Connect-4.
        assert board.has_win()
        ```
        Board from above, expected output:
        ```text
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  O  _  _  _
        _  O  _  O  _  _  _
        _  X  X  X  X  _  _
        ```
    """
    return self._board.hasWin()

is_full 

is_full() -> bool

Checks whether the board has any empty cells left.

A Connect Four board has 42 cells in total (7 columns x 6 rows). This method returns True if all cells are occupied, i.e. when Board.moves_left returns 0.

Returns:

Name Type Description
bool bool

True if the board is completely full (no more legal moves possible), otherwise False.
Example 
import bitbully as bb

board = bb.Board()
assert not board.is_full()
assert board.moves_left() == 42
assert board.count_tokens() == 0

# Fill the board column by column.
for _ in range(6):
    assert board.play("0123456")  # one token per column, per row

# Now every cell is occupied.
assert board.is_full()
assert board.moves_left() == 0
assert board.count_tokens() == 42
Referenced by:
Source code in src/bitbully/board.py 
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
def is_full(self) -> bool:
    """Checks whether the board has any empty cells left.

    A Connect Four board has 42 cells in total (7 columns x 6 rows).
    This method returns ``True`` if **all** cells are occupied, i.e.
    when  [Board.moves_left][src.bitbully.board.Board.moves_left] returns ``0``.

    Returns:
        bool:
            ``True`` if the board is completely full
            (no more legal moves possible), otherwise ``False``.

    Example:
        ```python
        import bitbully as bb

        board = bb.Board()
        assert not board.is_full()
        assert board.moves_left() == 42
        assert board.count_tokens() == 0

        # Fill the board column by column.
        for _ in range(6):
            assert board.play("0123456")  # one token per column, per row

        # Now every cell is occupied.
        assert board.is_full()
        assert board.moves_left() == 0
        assert board.count_tokens() == 42
        ```
    """
    return self.moves_left() == 0

is_game_over 

is_game_over() -> bool

Checks whether the game has ended (win or draw).

A game of Connect Four is considered over if:

  • One of the players has a winning position (see Board.has_win), or
  • The board is completely full and no further moves can be played (see Board.is_full).

This method does not indicate who won; for that, use Board.winner.

Returns:

Name Type Description
bool bool

True if the game is over (win or draw), otherwise False.
Example

Game over by a win: 

import bitbully as bb

# Player 1 (X) wins horizontally on the bottom row.
board = bb.Board()
assert board.play("0101010")

assert board.has_win()
assert board.is_game_over()
assert board.winner() == 1

Example

Game over by a draw (full board, no winner): 

import bitbully as bb

board, _ = bb.Board.random_board(42, forbid_direct_win=False)

assert board.is_full()
assert not board.has_win()
assert board.is_game_over()
assert board.winner() is None

Source code in src/bitbully/board.py 
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
def is_game_over(self) -> bool:
    """Checks whether the game has ended (win or draw).

    A game of Connect Four is considered **over** if:

    - One of the players has a winning position
      (see [Board.has_win][src.bitbully.board.Board.has_win]), **or**
    - The board is completely full and no further moves can be played
      (see [Board.is_full][src.bitbully.board.Board.is_full]).

    This method does **not** indicate *who* won; for that, use
    [Board.winner][src.bitbully.board.Board.winner].

    Returns:
        bool:
            ``True`` if the game is over (win or draw), otherwise ``False``.

    Example:
        Game over by a win:
        ```python
        import bitbully as bb

        # Player 1 (X) wins horizontally on the bottom row.
        board = bb.Board()
        assert board.play("0101010")

        assert board.has_win()
        assert board.is_game_over()
        assert board.winner() == 1
        ```

    Example:
        Game over by a draw (full board, no winner):
        ```python
        import bitbully as bb

        board, _ = bb.Board.random_board(42, forbid_direct_win=False)

        assert board.is_full()
        assert not board.has_win()
        assert board.is_game_over()
        assert board.winner() is None
        ```
    """
    return self.has_win() or self.is_full()

is_legal_move(move: int) -> bool

Checks if a move (column) is legal in the current position.

A move is considered legal if:

  • The column index is within the valid range (0-6), and
  • The column is not full (i.e. it still has at least one empty cell).

This method does not check for tactical consequences such as leaving an immediate win to the opponent, nor does it stop being usable once a player has already won. It purely validates whether a token can be dropped into the given column according to the basic rules of Connect Four. You have to check for wins separately using Board.has_win.

Parameters:

Name Type Description Default
int

The column index (0-6) to check.

 required

Returns:

Name Type Description
bool bool

True if the move is legal, False otherwise.
Example

All moves are legal on an empty board: 

import bitbully as bb

board = bb.Board()  # Empty 7x6 board

# Every column index from 0 to 6 is a valid move.
for col in range(7):
    assert board.is_legal_move(col)

# Out-of-range indices are always illegal.
assert not board.is_legal_move(-1)
assert not board.is_legal_move(7)

Example

Detecting an illegal move in a full column: 

import bitbully as bb

# Fill the center column (index 3) with six tokens.
board = bb.Board()
assert board.play([3, 3, 3, 3, 3, 3])

# The center column is now full, so another move in column 3 is illegal.
assert not board.is_legal_move(3)

# Other columns are still available (as long as they are not full).
assert board.is_legal_move(0)
assert board.is_legal_move(6)

print(board)
Expected output: 
_  _  _  O  _  _  _
_  _  _  X  _  _  _
_  _  _  O  _  _  _
_  _  _  X  _  _  _
_  _  _  O  _  _  _
_  _  _  X  _  _  _

Example

This function only checks legality, not for situations where a player has won: 

import bitbully as bb

# Player 1 (yellow, X) wins  the game.
board = bb.Board()
assert board.play("1122334")

# Even though Player 1 has already won, moves in non-full columns are still legal.
for col in range(7):
    assert board.is_legal_move(col)

print(board)
Expected output: 
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  O  O  O  _  _  _
_  X  X  X  X  _  _

Source code in src/bitbully/board.py 
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
def is_legal_move(self, move: int) -> bool:
    """Checks if a move (column) is legal in the current position.

    A move is considered *legal* if:

    - The column index is within the valid range (0-6), **and**
    - The column is **not full** (i.e. it still has at least one empty cell).

    This method does **not** check for tactical consequences such as
    leaving an immediate win to the opponent, nor does it stop being
    usable once a player has already won. It purely validates whether a
    token can be dropped into the given column according to the basic
    rules of Connect Four. You have to check for wins separately using
    [Board.has_win][src.bitbully.board.Board.has_win].


    Args:
        move (int): The column index (0-6) to check.

    Returns:
        bool: True if the move is legal, False otherwise.

    Example:
        All moves are legal on an empty board:
        ```python
        import bitbully as bb

        board = bb.Board()  # Empty 7x6 board

        # Every column index from 0 to 6 is a valid move.
        for col in range(7):
            assert board.is_legal_move(col)

        # Out-of-range indices are always illegal.
        assert not board.is_legal_move(-1)
        assert not board.is_legal_move(7)
        ```

    Example:
        Detecting an illegal move in a full column:
        ```python
        import bitbully as bb

        # Fill the center column (index 3) with six tokens.
        board = bb.Board()
        assert board.play([3, 3, 3, 3, 3, 3])

        # The center column is now full, so another move in column 3 is illegal.
        assert not board.is_legal_move(3)

        # Other columns are still available (as long as they are not full).
        assert board.is_legal_move(0)
        assert board.is_legal_move(6)

        print(board)
        ```
        Expected output:
        ```text
        _  _  _  O  _  _  _
        _  _  _  X  _  _  _
        _  _  _  O  _  _  _
        _  _  _  X  _  _  _
        _  _  _  O  _  _  _
        _  _  _  X  _  _  _
        ```

    Example:
        This function only checks legality, not for situations where a player has won:
        ```python
        import bitbully as bb

        # Player 1 (yellow, X) wins  the game.
        board = bb.Board()
        assert board.play("1122334")

        # Even though Player 1 has already won, moves in non-full columns are still legal.
        for col in range(7):
            assert board.is_legal_move(col)

        print(board)
        ```
        Expected output:
        ```text
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  O  O  O  _  _  _
        _  X  X  X  X  _  _
        ```
    """
    return self._board.isLegalMove(move)

legal_moves 

legal_moves(non_losing: bool = False, order_moves: bool = False) -> list[int]

Returns a list of all legal moves (non-full columns) for the current board state.

Parameters:

Name Type Description Default

non_losing

bool

If True, only returns moves that do not allow the opponent to win immediately on their next turn. The list might be empty If False, all legal moves are returned.

 False

order_moves

bool

If True, the returned list is ordered to prioritize moves (potentially more promising first).

 False

Returns:

Type Description
list[int]

list[int]: A list of column indices (0-6) where a token can be legally dropped.
Example 
import bitbully as bb

board = bb.Board()
legal_moves = board.legal_moves()
assert set(legal_moves) == set(range(7))  # All columns are initially legal
assert set(legal_moves) == set(board.legal_moves(order_moves=True))
board.legal_moves(order_moves=True) == [3, 2, 4, 1, 5, 0, 6]  # Center column prioritized
Example 
import bitbully as bb

board = bb.Board()
board.play("3322314")
print(board)
assert board.legal_moves() == list(range(7))
assert board.legal_moves(non_losing=True) == [5]

Expected output: 

_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  X  _  _  _
_  _  O  O  _  _  _
_  O  X  X  X  _  _

Source code in src/bitbully/board.py 
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
def legal_moves(self, non_losing: bool = False, order_moves: bool = False) -> list[int]:
    """Returns a list of all legal moves (non-full columns) for the current board state.

    Args:
        non_losing (bool):
            If ``True``, only returns moves that do **not** allow the opponent
            to win immediately on their next turn. The list might be empty
            If ``False``, all legal moves are returned.
        order_moves (bool):
            If ``True``, the returned list is ordered to prioritize moves (potentially more promising first).

    Returns:
        list[int]: A list of column indices (0-6) where a token can be legally dropped.

    Example:
        ```python
        import bitbully as bb

        board = bb.Board()
        legal_moves = board.legal_moves()
        assert set(legal_moves) == set(range(7))  # All columns are initially legal
        assert set(legal_moves) == set(board.legal_moves(order_moves=True))
        board.legal_moves(order_moves=True) == [3, 2, 4, 1, 5, 0, 6]  # Center column prioritized
        ```

    Example:
        ```python
        import bitbully as bb

        board = bb.Board()
        board.play("3322314")
        print(board)
        assert board.legal_moves() == list(range(7))
        assert board.legal_moves(non_losing=True) == [5]
        ```
    Expected output:
        ```text
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  X  _  _  _
        _  _  O  O  _  _  _
        _  O  X  X  X  _  _
        ```
    """
    return self._board.legalMoves(nonLosing=non_losing, orderMoves=order_moves)

mirror 

mirror() -> Board

Returns a new Board instance that is the mirror image of the current board.

This method reflects the board horizontally around its vertical center column: - Column 0 <-> Column 6 - Column 1 <-> Column 5 - Column 2 <-> Column 4 - Column 3 stays in the center

The player to move is not changed - only the spatial arrangement of the tokens is mirrored. The original board remains unchanged; mirror() always returns a new Board instance.

Returns:

Name Type Description
Board Board

A new Board instance that is the mirror image of the current one.
Example

Mirroring a simple asymmetric position: 

import bitbully as bb

# Play four moves along the bottom row.
board = bb.Board()
assert board.play("0123")  # Columns: 0, 1, 2, 3

# Create a mirrored copy of the board.
mirrored = board.mirror()

print("Original:")
print(board)

print("Mirrored:")
print(mirrored)

Expected output: 

Original:

_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
X  O  X  O  _  _  _

Mirrored:

_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  O  X  O  X

Example

Mirroring a position that is already symmetric: 

import bitbully as bb

# Central symmetry: one token in each outer column and in the center.
board = bb.Board([1, 3, 5])

mirrored = board.mirror()

# The mirrored position is identical to the original.
assert board == mirrored
assert hash(board) == hash(mirrored)

print(board)
Expected output: 
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  X  _  O  _  X  _

Source code in src/bitbully/board.py 
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
def mirror(self) -> Board:
    """Returns a new Board instance that is the mirror image of the current board.

    This method reflects the board **horizontally** around its vertical center column:
    - Column 0 <-> Column 6
    - Column 1 <-> Column 5
    - Column 2 <-> Column 4
    - Column 3 stays in the center

    The player to move is not changed - only the spatial
    arrangement of the tokens is mirrored. The original board remains unchanged;
    `mirror()` always returns a **new** `Board` instance.

    Returns:
        Board: A new Board instance that is the mirror image of the current one.

    Example:
        Mirroring a simple asymmetric position:
        ```python
        import bitbully as bb

        # Play four moves along the bottom row.
        board = bb.Board()
        assert board.play("0123")  # Columns: 0, 1, 2, 3

        # Create a mirrored copy of the board.
        mirrored = board.mirror()

        print("Original:")
        print(board)

        print("Mirrored:")
        print(mirrored)
        ```

        Expected output:
        ```text
        Original:

        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        X  O  X  O  _  _  _

        Mirrored:

        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  O  X  O  X
        ```

    Example:
        Mirroring a position that is already symmetric:
        ```python
        import bitbully as bb

        # Central symmetry: one token in each outer column and in the center.
        board = bb.Board([1, 3, 5])

        mirrored = board.mirror()

        # The mirrored position is identical to the original.
        assert board == mirrored
        assert hash(board) == hash(mirrored)

        print(board)
        ```
         Expected output:
        ```text
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  X  _  O  _  X  _
        ```
    """
    new_board = Board()
    new_board._board = self._board.mirror()
    return new_board

moves_left 

moves_left() -> int

Returns the number of moves left until the board is full.

This is simply the number of empty cells remaining on the 7x6 grid. On an empty board there are 42 free cells, so:

  • At the start of the game: moves_left() == 42
  • After n valid moves: moves_left() == 42 - n
  • On a completely full board: moves_left() == 0

This method is equivalent to: 

42 - board.count_tokens()
but implemented efficiently in the underlying C++ core.

Returns:

Name Type Description
int int

The number of moves left (0-42).
Example

Moves left on an empty board: 

import bitbully as bb

board = bb.Board()  # No tokens placed yet.
assert board.moves_left() == 42
assert board.count_tokens() == 0

Example

Relation to the number of moves played: 

import bitbully as bb

# Play five moves in various columns.
moves = [3, 3, 1, 4, 6]
board = bb.Board()
assert board.play(moves)

# Five tokens have been placed, so 42 - 5 = 37 moves remain.
assert board.count_tokens() == 5
assert board.moves_left() == 37
assert board.moves_left() + board.count_tokens() == 42

Referenced by:
Source code in src/bitbully/board.py 
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
def moves_left(self) -> int:
    """Returns the number of moves left until the board is full.

    This is simply the number of *empty* cells remaining on the 7x6 grid.
    On an empty board there are 42 free cells, so:

    - At the start of the game: `moves_left() == 42`
    - After `n` valid moves: `moves_left() == 42 - n`
    - On a completely full board: `moves_left() == 0`

    This method is equivalent to:
    ```
    42 - board.count_tokens()
    ```
    but implemented efficiently in the underlying C++ core.

    Returns:
        int: The number of moves left (0-42).

    Example:
        Moves left on an empty board:
        ```python
        import bitbully as bb

        board = bb.Board()  # No tokens placed yet.
        assert board.moves_left() == 42
        assert board.count_tokens() == 0
        ```

    Example:
        Relation to the number of moves played:
        ```python
        import bitbully as bb

        # Play five moves in various columns.
        moves = [3, 3, 1, 4, 6]
        board = bb.Board()
        assert board.play(moves)

        # Five tokens have been placed, so 42 - 5 = 37 moves remain.
        assert board.count_tokens() == 5
        assert board.moves_left() == 37
        assert board.moves_left() + board.count_tokens() == 42
        ```
    """
    return self._board.movesLeft()

play 

play(move: int | Sequence[int] | str) -> bool

Plays one or more moves for the current player.

The method updates the internal board state by dropping tokens into the specified columns. Input can be: - a single integer (column index 0 to 6), - an iterable sequence of integers (e.g., [3, 1, 3] or range(7)), - or a string of digits (e.g., "33333111") representing the move order.

Parameters:

Name Type Description Default

move

int | Sequence[int] | str

The column index or sequence of column indices where tokens should be placed.

 required

Returns:

Name Type Description
bool bool

True if the move was played successfully, False if the move was illegal.
Example

Play a sequence of moves into the center column (column index 3): 

import bitbully as bb

board = bb.Board()
assert board.play([3, 3, 3])  # returns True on successful move
board

Expected output:

_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  X  _  _  _
_  _  _  O  _  _  _
_  _  _  X  _  _  _
Example

Play a sequence of moves across all columns: 

import bitbully as bb

board = bb.Board()
assert board.play(range(7))  # returns True on successful move
board
Expected output: 
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
X  O  X  O  X  O  X

Example

Play a sequence using a string: 

import bitbully as bb

board = bb.Board()
assert board.play("33333111")  # returns True on successful move
board
Expected output: 
_  _  _  _  _  _  _
_  _  _  X  _  _  _
_  _  _  O  _  _  _
_  O  _  X  _  _  _
_  X  _  O  _  _  _
_  O  _  X  _  _  _

Referenced by:
Source code in src/bitbully/board.py 
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
def play(self, move: int | Sequence[int] | str) -> bool:
    """Plays one or more moves for the current player.

    The method updates the internal board state by dropping tokens
    into the specified columns. Input can be:
    - a single integer (column index 0 to 6),
    - an iterable sequence of integers (e.g., `[3, 1, 3]` or `range(7)`),
    - or a string of digits (e.g., `"33333111"`) representing the move order.

    Args:
        move (int | Sequence[int] | str):
            The column index or sequence of column indices where tokens should be placed.

    Returns:
        bool: True if the move was played successfully, False if the move was illegal.


    Example:
        Play a sequence of moves into the center column (column index 3):
        ```python
        import bitbully as bb

        board = bb.Board()
        assert board.play([3, 3, 3])  # returns True on successful move
        board
        ```

        Expected output:

        ```
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  X  _  _  _
        _  _  _  O  _  _  _
        _  _  _  X  _  _  _
        ```

    Example:
        Play a sequence of moves across all columns:
        ```python
        import bitbully as bb

        board = bb.Board()
        assert board.play(range(7))  # returns True on successful move
        board
        ```
        Expected output:
        ```text
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        X  O  X  O  X  O  X
        ```

    Example:
        Play a sequence using a string:
        ```python
        import bitbully as bb

        board = bb.Board()
        assert board.play("33333111")  # returns True on successful move
        board
        ```
        Expected output:
        ```text
        _  _  _  _  _  _  _
        _  _  _  X  _  _  _
        _  _  _  O  _  _  _
        _  O  _  X  _  _  _
        _  X  _  O  _  _  _
        _  O  _  X  _  _  _
        ```
    """
    # Case 1: string -> pass through directly
    if isinstance(move, str):
        return self._board.play(move)

    # Case 2: int -> pass through directly
    if isinstance(move, int):
        return self._board.play(move)

    # From here on, move is a Sequence[...] (but not str or int).
    move_list: list[int] = [int(v) for v in cast(Sequence[Any], move)]
    return self._board.play(move_list)

play_on_copy 

play_on_copy(move: int) -> Board

Return a new board with the given move applied, leaving the current board unchanged.

Parameters:

Name Type Description Default

move

int

The column index (0-6) in which to play the move.

 required

Returns:

Name Type Description
Board Board

A new Board instance representing the position after the move.

Raises:

Type Description
ValueError

If the move is illegal (e.g. column is full or out of range).
Example 
import bitbully as bb

board = bb.Board("333")  # Some existing position
new_board = board.play_on_copy(4)

# The original board is unchanged.
assert board.count_tokens() == 3

# The returned board includes the new move.
assert new_board.count_tokens() == 4
assert new_board != board
Source code in src/bitbully/board.py 
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
def play_on_copy(self, move: int) -> Board:
    """Return a new board with the given move applied, leaving the current board unchanged.

    Args:
        move (int):
            The column index (0-6) in which to play the move.

    Returns:
        Board:
            A new Board instance representing the position after the move.

    Raises:
        ValueError: If the move is illegal (e.g. column is full or out of range).

    Example:
        ```python
        import bitbully as bb

        board = bb.Board("333")  # Some existing position
        new_board = board.play_on_copy(4)

        # The original board is unchanged.
        assert board.count_tokens() == 3

        # The returned board includes the new move.
        assert new_board.count_tokens() == 4
        assert new_board != board
        ```
    """
    # Delegate to C++ (this returns a BoardCore instance)
    core_new = self._board.playMoveOnCopy(move)

    if core_new is None:
        # C++ signals illegal move by returning a null board
        raise ValueError(f"Illegal move: column {move}")

    # Wrap in a new high-level Board object
    new_board = Board()
    new_board._board = core_new
    return new_board

random_board staticmethod 

random_board(n_ply: int, forbid_direct_win: bool) -> tuple[Board, list[int]]

Generates a random board state by playing a specified number of random moves.

If forbid_direct_win is True, the generated position is guaranteed not to contain an immediate winning move for the player to move.

Parameters:

Name Type Description Default

n_ply

int

Number of random moves to simulate (0-42).

 required

forbid_direct_win

bool

If True, ensures the resulting board has no immediate winning move.

 required

Returns:

Type Description
tuple[Board, list[int]]

tuple[Board, list[int]]: A pair (board, moves) where board is the generated position and moves are the exact random moves performed.

Raises:

Type Description
ValueError

If n_ply is outside the valid range [0, 42].
Example

Basic usage: 

import bitbully as bb

board, moves = bb.Board.random_board(10, forbid_direct_win=True)

print("Moves:", moves)
print("Board:")
print(board)

# The move list must match the requested ply.
assert len(moves) == 10

# No immediate winning move when forbid_direct_win=True.
assert not board.can_win_next()

Example

Using random boards in tests or simulations: 

import bitbully as bb

# Generate 50 random 10-ply positions.
for _ in range(50):
    board, moves = bb.Board.random_board(10, forbid_direct_win=True)
    assert len(moves) == 10
    assert not board.has_win()  # Game should not be over
    assert board.count_tokens() == 10  # All generated boards contain exactly 10 tokens
    assert not board.can_win_next()  # Since `forbid_direct_win=True`, no immediate threat

Example

Reconstructing the board manually from the move list: 

import bitbully as bb

b1, moves = bb.Board.random_board(8, forbid_direct_win=True)

# Recreate the board using the move sequence:
b2 = bb.Board(moves)

assert b1 == b2
assert b1.to_string() == b2.to_string()
assert b1.uid() == b2.uid()

Example

Ensure randomness by generating many distinct sequences: 

import bitbully as bb

seen = set()
for _ in range(20):
    _, moves = bb.Board.random_board(5, False)
    seen.add(tuple(moves))

# Very likely to see more than one unique sequence.
assert len(seen) > 1

Source code in src/bitbully/board.py 
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
@staticmethod
def random_board(n_ply: int, forbid_direct_win: bool) -> tuple[Board, list[int]]:
    """Generates a random board state by playing a specified number of random moves.

    If ``forbid_direct_win`` is ``True``, the generated position is guaranteed
    **not** to contain an immediate winning move for the player to move.

    Args:
        n_ply (int):
            Number of random moves to simulate (0-42).
        forbid_direct_win (bool):
            If ``True``, ensures the resulting board has **no immediate winning move**.

    Returns:
        tuple[Board, list[int]]:
            A pair ``(board, moves)`` where ``board`` is the generated position
            and ``moves`` are the exact random moves performed.

    Raises:
        ValueError: If `n_ply` is outside the valid range [0, 42].

    Example:
        Basic usage:
        ```python
        import bitbully as bb

        board, moves = bb.Board.random_board(10, forbid_direct_win=True)

        print("Moves:", moves)
        print("Board:")
        print(board)

        # The move list must match the requested ply.
        assert len(moves) == 10

        # No immediate winning move when forbid_direct_win=True.
        assert not board.can_win_next()
        ```

    Example:
        Using random boards in tests or simulations:
        ```python
        import bitbully as bb

        # Generate 50 random 10-ply positions.
        for _ in range(50):
            board, moves = bb.Board.random_board(10, forbid_direct_win=True)
            assert len(moves) == 10
            assert not board.has_win()  # Game should not be over
            assert board.count_tokens() == 10  # All generated boards contain exactly 10 tokens
            assert not board.can_win_next()  # Since `forbid_direct_win=True`, no immediate threat
        ```

    Example:
        Reconstructing the board manually from the move list:
        ```python
        import bitbully as bb

        b1, moves = bb.Board.random_board(8, forbid_direct_win=True)

        # Recreate the board using the move sequence:
        b2 = bb.Board(moves)

        assert b1 == b2
        assert b1.to_string() == b2.to_string()
        assert b1.uid() == b2.uid()
        ```

    Example:
        Ensure randomness by generating many distinct sequences:
        ```python
        import bitbully as bb

        seen = set()
        for _ in range(20):
            _, moves = bb.Board.random_board(5, False)
            seen.add(tuple(moves))

        # Very likely to see more than one unique sequence.
        assert len(seen) > 1
        ```
    """
    if not 0 <= n_ply <= 42:
        raise ValueError(f"n_ply must be between 0 and 42 (inclusive), got {n_ply}.")
    board_, moves = bitbully_core.BoardCore.randomBoard(n_ply, forbid_direct_win)
    board = Board()
    board._board = board_

    return board, moves

reset_board 

reset_board(board: Sequence[int] | Sequence[Sequence[int]] | str | None = None) -> bool

Resets the board or sets (overrides) the board to a specific state.

Parameters:

Name Type Description Default

board

Sequence[int] | Sequence[Sequence[int]] | str | None

The new board state. Accepts: - 2D array (list, tuple, numpy-array) with shape 7x6 or 6x7 - 1D sequence of ints: a move sequence of columns (e.g., [0, 0, 2, 2, 3, 3]) - String: A move sequence of columns as string (e.g., "002233...") - None: to reset to an empty board

 None

Returns:

Name Type Description
bool bool

True if the board was set successfully, False otherwise.
Example

Reset the board to an empty state: 

import bitbully as bb

# Create a temporary board position from a move string.
# The string "0123456" plays one token in each column (0-6) in sequence.
board = bb.Board("0123456")

# Reset the board to an empty state.
# Calling `reset_board()` clears all tokens and restores the starting position.
# No moves → an empty board.
assert board.reset_board()
board
Expected output: 
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _

Example

(Re-)Set the board using a move sequence string: 

import bitbully as bb

# This is just a temporary setup; it will be replaced below.
board = bb.Board("0123456")

# Set the board state directly from a move sequence.
# The list [3, 3, 3] represents three consecutive moves in the center column (index 3).
# Moves alternate automatically between Player 1 (yellow) and Player 2 (red).
#
# The `reset_board()` method clears the current position and replays the given moves
# from an empty board — effectively overriding any existing board state.
assert board.reset_board([3, 3, 3])

# Display the updated board to verify the new position.
board
Expected output: 
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  _  _  _  _
_  _  _  X  _  _  _
_  _  _  O  _  _  _
_  _  _  X  _  _  _

Example

You can also set the board using other formats, such as a 2D array or a string. See the examples in the Board docstring for details.

# Briefly demonstrate the different input formats accepted by `reset_board()`.
import bitbully as bb

# Create an empty board instance
board = bb.Board()

# Variant 1: From a list of moves (integers)
# Each number represents a column index (0-6); moves alternate between players.
assert board.reset_board([3, 3, 3])

# Variant 2: From a compact move string
# Equivalent to the list above — useful for quick testing or serialization.
assert board.reset_board("33333111")

# Variant 3: From a 2D list in row-major format (6 x 7)
# Each inner list represents a row (top to bottom).
# 0 = empty, 1 = Player 1, 2 = Player 2.
board_array = [
    [0, 0, 0, 0, 0, 0, 0],  # Row 5 (top)
    [0, 0, 0, 1, 0, 0, 0],  # Row 4
    [0, 0, 0, 2, 0, 0, 0],  # Row 3
    [0, 2, 0, 1, 0, 0, 0],  # Row 2
    [0, 1, 0, 2, 0, 0, 0],  # Row 1
    [0, 2, 0, 1, 0, 0, 0],  # Row 0 (bottom)
]
assert board.reset_board(board_array)

# Variant 4: From a 2D list in column-major format (7 x 6)
# Each inner list represents a column (left to right); this matches BitBully's internal layout.
board_array = [
    [0, 0, 0, 0, 0, 0],  # Column 0 (leftmost)
    [2, 1, 2, 1, 0, 0],  # Column 1
    [0, 0, 0, 0, 0, 0],  # Column 2
    [1, 2, 1, 2, 1, 0],  # Column 3 (center)
    [0, 0, 0, 0, 0, 0],  # Column 4
    [2, 1, 2, 0, 0, 0],  # Column 5
    [0, 0, 0, 0, 0, 0],  # Column 6 (rightmost)
]
assert board.reset_board(board_array)

# Display the final board state in text form
board

Expected output: 

_  _  _  _  _  _  _
_  _  _  X  _  _  _
_  X  _  O  _  _  _
_  O  _  X  _  O  _
_  X  _  O  _  X  _
_  O  _  X  _  O  _

Source code in src/bitbully/board.py 
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
def reset_board(self, board: Sequence[int] | Sequence[Sequence[int]] | str | None = None) -> bool:
    """Resets the board or sets (overrides) the board to a specific state.

    Args:
        board (Sequence[int] | Sequence[Sequence[int]] | str | None):
            The new board state. Accepts:
            - 2D array (list, tuple, numpy-array) with shape 7x6 or 6x7
            - 1D sequence of ints: a move sequence of columns (e.g., [0, 0, 2, 2, 3, 3])
            - String: A move sequence of columns as string (e.g., "002233...")
            - None: to reset to an empty board

    Returns:
        bool: True if the board was set successfully, False otherwise.

    Example:
        Reset the board to an empty state:
        ```python
        import bitbully as bb

        # Create a temporary board position from a move string.
        # The string "0123456" plays one token in each column (0-6) in sequence.
        board = bb.Board("0123456")

        # Reset the board to an empty state.
        # Calling `reset_board()` clears all tokens and restores the starting position.
        # No moves → an empty board.
        assert board.reset_board()
        board
        ```
        Expected output:
        ```text
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        ```

    Example:
        (Re-)Set the board using a move sequence string:
        ```python
        import bitbully as bb

        # This is just a temporary setup; it will be replaced below.
        board = bb.Board("0123456")

        # Set the board state directly from a move sequence.
        # The list [3, 3, 3] represents three consecutive moves in the center column (index 3).
        # Moves alternate automatically between Player 1 (yellow) and Player 2 (red).
        #
        # The `reset_board()` method clears the current position and replays the given moves
        # from an empty board — effectively overriding any existing board state.
        assert board.reset_board([3, 3, 3])

        # Display the updated board to verify the new position.
        board
        ```
        Expected output:
        ```text
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  _  _  _  _
        _  _  _  X  _  _  _
        _  _  _  O  _  _  _
        _  _  _  X  _  _  _
        ```

    Example:
        You can also set the board using other formats, such as a 2D array or a string.
        See the examples in the [Board][src.bitbully.board.Board] docstring for details.

        ```python
        # Briefly demonstrate the different input formats accepted by `reset_board()`.
        import bitbully as bb

        # Create an empty board instance
        board = bb.Board()

        # Variant 1: From a list of moves (integers)
        # Each number represents a column index (0-6); moves alternate between players.
        assert board.reset_board([3, 3, 3])

        # Variant 2: From a compact move string
        # Equivalent to the list above — useful for quick testing or serialization.
        assert board.reset_board("33333111")

        # Variant 3: From a 2D list in row-major format (6 x 7)
        # Each inner list represents a row (top to bottom).
        # 0 = empty, 1 = Player 1, 2 = Player 2.
        board_array = [
            [0, 0, 0, 0, 0, 0, 0],  # Row 5 (top)
            [0, 0, 0, 1, 0, 0, 0],  # Row 4
            [0, 0, 0, 2, 0, 0, 0],  # Row 3
            [0, 2, 0, 1, 0, 0, 0],  # Row 2
            [0, 1, 0, 2, 0, 0, 0],  # Row 1
            [0, 2, 0, 1, 0, 0, 0],  # Row 0 (bottom)
        ]
        assert board.reset_board(board_array)

        # Variant 4: From a 2D list in column-major format (7 x 6)
        # Each inner list represents a column (left to right); this matches BitBully's internal layout.
        board_array = [
            [0, 0, 0, 0, 0, 0],  # Column 0 (leftmost)
            [2, 1, 2, 1, 0, 0],  # Column 1
            [0, 0, 0, 0, 0, 0],  # Column 2
            [1, 2, 1, 2, 1, 0],  # Column 3 (center)
            [0, 0, 0, 0, 0, 0],  # Column 4
            [2, 1, 2, 0, 0, 0],  # Column 5
            [0, 0, 0, 0, 0, 0],  # Column 6 (rightmost)
        ]
        assert board.reset_board(board_array)

        # Display the final board state in text form
        board
        ```

        Expected output:
        ```text
        _  _  _  _  _  _  _
        _  _  _  X  _  _  _
        _  X  _  O  _  _  _
        _  O  _  X  _  O  _
        _  X  _  O  _  X  _
        _  O  _  X  _  O  _
        ```
    """
    if board is None:
        return self._board.setBoard([])
    if isinstance(board, str):
        return self._board.setBoard(board)

    # From here on, board is a Sequence[...] (but not str).
    # Distinguish 2D vs 1D by inspecting the first element.
    if len(board) > 0 and isinstance(board[0], Sequence) and not isinstance(board[0], (str, bytes)):
        # Case 2: 2D -> list[list[int]]
        # Convert inner sequences to lists of ints
        grid: list[list[int]] = [[int(v) for v in row] for row in cast(Sequence[Sequence[Any]], board)]
        return self._board.setBoard(grid)

    # Case 3: 1D -> list[int]
    moves: list[int] = [int(v) for v in cast(Sequence[Any], board)]
    return self._board.setBoard(moves)

to_array 

to_array(column_major_layout: bool = True) -> list[list[int]]

Returns the board state as a 2D array (list of lists).

This layout is convenient for printing, serialization, or converting to a NumPy array for further analysis.

Parameters:

Name Type Description Default

column_major_layout

bool

Use column-major format if set to True, otherwise the row-major-layout is used.

 True

Returns:

Type Description
list[list[int]]

list[list[int]]: A 7x6 2D list representing the board state.

Raises:

Type Description
NotImplementedError

If column_major_layout is set to False.
Example

The returned array is in column-major format with shape 7 x 6 ([column][row]):

  • There are 7 inner lists, one for each column of the board.
  • Each inner list has 6 integers, one for each row.
  • Row index 0 corresponds to the bottom row, row index 5 to the top row.
  • Convention:
  • 0 -> empty cell
  • 1 -> Player 1 token (yellow, X)
  • 2 -> Player 2 token (red, O)

import bitbully as bb
from pprint import pprint

# Create a position from a move sequence.
board = bb.Board("33333111")

# Extract the board as a 2D list (rows x columns).
arr = board.to_array()

# Reconstruct the same position from the 2D array.
board2 = bb.Board(arr)

# Both boards represent the same position.
assert board == board2
assert board.to_array() == board2.to_array()

# print ther result of `board.to_array()`:
pprint(board.to_array())
Expected output: 
[[0, 0, 0, 0, 0, 0],
[2, 1, 2, 0, 0, 0],
[0, 0, 0, 0, 0, 0],
[1, 2, 1, 2, 1, 0],
[0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0],
[0, 0, 0, 0, 0, 0]]


TODO: This is not supported yet
Source code in src/bitbully/board.py 
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
def to_array(self, column_major_layout: bool = True) -> list[list[int]]:
    """Returns the board state as a 2D array (list of lists).

    This layout is convenient for printing, serialization, or converting
    to a NumPy array for further analysis.

    Args:
        column_major_layout (bool): Use column-major format if set to `True`,
            otherwise the row-major-layout is used.

    Returns:
        list[list[int]]: A 7x6 2D list representing the board state.

    Raises:
        NotImplementedError: If `column_major_layout` is set to `False`.

    Example:
        === "Column-major Format:"

            The returned array is in **column-major** format with shape `7 x 6`
            (`[column][row]`):

            - There are 7 inner lists, one for each column of the board.
            - Each inner list has 6 integers, one for each row.
            - Row index `0` corresponds to the **bottom row**,
            row index `5` to the **top row**.
            - Convention:
            - `0` -> empty cell
            - `1` -> Player 1 token (yellow, X)
            - `2` -> Player 2 token (red, O)

            ```python
            import bitbully as bb
            from pprint import pprint

            # Create a position from a move sequence.
            board = bb.Board("33333111")

            # Extract the board as a 2D list (rows x columns).
            arr = board.to_array()

            # Reconstruct the same position from the 2D array.
            board2 = bb.Board(arr)

            # Both boards represent the same position.
            assert board == board2
            assert board.to_array() == board2.to_array()

            # print ther result of `board.to_array()`:
            pprint(board.to_array())
            ```
            Expected output:
            ```text
            [[0, 0, 0, 0, 0, 0],
            [2, 1, 2, 0, 0, 0],
            [0, 0, 0, 0, 0, 0],
            [1, 2, 1, 2, 1, 0],
            [0, 0, 0, 0, 0, 0],
            [0, 0, 0, 0, 0, 0],
            [0, 0, 0, 0, 0, 0]]
            ```

        === "Row-major Format:"

            ``` markdown
            TODO: This is not supported yet
            ```
    """
    if not column_major_layout:
        # TODO: Implement in C++
        raise NotImplementedError("Row-major Layout is yet to be implemented")

    return self._board.toArray()

to_huffman 

to_huffman() -> int

Encode the current board position into a Huffman-compressed byte sequence.

This is a high-level wrapper around bitbully_core.BoardCore.toHuffman. The returned int encodes the exact token layout and the side to move using the same format as the BitBully opening databases.

The encoding is:

  • Deterministic: the same position always yields the same byte sequence.
  • Compact: suitable for storage (of positions with little number of tokens), or lookups in the BitBully database format.

Returns:

Name Type Description
int int

A Huffman-compressed representation of the current board
int

state.

Raises:

Type Description
NotImplementedError

If the position does not contain exactly 8 or 12 tokens, as the Huffman encoding is only defined for these cases.
Example

Encode a position and verify that equivalent positions have the same Huffman code:

import bitbully as bb

# Two different move sequences leading to the same final position.
b1 = bb.Board("01234444")
b2 = bb.Board("44440123")

h1 = b1.to_huffman()
h2 = b2.to_huffman()

# Huffman encoding is purely position-based.
assert h1 == h2

print(f"Huffman code: {h1}")

Expected output: 

Huffman code: 10120112

Source code in src/bitbully/board.py 
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
def to_huffman(self) -> int:
    """Encode the current board position into a Huffman-compressed byte sequence.

    This is a high-level wrapper around
    `bitbully_core.BoardCore.toHuffman`. The returned int encodes the
    exact token layout **and** the side to move using the same format as
    the BitBully opening databases.

    The encoding is:

    - Deterministic: the same position always yields the same byte sequence.
    - Compact: suitable for storage (of positions with little number of tokens),
      or lookups in the BitBully database format.

    Returns:
        int: A Huffman-compressed representation of the current board
        state.

    Raises:
        NotImplementedError:
            If the position does not contain exactly 8 or 12 tokens, as the
              Huffman encoding is only defined for these cases.

    Example:
        Encode a position and verify that equivalent positions have the
        same Huffman code:

        ```python
        import bitbully as bb

        # Two different move sequences leading to the same final position.
        b1 = bb.Board("01234444")
        b2 = bb.Board("44440123")

        h1 = b1.to_huffman()
        h2 = b2.to_huffman()

        # Huffman encoding is purely position-based.
        assert h1 == h2

        print(f"Huffman code: {h1}")
        ```
    Expected output:
        ```text
        Huffman code: 10120112
        ```
    """
    token_count = self.count_tokens()
    if token_count != 8 and token_count != 12:
        raise NotImplementedError("to_huffman() is only implemented for positions with 8 or 12 tokens.")
    return self._board.toHuffman()

to_string 

to_string() -> str

Returns a human-readable ASCII representation of the board.

The returned string shows the current board position as a 6x7 grid, laid out exactly as it would appear when you print a Board instance:

  • 6 lines of text, one per row (top row first, bottom row last)
  • 7 entries per row, separated by two spaces
  • _ represents an empty cell
  • X represents a token from Player 1 (yellow)
  • O represents a token from Player 2 (red)

This is useful when you want to explicitly capture the board as a string (e.g., for logging, debugging, or embedding into error messages) instead of relying on print(board) or repr(board).

Returns:

Name Type Description
str str

A multi-line ASCII string representing the board state.
Example

Using to_string() on an empty board: 

import bitbully as bb

board = bb.Board("33333111")

s = board.to_string()
print(s)

Expected output: 

_  _  _  _  _  _  _
_  _  _  X  _  _  _
_  _  _  O  _  _  _
_  O  _  X  _  _  _
_  X  _  O  _  _  _
_  O  _  X  _  _  _

Referenced by:
Source code in src/bitbully/board.py 
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
def to_string(self) -> str:
    """Returns a human-readable ASCII representation of the board.

    The returned string shows the **current board position** as a 6x7 grid,
    laid out exactly as it would appear when you print a `Board` instance:

    - 6 lines of text, one per row (top row first, bottom row last)
    - 7 entries per row, separated by two spaces
    - `_` represents an empty cell
    - `X` represents a token from Player 1 (yellow)
    - `O` represents a token from Player 2 (red)

    This is useful when you want to explicitly capture the board as a string
    (e.g., for logging, debugging, or embedding into error messages) instead
    of relying on `print(board)` or `repr(board)`.

    Returns:
        str: A multi-line ASCII string representing the board state.

    Example:
        Using `to_string()` on an empty board:
        ```python
        import bitbully as bb

        board = bb.Board("33333111")

        s = board.to_string()
        print(s)
        ```

        Expected output:
        ```text
        _  _  _  _  _  _  _
        _  _  _  X  _  _  _
        _  _  _  O  _  _  _
        _  O  _  X  _  _  _
        _  X  _  O  _  _  _
        _  O  _  X  _  _  _
        ```
    """
    return self._board.toString()

uid 

uid() -> int

Returns a unique identifier for the current board state.

The UID is a deterministic integer computed from the internal bitboard representation of the position. It is stable, position-based, and uniquely tied to the exact token layout and the side to move.

Key properties:

  • Boards with the same configuration (tokens + player to move) always produce the same UID.
  • Any change to the board (e.g., after a legal move) will almost always result in a different UID.
  • Copies of a board created via the copy constructor or Board.copy() naturally share the same UID as long as their states remain identical.

Unlike __hash__(), the UID is not optimized for hash-table dispersion. For use in transposition tables, caching, or dictionary/set keys, prefer __hash__() since it provides a higher-quality hash distribution.

Returns:

Name Type Description
int int

A unique integer identifier for the board state.
Example

UID is an integer and not None: 

import bitbully as bb

board = bb.Board()
u = board.uid()

assert isinstance(u, int)
# Empty board has a well-defined, stable UID.
assert board.uid() == u

Example

UID changes when the position changes: 

import bitbully as bb

board = bb.Board()
uid_before = board.uid()

assert board.play(1)  # Make a move in column 1.

uid_after = board.uid()
assert uid_after != uid_before

Example

Copies share the same UID while they are identical: 

import bitbully as bb

board = bb.Board("0123")

# Create an independent copy of the same position.
board_copy = board.copy()

assert board is not board_copy  # Different objects
assert board == board_copy  # Same position
assert board.uid() == board_copy.uid()  # Same UID

# After modifying the copy, they diverge.
assert board_copy.play(4)
assert board != board_copy
assert board.uid() != board_copy.uid()

Example

Different move sequences leading to the same position share the same UID: 

import bitbully as bb

board_1 = bb.Board("01234444")
board_2 = bb.Board("44440123")

assert board_1 is not board_2  # Different objects
assert board_1 == board_2  # Same position
assert board_1.uid() == board_2.uid()  # Same UID

# After modifying the copy, they diverge.
assert board_1.play(4)
assert board_1 != board_2
assert board_1.uid() != board_2.uid()

Source code in src/bitbully/board.py 
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
def uid(self) -> int:
    """Returns a unique identifier for the current board state.

    The UID is a deterministic integer computed from the internal bitboard
    representation of the position. It is **stable**, **position-based**, and
    uniquely tied to the exact token layout **and** the side to move.

    Key properties:

    - Boards with the **same** configuration (tokens + player to move) always
      produce the **same** UID.
    - Any change to the board (e.g., after a legal move) will almost always
      result in a **different** UID.
    - Copies of a board created via the copy constructor or `Board.copy()`
      naturally share the same UID as long as their states remain identical.

    Unlike `__hash__()`, the UID is not optimized for hash-table dispersion.
    For use in transposition tables, caching, or dictionary/set keys,
    prefer `__hash__()` since it provides a higher-quality hash distribution.

    Returns:
        int: A unique integer identifier for the board state.

    Example:
        UID is an integer and not None:
        ```python
        import bitbully as bb

        board = bb.Board()
        u = board.uid()

        assert isinstance(u, int)
        # Empty board has a well-defined, stable UID.
        assert board.uid() == u
        ```

    Example:
        UID changes when the position changes:
        ```python
        import bitbully as bb

        board = bb.Board()
        uid_before = board.uid()

        assert board.play(1)  # Make a move in column 1.

        uid_after = board.uid()
        assert uid_after != uid_before
        ```

    Example:
        Copies share the same UID while they are identical:
        ```python
        import bitbully as bb

        board = bb.Board("0123")

        # Create an independent copy of the same position.
        board_copy = board.copy()

        assert board is not board_copy  # Different objects
        assert board == board_copy  # Same position
        assert board.uid() == board_copy.uid()  # Same UID

        # After modifying the copy, they diverge.
        assert board_copy.play(4)
        assert board != board_copy
        assert board.uid() != board_copy.uid()
        ```

    Example:
        Different move sequences leading to the same position share the same UID:
        ```python
        import bitbully as bb

        board_1 = bb.Board("01234444")
        board_2 = bb.Board("44440123")

        assert board_1 is not board_2  # Different objects
        assert board_1 == board_2  # Same position
        assert board_1.uid() == board_2.uid()  # Same UID

        # After modifying the copy, they diverge.
        assert board_1.play(4)
        assert board_1 != board_2
        assert board_1.uid() != board_2.uid()
        ```
    """
    return self._board.uid()

winner 

winner() -> int | None

Returns the winning player, if the game has been won.

This helper interprets the current board under the assumption that Board.has_win indicates the last move created a winning configuration. In that case, the winner is the previous player:

  • If it is currently Player 1's turn, then Player 2 must have just won.
  • If it is currently Player 2's turn, then Player 1 must have just won.

If there is no winner (i.e. Board.has_win is False), this method returns None.

Returns:

Type Description
int | None

int | None: The winning player, or None if there is no winner.

  • 1 → Player 1 (yellow, X)
  • 2 → Player 2 (red, O)
  • None → No winner (game still ongoing or draw)
Example

Detecting a winner: 

import bitbully as bb

# Player 1 wins with a horizontal line at the bottom.
board = bb.Board()
assert board.play("1122334")

assert board.has_win()
assert board.is_game_over()

# It is now Player 2's turn to move next...
assert board.current_player() == 2

# ...which implies Player 1 must be the winner.
assert board.winner() == 1

Example

No winner yet: 

import bitbully as bb

board = bb.Board()
assert board.play("112233")  # no connect-four yet

assert not board.has_win()
assert not board.is_game_over()
assert board.winner() is None

Referenced by:
Source code in src/bitbully/board.py 
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
def winner(self) -> int | None:
    """Returns the winning player, if the game has been won.

    This helper interprets the current board under the assumption that
    [Board.has_win][src.bitbully.board.Board.has_win] indicates **the last move** created a
    winning configuration. In that case, the winner is the *previous* player:

    - If it is currently Player 1's turn, then Player 2 must have just won.
    - If it is currently Player 2's turn, then Player 1 must have just won.

    If there is no winner (i.e. [Board.has_win][src.bitbully.board.Board.has_win] is ``False``),
    this method returns ``None``.

    Returns:
        int | None:
            The winning player, or ``None`` if there is no winner.

            - ``1`` → Player 1 (yellow, ``X``)
            - ``2`` → Player 2 (red, ``O``)
            - ``None`` → No winner (game still ongoing or draw)

    Example:
        Detecting a winner:
        ```python
        import bitbully as bb

        # Player 1 wins with a horizontal line at the bottom.
        board = bb.Board()
        assert board.play("1122334")

        assert board.has_win()
        assert board.is_game_over()

        # It is now Player 2's turn to move next...
        assert board.current_player() == 2

        # ...which implies Player 1 must be the winner.
        assert board.winner() == 1
        ```

    Example:
        No winner yet:
        ```python
        import bitbully as bb

        board = bb.Board()
        assert board.play("112233")  # no connect-four yet

        assert not board.has_win()
        assert not board.is_game_over()
        assert board.winner() is None
        ```
    """
    if not self.has_win():
        return None
    # Previous player = opposite of current_player
    return 2 if self.current_player() == 1 else 1