Metadata-Version: 2.4
Name: chess-widgets
Version: 0.5.0
Summary: A PySide6 chess board widget
Author-email: Leszek <leszek.hanusz@gmail.com>
Project-URL: Repository, https://github.com/leszekhanusz/chess-widgets
Project-URL: Issues, https://github.com/leszekhanusz/chess-widgets/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PySide6<7,>=6.10.1
Requires-Dist: python-chess<2,>=1.999
Provides-Extra: dev
Requires-Dist: black==25.11.0; extra == "dev"
Requires-Dist: flake8==7.3.0; extra == "dev"
Requires-Dist: isort==7.0.0; extra == "dev"
Requires-Dist: mypy==1.18.2; extra == "dev"
Requires-Dist: pytest==9.0.1; extra == "dev"
Requires-Dist: pytest-cov==6.0.0; extra == "dev"
Requires-Dist: pytest-qt==4.5.0; extra == "dev"
Dynamic: license-file

# Python Chess Widgets

[![Tests](https://github.com/leszekhanusz/chess-widgets/actions/workflows/test.yml/badge.svg)](https://github.com/leszekhanusz/chess-widgets/actions/workflows/test.yml)
[![codecov](https://codecov.io/gh/leszekhanusz/chess-widgets/branch/main/graph/badge.svg)](https://codecov.io/gh/leszekhanusz/chess-widgets)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/chess-widgets.svg)](https://pypi.org/project/chess-widgets/)

A modern, feature-rich chess board widget for PySide6 applications, designed to mimic the visual style and user experience of Lichess. It is built on top of the powerful [python-chess](https://github.com/niklasf/python-chess) library.

![Fool's Mate Demo](examples/assets/fools_mate.gif)

## Features

- **Lichess-like Aesthetics**: Uses standard Lichess colors, SVG piece sets, and highlighting styles.
- **Interactive**: Supports both drag-and-drop and click-to-move interactions.
- **Smooth Animations**: Piece movements are animated for a better user experience.
- **Visual Indicators**:
  - Legal move highlights (dots for empty squares, rings for captures).
  - Last move highlighting.
  - Check indicator (red blurred glow behind the king).
  - Selected piece and hover highlights.
- **Responsive**: The board maintains its square aspect ratio and centers itself within the widget, scaling to fit the available space.
- **Board Flipping**: Easily toggle between White and Black perspectives.
- **Type Safe**: Fully typed codebase with `mypy` support (PEP 561 compliant).

## Installation

You can install the package from PyPI:

```bash
pip install chess-widgets
```

## Usage

Here is a simple example of how to use the `BoardWidget` in a PySide6 application:

```python
import sys
import chess
from PySide6.QtWidgets import QApplication, QMainWindow
from chess_widgets import BoardWidget

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Chess Board Example")
        self.resize(600, 600)

        # Create the widget
        self.board_widget = BoardWidget()
        self.setCentralWidget(self.board_widget)

        # Connect to the move signal
        self.board_widget.move_played.connect(self.on_move_played)

        # Optional: Set an initial board state (defaults to starting position)
        # self.board_widget.set_board(chess.Board())

    def on_move_played(self, move: chess.Move, move_info: dict):
        interactive = move_info.get("interactive", False)
        print(f"{'Interactive' if interactive else 'Programmatic'} move: {move}")
        # The widget updates its internal board automatically for user moves.
        # You can access the board state via:
        # print(self.board_widget._board.fen())

if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = MainWindow()
    window.show()
    sys.exit(app.exec())
```

A more complex example with move history navigation, board flipping, and random moves played for the opposite color can be found in the [examples/demo.py](examples/demo.py) file.

![Demo](examples/assets/demo.png)


### API Overview

- **`set_board(board: chess.Board)`**: Sets the board state to display.
- **`set_flipped(flipped: bool)`**: Sets the board orientation (`True` for Black at bottom, `False` for White at bottom).
- **`play_move(move: chess.Move, animate: bool = True, interactive: bool = False)`**: Programmatically make a move on the board, optionally with animation.
- **`undo_move(move: chess.Move, animate: bool = True)`**: Programmatically unmake the last move on the board, optionally with animation.
- `move_played(chess.Move, dict)`: Emitted when a move is played. The dictionary contains move information (e.g., `{'interactive': True}`).
- `move_undone(chess.Move)`: Emitted when a move is undone.

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to set up your development environment and submit changes.

## License

[MIT License](LICENSE)
