Openix

A Python chess openings library for loading, searching, and exploring ECO opening lines.

Why Openix

Openix gives you a ready-to-use chess openings library with bundled ECO data, simple search tools, and a clean API for Python projects that need opening lookup, move suggestions, or opening exploration.

• Load bundled opening files directly from the package.
• Search by ECO code, opening name, move prefix, or partial move sequence.
• Handle castling written as O-O or 0-0.
• Work with python-chess boards after applying an opening line.
• Use lightweight methods without extra setup beyond installation.

What's New in 2.0.4

• Added load_builtin_openings() for loading bundled ECO JSON data directly.
• Fixed parsing for move strings like 1.a3.
• Normalized castling formats such as 0-0 and 0-0-0.
• Made find_by_eco() case-insensitive.
• Improved package metadata and packaging for cleaner publishing.
• Refreshed the documentation and project presentation.

Installation

pip install Openix

Quick Start

from Openix import ChessOpeningsLibrary, __version__

print(__version__)  # 2.0.4

library = ChessOpeningsLibrary()
library.load_builtin_openings()

results = library.find_openings_after_moves(["e4", "e5", "Nf3", "Nc6", "Bb5"])

for opening in results[:3]:
    print(opening.eco_code, opening.name)
    print(opening.moves_list)

Common Use Cases

Load bundled openings

from Openix import ChessOpeningsLibrary

library = ChessOpeningsLibrary()
loaded_count = library.load_builtin_openings()

print("Loaded:", loaded_count)
print("Total:", len(library.get_all_openings()))

Search by ECO code

library.find_by_eco("C50")
library.find_by_eco("c50")  # same result

Search by name

matches = library.search_by_name("sicilian")

for opening in matches[:5]:
    print(opening.eco_code, opening.name)

Find openings after a move sequence

results = library.find_openings_after_moves(
    ["e4", "e5", "Nf3", "Nc6", "Bc4", "Bc5", "0-0"]
)

Get the most common next moves

next_moves = library.list_next_moves_after(["e4", "e5", "Nf3", "Nc6"])
print(next_moves[:5])

Build a board from an opening

from Openix import ChessOpening

opening = ChessOpening(
    "C60",
    "Ruy Lopez",
    "1. e4 e5 2. Nf3 Nc6 3. Bb5"
)

board = opening.get_board_after_opening()
print(board)

Loading Custom JSON Files

You can load your own opening files in addition to the bundled dataset.

from Openix import ChessOpeningsLibrary

library = ChessOpeningsLibrary()
library.load_from_json_file("my_openings.json")
library.load_multiple_files(["ecoA.json", "ecoB.json"])

Each opening entry should follow this structure:

{
  "eco": "C60",
  "name": "Ruy Lopez",
  "moves": "1. e4 e5 2. Nf3 Nc6 3. Bb5"
}

API Overview

ChessOpening

Represents a single opening line.

Useful attributes:

• eco_code
• name
• moves_str
• moves_list
• last_move
• moves_count

Useful methods:

• get_board_after_opening()
• from_dict(data)

ChessOpeningsLibrary

Loads and searches many openings.

Loading methods:

• load_builtin_openings(raise_on_error=False)
• load_from_json_file(file_path, raise_on_error=False)
• load_multiple_files(files_list, raise_on_error=False)

Search methods:

• find_by_eco(eco_code)
• search_by_name(name_substring)
• find_openings_starting_with(move_san)
• find_openings_after_moves(moves_list)
• list_openings_after_moves(moves_list)
• list_next_moves_after(moves_list)
• search_by_partial_moves(moves_sublist)

Utility methods:

• get_random_opening()
• get_random_opening_starting_with(move_san)
• get_random_opening_after_moves(moves_list)
• get_all_openings()
• get_statistics()

Notes

• Move strings should be valid SAN sequences.
• Invalid entries are skipped during loading unless raise_on_error=True.
• The package depends on python-chess.
• Bundled ECO data is included with the package.

Changelog

See CHANGELOG.md for release notes.

License

This project is released under the MIT License. See LICENSE.