bitbully-databases
Opening Databases for the Board Game Connect-4.
BitBully Databases is a companion library to BitBully that provides precomputed Connect-4 opening books with millions of evaluated positions. It includes a pure-Python reference implementation (no NumPy dependency) demonstrating how to read, search, and interpret these binary databases — ideal for educational use and exploration. For high-performance inference, use the native C++/pybind11 BitBully API to access and query the databases.
Install
Install bitbully-databases via pip:
pip install bitbully-databases
Usage
import bitbully_databases as bbd
# Load the 12-ply book with distances (default)
db = bbd.BitBullyDatabases("12-ply-dist")
# Get the absolute file path of the packaged database
path = bbd.BitBullyDatabases.get_database_path("12-ply-dist")
print("Database path:", path)
# Check database metadata
print("Book size:", db.get_book_size())
print("Memory size (bytes):", db.get_book_memory_size())
print("Contains win distances:", db.has_win_distances())
# Example Connect-4 board (bottom → top)
# Player 1 (yellow, X) will eventually win
board = [
[0, 0, 0, 0, 0, 0, 0],
[0, 0, 0, 1, 0, 0, 0],
[0, 1, 0, 2, 0, 0, 0],
[0, 2, 0, 1, 0, 2, 0],
[0, 1, 0, 2, 0, 1, 0],
[0, 2, 0, 1, 0, 2, 0],
]
# Retrieve the evaluation score for the board
value = db.get_book_value(board)
print("Book value:", value)
if value is not None and db.has_win_distances():
print(f"→ Player 1 wins in {100 - abs(value)} moves.")
# Display whether the database uses distances and the type of book
print("Has win distances:", db.has_win_distances())
Further Usage Examples and API Reference
You will find further examples and the full API reference under https://markusthill.github.io/bitbully-databases/
Development (Debian-based Systems)
Install & Activate virtualenv
python3 -m venv venv
source venv/bin/activate
Install Dependencies
pip install -e .[dev,ci]
pre-commit install
You can run pre-commit before a commit with:
pre-commit run
Commitizen
Bump Version
cz bump --dry-run # first perform a dry run
cz bump
git push origin tag x.x.x
An alpha release can be created like this:
cz bump --prerelease alpha
Push commit and tag atomically
For example, pushing the commit and tag for v0.0.2-a1 would be done like this:
git push --atomic origin master v0.0.2-a1
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file bitbully_databases-0.0.2.tar.gz.
File metadata
- Download URL: bitbully_databases-0.0.2.tar.gz
- Upload date:
- Size: 17.9 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ca7a1d8d649af0afcf658fc2e0310585f8ffc0ba061ed26662fe9e01a2b957c1
|
|
| MD5 |
d68c7f4e48ece357f5b8871aac0d5a7c
|
|
| BLAKE2b-256 |
81feebb52e65e4c2c4d89429baf539c132e59f66ba2eac6d95508016aaed7f35
|
Provenance
The following attestation bundles were made for bitbully_databases-0.0.2.tar.gz:
Publisher:
wheels.yml on MarkusThill/bitbully-databases
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
bitbully_databases-0.0.2.tar.gz -
Subject digest:
ca7a1d8d649af0afcf658fc2e0310585f8ffc0ba061ed26662fe9e01a2b957c1 - Sigstore transparency entry: 702426934
- Sigstore integration time:
-
Permalink:
MarkusThill/bitbully-databases@662de45918370bf0e76a8c6bb17a16b996551111 -
Branch / Tag:
refs/tags/v0.0.2 - Owner: https://github.com/MarkusThill
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
wheels.yml@662de45918370bf0e76a8c6bb17a16b996551111 -
Trigger Event:
push
-
Statement type:
File details
Details for the file bitbully_databases-0.0.2-py3-none-any.whl.
File metadata
- Download URL: bitbully_databases-0.0.2-py3-none-any.whl
- Upload date:
- Size: 17.9 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
42d4431d964dc37d58a8e776729b247ac3e2096c575f27b185ac013a45e26d74
|
|
| MD5 |
30d6603822183f98086a52c1d750981f
|
|
| BLAKE2b-256 |
a9d9afba82badfc1c1d91d6c8a2a8e750d664eebbc64b0131083002d3e423788
|
Provenance
The following attestation bundles were made for bitbully_databases-0.0.2-py3-none-any.whl:
Publisher:
wheels.yml on MarkusThill/bitbully-databases
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
bitbully_databases-0.0.2-py3-none-any.whl -
Subject digest:
42d4431d964dc37d58a8e776729b247ac3e2096c575f27b185ac013a45e26d74 - Sigstore transparency entry: 702426935
- Sigstore integration time:
-
Permalink:
MarkusThill/bitbully-databases@662de45918370bf0e76a8c6bb17a16b996551111 -
Branch / Tag:
refs/tags/v0.0.2 - Owner: https://github.com/MarkusThill
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
wheels.yml@662de45918370bf0e76a8c6bb17a16b996551111 -
Trigger Event:
push
-
Statement type:
