Metadata-Version: 2.4
Name: elochess
Version: 0.5.0
Summary: A simple python package for calculating chess ratings.
Author-email: Moritz Eckert <MoritzEckert@web.de>
License: MIT
Project-URL: Homepage, https://github.com/Moritz72/elochess
Project-URL: Repository, https://github.com/Moritz72/elochess
Keywords: chess,tournament
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Games/Entertainment :: Board Games
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: api
Requires-Dist: fastapi[standard]>=0.100.0; extra == "api"
Requires-Dist: fastapi-cli[standard]>=0.0.15; extra == "api"
Requires-Dist: uvicorn>=0.23; extra == "api"
Provides-Extra: cli
Requires-Dist: typer>=0.25.0; extra == "cli"
Provides-Extra: dev
Requires-Dist: httpx>=0.24; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Requires-Dist: pydantic>=2.0; extra == "dev"
Requires-Dist: pytest>=7.2; extra == "dev"
Requires-Dist: pytest-cov>=7.0; extra == "dev"
Requires-Dist: ruff>=0.14; extra == "dev"
Dynamic: license-file

# ♟️ elochess

[![CI](https://github.com/Moritz72/elochess/actions/workflows/ci.yml/badge.svg)](https://github.com/Moritz72/elochess/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/Moritz72/elochess/branch/main/graph/badge.svg)](https://codecov.io/gh/Moritz72/elochess)
[![Python 3.11](https://img.shields.io/badge/python-3.11+-blue)](https://img.shields.io/badge/python-3.11+-blue)
[![uv](https://img.shields.io/badge/dependency%20manager-uv-blue)](https://github.com/astral-sh/uv)
[![Ruff](https://img.shields.io/badge/linting-ruff-blue)](https://github.com/astral-sh/ruff)
[![mypy](https://img.shields.io/badge/types-mypy-blue)](https://github.com/python/mypy)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

`elochess` is a simple python package for calculating chess ratings.

## ✨ Rating Systems

* [FIDE Elo](https://en.wikipedia.org/wiki/Elo_rating_system) used by the [FIDE](https://en.wikipedia.org/wiki/FIDE)
* [Deutsche Wertungszahl](https://de.wikipedia.org/wiki/Deutsche_Wertungszahl) used by the [German Chess Federation](https://www.schachbund.de)
* [USCF Rating](https://www.uscfsales.com/blogs/chess-matches/understanding-the-uscf-chess-rating-system?srsltid=AfmBOoqF_EKwyGsBCQFddl7XJ9mgGjqz-lktlDT3AOnOnnXpmjNh0ses) used by the [US Chess Federation](https://new.uschess.org)

## 🎯 Accuracy

This project aims to replicate the exact official rating calulations.

For FIDE Elo and DWZ, the calculated ratings have been confirmed
to be accurate in a large number of real scenarios.

For USCF rating, the calculated ratings are an estimate
based on the "official" [Rating Estimator](https://www.uschess.org/index.php/Players-Ratings/Rating-Estimator-February-2023.html).
Here as well, it has been confirmed
to be accurate in a large number of real scenarios.
But keep in mind that this is a mere estimate of the real calculation
which can only be performed by knowing all results of all players.

## 📦 Installation

```bash
pip install elochess
```

For CLI support:

```bash
pip install elochess[cli]
```

For API support:

```bash
pip install elochess[api]
```

## 🚀 Usage

### 🐍 Python

```python
from elochess.elo import EloCalculator

current_rating = 1500
opponent_ratings = [1642, 1425, 1432]
score = 2.5

new_rating = EloCalculator.update_rating(
    current_rating,
    opponent_ratings,
    score
)
```

### 💻 CLI

```bash
elochess-cli update elo \
  --current 1500 \
  --opponent 1642 \
  --opponent 1425 \
  --opponent 1432 \
  --score 2.5
```

### 🌐 API

```bash
elochess-api
```

Check out the [OpenAPI Spec](https://swagger.io/specification/)
at [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).

## 📄 License

This project is licensed under the [MIT License](LICENSE).
