py4swiss 0.3.1

A package to pair swiss tournaments

♟️ py4swiss

py4swiss is a python package for pairing Swiss-system chess tournaments.

The code is heavily inspired by bbpPairings and also directly utitlizes the maximum weight matching algorithm implemented there.

Supports Windows, Linux (Ubuntu), and macOS.

📄 Tournament Report File

For generation of pairings, an input file containing the entire history of the tournament up until this point is required. This file needs to be a TRF(x) as defined by the javafo User Manual.

When parsing, malformed lines (with an incomplete or invalid code) will be skipped by default. Use --strict to enable stricter parsing, if desired.

Note that unlike javafo, if no initial color is provided, py4swiss will default to white1 instead of choosing randomly.

📦 Installation

You can install this package directly from PyPI using pip via

pip install py4swiss

If you prefer, you can also install the latest version from the source repository via

git clone https://github.com/Moritz72/py4swiss.git
cd py4swiss
pip install .

Pre-built binary files for each supported OS are also available in the Releases section.

⚙ Usage

To generate pairings for a given tournament, run

py4swiss -t <trf-file>

Additional arguments can be specified for more precise control.

Argument	Description	Default
-e, --engine	Pairing engine	dutch
-p, --pairings	Output file for pairings	pairings.txt
-s, --strict	Enable strict parsing mode	False

🧩 Variants

FIDE Dutch System

Pairing engine: dutch

This variant implements the (Swiss) Dutch System (until 2026) rules by FIDE. It was tested against and produces results identical to bbpPairings.

FIDE Dubov System

Pairing engine: dubov

This variant implements the (Swiss) Dubov System (from 2026) rules by FIDE. It was tested against and produces results identical to CPPDubovSystem in most cases. Note, however, that neither implementation is mature at this point in time.

FIDE Burstein System

Pairing engine: burstein

This variant implements the (Swiss) Burstein System (from 2026) rules by FIDE. Note, however, that this implementation is not mature at this point in time.

🧪 Tests

In order to run some tests, bbpPairings.exe as well as CPPDubovSystem need to be in the environment. You can download bbpPairings.exe directly from here while CPPDubovSystem needs to be built from source.

After that you can run the tests using pytest.

📜 License

This project is licensed under the MIT License. The contents of /cpp, however, were copied from bbpPairings and are thus licensed under the Apache License 2.0.