Metadata-Version: 2.4
Name: fairyfishnet
Version: 1.16.69
Summary: Distributed Fairy-Stockfish analysis for pychess.org
Keywords: chess,fairy-stockfish,fishnet,pychess,uci
Author: Bajusz Tamás
Author-email: Bajusz Tamás <gbtami@gmail.com>
License-Expression: GPL-3.0-or-later
License-File: LICENSE.txt
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Games/Entertainment :: Board Games
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Dist: beautifulsoup4==4.14.3
Requires-Dist: gdown==5.2.2
Requires-Dist: pyffish==0.0.89
Requires-Dist: requests==2.32.4 ; python_full_version < '3.9'
Requires-Dist: requests==2.32.5 ; python_full_version >= '3.9'
Requires-Python: >=3.8
Project-URL: Homepage, https://github.com/gbtami/fairyfishnet
Project-URL: Documentation, https://github.com/gbtami/fairyfishnet/blob/master/README.md
Project-URL: Issues, https://github.com/gbtami/fairyfishnet/issues
Project-URL: Repository, https://github.com/gbtami/fairyfishnet
Description-Content-Type: text/markdown

# fairyfishnet

[![PyPI version](https://badge.fury.io/py/fairyfishnet.svg)](https://pypi.org/project/fairyfishnet/)

Distributed [Fairy-Stockfish](https://github.com/ianfab/Fairy-Stockfish) analysis for [pychess.org](https://www.pychess.org/).

fairyfishnet requires Python 3.8 or newer.

## Installation

1. Request a personal fairyfishnet key on the [pychess Discord server](https://discord.gg/aPs8RKr).
2. Install [uv](https://docs.astral.sh/uv/getting-started/installation/).
3. Install the worker as an isolated command-line tool:

   ```console
   uv tool install --with pip fairyfishnet
   ```

4. Start the worker and follow the configuration prompts:

   ```console
   fairyfishnet --auto-update
   ```

To upgrade manually:

```console
uv tool upgrade fairyfishnet
```

The extra `pip` package keeps the worker's existing `--auto-update` behavior available inside the isolated uv tool environment.

### systemd

Generate a service file after configuring the worker:

```console
fairyfishnet systemd
```

The command prints a service definition that can be reviewed and installed under `/etc/systemd/system/`.

### Docker

Build the image. The Dockerfile installs the latest released `fairyfishnet` package from PyPI; it does not install the current checkout:

```console
docker build -t fairyfishnet .
docker run --rm fairyfishnet --key MY_API_KEY --auto-update
```

## Fairy-Stockfish

fairyfishnet uses the pychess-variants build of [Fairy-Stockfish](https://github.com/ianfab/Fairy-Stockfish).

A suitable precompiled engine is downloaded automatically. To use a locally built engine, run `./build-stockfish.sh` and pass its path with `--stockfish-command`.

Engine lifecycle, UCI, dynamic variant, and cache invariants are documented in [ENGINES.md](ENGINES.md).

## Development

The repository uses a `src/` package layout and keeps tests under `tests/`.

Create the locked development environment using the oldest supported Python:

```console
uv sync --locked --python 3.8
```

Run the fast tests and quality checks:

```console
uv run pytest -m "not engine"
uv run ruff check .
uv run ruff format --check .
uv run pyright
uv lock --check --python 3.8
uv build
```

The engine integration tests download or launch Fairy-Stockfish:

```console
uv run pytest -m engine
```

Apply formatting with:

```console
uv run ruff format .
```

Whenever project or development dependencies change, refresh and commit the lockfile:

```console
uv lock
```

### Repository layout

```text
src/fairyfishnet/__init__.py   package metadata only
src/fairyfishnet/cli.py        argument parsing, commands, signals, and worker orchestration
src/fairyfishnet/config.py     configuration loading and validation
src/fairyfishnet/engine.py     subprocess management and the UCI protocol
src/fairyfishnet/worker.py     job acquisition, move generation, and analysis
src/fairyfishnet/variants.py   server variants.ini download and scoped cache lifecycle
src/fairyfishnet/downloads.py  engine downloads and self-update handling
src/fairyfishnet/cpuid.py      low-level CPU capability probing
src/fairyfishnet/http_utils.py HTTP and release-version helpers
tests/                         focused unit tests and engine integration tests
scripts/                       release and maintenance helpers
doc/                           fishnet protocol documentation
```

The fast suite is intentionally split by subsystem, so a regression normally points to the module that owns the behavior. Tests marked `engine` download or launch Fairy-Stockfish and are therefore slower and require network access on a clean checkout.

## Protocol

See [doc/protocol.md](doc/protocol.md) for the worker/server protocol.

![Sequence diagram](doc/sequence-diagram.png)

## Releasing

Set `UV_PUBLISH_TOKEN`, then run:

```console
uv run python scripts/release.py
```

The release helper runs tests, Ruff, Pyright, builds distributions, verifies a clean Git tree, creates the version tag, pushes it, and publishes with uv.

## License

fairyfishnet is licensed under GPL-3.0-or-later. See [LICENSE.txt](LICENSE.txt).
