Metadata-Version: 2.4
Name: Openix
Version: 2.0.4
Summary: A simple chess openings (ECO) library for Python.
Home-page: https://github.com/0xh7/Openix-Library
Author: 0xh7
Author-email: fjdjfjd1424@gmail.com
License: MIT
Keywords: chess,ECO,openings,chess openings,ai chess,python chess,openix,game opening,board games,chess library,python library,python chess library,python chess openings
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-chess
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<p align="center">
  <img src="https://raw.githubusercontent.com/0xh7/Openix-Library/main/assets/openix.png" alt="Openix Library" width="280" />
</p>

<h1 align="center">Openix</h1>

<p align="center">
  A Python chess openings library for loading, searching, and exploring ECO opening lines.
</p>

<p align="center">
  <a href="https://pypi.org/project/Openix/">
    <img src="https://img.shields.io/pypi/v/Openix?label=PyPI&color=0f172a" alt="PyPI Version" />
  </a>
  <a href="https://pypi.org/project/Openix/">
    <img src="https://img.shields.io/pypi/pyversions/Openix?color=3f7f2f" alt="Python Versions" />
  </a>
  <a href="https://pepy.tech/projects/openix">
    <img src="https://static.pepy.tech/personalized-badge/openix?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads" alt="PyPI Downloads" />
  </a>
  <a href="https://github.com/0xh7/Openix-Library/blob/main/LICENSE">
    <img src="https://img.shields.io/badge/license-MIT-1f6feb" alt="MIT License" />
  </a>
</p>

## 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

```bash
pip install Openix
```

## Quick Start

```python
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

```python
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

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

### Search by name

```python
matches = library.search_by_name("sicilian")

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

### Find openings after a move sequence

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

### Get the most common next moves

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

### Build a board from an opening

```python
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.

```python
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:

```json
{
  "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](./CHANGELOG.md) for release notes.

## License

This project is released under the MIT License. See [LICENSE](./LICENSE).
