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
Metadata
Release files for bitbully-databases 0.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| bitbully_databases-0.0.2.tar.gz | 17.9 MB | With provenance | Details for bitbully_databases-0.0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| bitbully_databases-0.0.2-py3-none-any.whl | Python 3 | none | any | Details for bitbully_databases-0.0.2-py3-none-any.whl |
Total release size: 35.8 MB
Release files / bitbully_databases-0.0.2.tar.gz
| Download URL | bitbully_databases-0.0.2.tar.gz |
|---|---|
| Size | 17.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ca7a1d8d649af0afcf658fc2e0310585f8ffc0ba061ed26662fe9e01a2b957c1
|
|
BLAKE2b-256 checksum How to use checksums |
81feebb52e65e4c2c4d89429baf539c132e59f66ba2eac6d95508016aaed7f35
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2025.
Transparency logRelease files / bitbully_databases-0.0.2-py3-none-any.whl
| Download URL | bitbully_databases-0.0.2-py3-none-any.whl |
|---|---|
| Size | 17.9 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
42d4431d964dc37d58a8e776729b247ac3e2096c575f27b185ac013a45e26d74
|
|
BLAKE2b-256 checksum How to use checksums |
a9d9afba82badfc1c1d91d6c8a2a8e750d664eebbc64b0131083002d3e423788
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2025.
Transparency logSecurity for bitbully-databases 0.0.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for bitbully_databases-0.0.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2025.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.