Metadata-Version: 2.4
Name: pychessview
Version: 0.2.0
Summary: Interactive chessboard view library with optional Qt widget.
Author-email: Diblo <noreply@diblo.dk>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Diblo/pychessview
Project-URL: Repository, https://github.com/Diblo/pychessview
Project-URL: Documentation, https://github.com/Diblo/pychessview/blob/main/README.md
Project-URL: Issues, https://github.com/Diblo/pychessview/issues
Project-URL: Changelog, https://github.com/Diblo/pychessview/blob/main/CHANGELOG.md
Keywords: chess,qt,pyside6,board,gui
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Games/Entertainment :: Board Games
Classifier: Typing :: Typed
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: PyYAML>=6.0
Requires-Dist: chess~=1.11.2
Requires-Dist: imagesize>=2.0.0
Provides-Extra: qt
Requires-Dist: PySide6>=6.7; extra == "qt"
Provides-Extra: dev
Requires-Dist: pre-commit~=4.5; extra == "dev"
Requires-Dist: pytest~=8.4; extra == "dev"
Requires-Dist: ruff>=0.14; extra == "dev"
Requires-Dist: pyright>=1.1; extra == "dev"
Requires-Dist: build~=1.4.4; extra == "dev"
Requires-Dist: twine~=6.2; extra == "dev"
Requires-Dist: argcomplete~=3.6.3; extra == "dev"
Dynamic: license-file

# Pychessview

Pychessview is a Python library for building interactive chessboard UIs
without coupling presentation logic to a specific GUI framework or chess engine.

The project is published as a single PyPI distribution:

- `pychessview`: core package providing board state, layout, rendering,
  interaction handling, themes, and the public view API
- `pychessview.qt`: optional Qt integration module enabled through the `qt` extra

## Requirements

- Python 3.11 or newer
- Core runtime dependencies installed automatically with `pychessview`
- For Qt widget support, `PySide6` is required

Install only the core package when no GUI backend is needed:

```shell
pip install pychessview
```

Install the optional Qt widget support when using PySide:

```shell
pip install "pychessview[qt]"
```

The core package defines rendering contracts, game/session orchestration,
and interaction behavior while remaining backend-agnostic. The optional Qt
module builds on this foundation with `QtRenderer`, `QtControllerAdapter`, and
`ChessboardWidget`.

This design enables reusable and extensible chessboard UIs for applications such
as chess GUIs, analysis tools, and training software, where the UI layer remains
independent from the underlying game implementation.

## Quick Start

Qt provides the simplest way to render a chessboard:

```python
from PySide6.QtWidgets import QApplication

from pychessview import StandardChessFactory
from pychessview.qt import ChessboardWidget


def main() -> int:
    app = QApplication.instance() or QApplication([])

    widget = ChessboardWidget(game_spec=StandardChessFactory.create_game_spec())
    widget.resize(640, 640)
    widget.show()

    return app.exec()
```

The core package can also be used without Qt by providing a
`pychessview.RendererProtocol` implementation and initializing `pychessview.View`
directly.

## Documentation

- [Engine Guide](https://github.com/Diblo/pychessview/blob/main/docs/engine.md): backend-agnostic engine usage
  with `View`, `GameSpec`, themes, and renderers
- [Qt Widget Guide](https://github.com/Diblo/pychessview/blob/main/docs/qt_widget.md): widget construction,
  state access, and Qt-specific behavior
- [Development Guide](https://github.com/Diblo/pychessview/blob/main/docs/development.md): workspace layout,
  architecture, tooling, and test conventions

## Example

A runnable Qt example is available at
[examples/qt_demo.py](https://github.com/Diblo/pychessview/blob/main/examples/qt_demo.py).

![Chessboard preview](docs/assets/chessboard_preview.png)

The Qt example supports these interactions:

- Use the left mouse button to select, move, and drag pieces.
- Use Shift, Ctrl, or Alt with the left mouse button to add a circle or arrow.
- Use the right mouse button to delete a circle or arrow.

## License

This project is licensed under the Apache License 2.0.

GitHub profile: [Diblo/pychessview](https://github.com/Diblo/pychessview)
