| Name | elote JSON |
| Version |
1.1.0
JSON |
| download |
| home_page | None |
| Summary | Python module for rating bouts (like with Elo Rating) |
| upload_time | 2025-04-03 00:13:52 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
elo
scoring
rating
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Elote 🏆
[](https://badge.fury.io/py/elote)
[](https://pypi.org/project/elote/)
[](https://opensource.org/licenses/MIT)
**Elote** is a powerful Python library for implementing and comparing rating systems. Whether you're ranking chess players, sports teams, or prioritizing features in your product backlog, Elote provides a simple, elegant API for all your competitive ranking needs.
## Table of Contents
- [Overview](#overview)
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage Examples](#usage-examples)
- [Competitors](#competitors)
- [Arenas](#arenas)
- [Development](#development)
- [Contributing](#contributing)
- [Blog Posts](#blog-posts)
- [References](#references)
## Overview
Rating systems allow you to rank competitors based on their performance in head-to-head matchups. The most famous example is the Elo rating system used in chess, but these systems have applications far beyond sports:
- Ranking products based on A/B comparisons
- Prioritizing features through pairwise voting
- Creating recommendation systems
- Matchmaking in games and competitions
- Collaborative filtering and ranking
Elote makes implementing these systems simple and intuitive, with a clean API that handles all the mathematical complexity for you.
## Features
Currently implemented rating systems:
- **Elo** - The classic chess rating system
- **Glicko-1** - An improvement on Elo that accounts for rating reliability
- **Glicko-2** - A further improvement on Glicko that adds volatility tracking
- **TrueSkill** - Microsoft's Bayesian skill rating system for multiplayer games
- **ECF** - The English Chess Federation rating system
- **DWZ** - The Deutsche Wertungszahl (German evaluation number) system
## Installation
### For Users
```bash
pip install elote
```
### For Developers
We use a modern Python packaging approach with `pyproject.toml`. Most things you need are in the `Makefile`:
```bash
# Using Make (recommended)
make install-dev
# Or using pip
pip install -e ".[dev]"
# Or using uv
uv pip install -e ".[dev]"
```
### Requirements
- Python 3.8 or higher
## Quick Start
```python
from elote import EloCompetitor
# Create two competitors with different initial ratings
player1 = EloCompetitor(initial_rating=1500)
player2 = EloCompetitor(initial_rating=1600)
# Get win probability
print(f"Player 2 win probability: {player2.expected_score(player1):.2%}")
# Record a match result
player1.beat(player2) # Player 1 won!
# Ratings are automatically updated
print(f"Player 1 new rating: {player1.rating}")
print(f"Player 2 new rating: {player2.rating}")
```
## Usage Examples
Elote is built around two main concepts: **Competitors** and **Arenas**.
### Competitors
Competitors represent the entities you're rating. Here's how to use them:
```python
from elote import EloCompetitor
good = EloCompetitor(initial_rating=400)
better = EloCompetitor(initial_rating=500)
# Check win probabilities
print(f"Probability of better beating good: {better.expected_score(good):.2%}")
print(f"Probability of good beating better: {good.expected_score(better):.2%}")
```
Output:
```
Probability of better beating good: 64.01%
Probability of good beating better: 35.99%
```
If a match occurs, updating ratings is simple:
```python
# If good wins (an upset!)
good.beat(better)
# OR
better.lost_to(good)
# Check updated probabilities
print(f"Probability of better beating good: {better.expected_score(good):.2%}")
print(f"Probability of good beating better: {good.expected_score(better):.2%}")
```
Output:
```
Probability of better beating good: 61.25%
Probability of good beating better: 38.75%
```
### Arenas
Arenas handle large numbers of matchups automatically. The `LambdaArena` takes a comparison function and manages all competitors for you:
```python
from elote import LambdaArena
import json
import random
# Define a comparison function (returns True if a beats b)
def comparison(a, b):
return a > b
# Generate 1000 random matchups between numbers 1-10
matchups = [(random.randint(1, 10), random.randint(1, 10)) for _ in range(1000)]
# Create arena and run tournament
arena = LambdaArena(comparison)
arena.tournament(matchups)
# Display final rankings
print("Arena results:")
print(json.dumps(arena.leaderboard(), indent=4))
```
This example effectively implements a sorting algorithm using a rating system - not efficient, but demonstrates how Elote works with any comparable objects!
## Development
The project includes a Makefile that simplifies common development tasks:
```bash
# Run tests
make test
# Run tests with coverage
make test-cov
# Lint code
make lint
# Auto-fix linting issues
make lint-fix
# Format code
make format
# Build package
make build
# Build documentation
make docs
```
## Contributing
Contributions are welcome! If you'd like to help improve Elote:
1. Check the [issues](https://github.com/yourusername/elote/issues) for open tasks
2. Fork the repository
3. Create a feature branch
4. Add your changes
5. Submit a pull request
For major changes, please open an issue first to discuss what you'd like to change.
## Blog Posts
Here are some blog posts about Elote:
- [Elote: A Python Package for Rating Systems](https://mcginniscommawill.com/posts/2017-12-06-elote-python-package-rating-systems/) - Introduction to the library
- [Using Cursor for Library Maintenance](https://mcginniscommawill.com/posts/2025-03-09-cursor-for-library-maintenance/#how-cursor-helps-with-maintenance) - How Cursor helps maintain Elote
- [Year's End: Looking Back at 2017](https://mcginniscommawill.com/posts/2017-12-28-years-end-looking-back-2017/) - Reflections including Elote development
## References
1. [Glicko Rating System](http://www.glicko.net/glicko/glicko.pdf)
2. [Glicko-2 Rating System](http://www.glicko.net/glicko/glicko2.pdf)
3. [Massey Ratings](https://masseyratings.com)
4. Elo, Arpad (1978). The Rating of Chessplayers, Past and Present. Arco. ISBN 0-668-04721-6.
5. [ECF Grading System](http://www.ecfgrading.org.uk/new/help.php#elo)
6. [Deutsche Wertungszahl](https://en.wikipedia.org/wiki/Deutsche_Wertungszahl)
7. [TrueSkill: A Bayesian Skill Rating System](https://www.microsoft.com/en-us/research/publication/trueskilltm-a-bayesian-skill-rating-system/)
Raw data
{
"_id": null,
"home_page": null,
"name": "elote",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "elo, scoring, rating",
"author": null,
"author_email": "Will McGinnis <will@helton.io>",
"download_url": "https://files.pythonhosted.org/packages/7f/30/9f3d4c1d4315f8674717773594fae800b2c9a667e232b1798adec657a590/elote-1.1.0.tar.gz",
"platform": null,
"description": "# Elote \ud83c\udfc6\n\n[](https://badge.fury.io/py/elote)\n[](https://pypi.org/project/elote/)\n[](https://opensource.org/licenses/MIT)\n\n**Elote** is a powerful Python library for implementing and comparing rating systems. Whether you're ranking chess players, sports teams, or prioritizing features in your product backlog, Elote provides a simple, elegant API for all your competitive ranking needs.\n\n## Table of Contents\n- [Overview](#overview)\n- [Features](#features)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Usage Examples](#usage-examples)\n - [Competitors](#competitors)\n - [Arenas](#arenas)\n- [Development](#development)\n- [Contributing](#contributing)\n- [Blog Posts](#blog-posts)\n- [References](#references)\n\n## Overview\n\nRating systems allow you to rank competitors based on their performance in head-to-head matchups. The most famous example is the Elo rating system used in chess, but these systems have applications far beyond sports:\n\n- Ranking products based on A/B comparisons\n- Prioritizing features through pairwise voting\n- Creating recommendation systems\n- Matchmaking in games and competitions\n- Collaborative filtering and ranking\n\nElote makes implementing these systems simple and intuitive, with a clean API that handles all the mathematical complexity for you.\n\n## Features\n\nCurrently implemented rating systems:\n\n- **Elo** - The classic chess rating system\n- **Glicko-1** - An improvement on Elo that accounts for rating reliability\n- **Glicko-2** - A further improvement on Glicko that adds volatility tracking\n- **TrueSkill** - Microsoft's Bayesian skill rating system for multiplayer games\n- **ECF** - The English Chess Federation rating system\n- **DWZ** - The Deutsche Wertungszahl (German evaluation number) system\n\n## Installation\n\n### For Users\n\n```bash\npip install elote\n```\n\n### For Developers\n\nWe use a modern Python packaging approach with `pyproject.toml`. Most things you need are in the `Makefile`:\n\n```bash\n# Using Make (recommended)\nmake install-dev\n\n# Or using pip\npip install -e \".[dev]\"\n\n# Or using uv\nuv pip install -e \".[dev]\"\n```\n\n### Requirements\n\n- Python 3.8 or higher\n\n## Quick Start\n\n```python\nfrom elote import EloCompetitor\n\n# Create two competitors with different initial ratings\nplayer1 = EloCompetitor(initial_rating=1500)\nplayer2 = EloCompetitor(initial_rating=1600)\n\n# Get win probability\nprint(f\"Player 2 win probability: {player2.expected_score(player1):.2%}\")\n\n# Record a match result\nplayer1.beat(player2) # Player 1 won!\n\n# Ratings are automatically updated\nprint(f\"Player 1 new rating: {player1.rating}\")\nprint(f\"Player 2 new rating: {player2.rating}\")\n```\n\n## Usage Examples\n\nElote is built around two main concepts: **Competitors** and **Arenas**.\n\n### Competitors\n\nCompetitors represent the entities you're rating. Here's how to use them:\n\n```python\nfrom elote import EloCompetitor\n\ngood = EloCompetitor(initial_rating=400)\nbetter = EloCompetitor(initial_rating=500)\n\n# Check win probabilities\nprint(f\"Probability of better beating good: {better.expected_score(good):.2%}\")\nprint(f\"Probability of good beating better: {good.expected_score(better):.2%}\")\n```\n\nOutput:\n```\nProbability of better beating good: 64.01%\nProbability of good beating better: 35.99%\n```\n\nIf a match occurs, updating ratings is simple:\n\n```python\n# If good wins (an upset!)\ngood.beat(better)\n# OR\nbetter.lost_to(good)\n\n# Check updated probabilities\nprint(f\"Probability of better beating good: {better.expected_score(good):.2%}\")\nprint(f\"Probability of good beating better: {good.expected_score(better):.2%}\")\n```\n\nOutput:\n```\nProbability of better beating good: 61.25%\nProbability of good beating better: 38.75%\n```\n\n### Arenas\n\nArenas handle large numbers of matchups automatically. The `LambdaArena` takes a comparison function and manages all competitors for you:\n\n```python\nfrom elote import LambdaArena\nimport json\nimport random\n\n# Define a comparison function (returns True if a beats b)\ndef comparison(a, b):\n return a > b\n\n# Generate 1000 random matchups between numbers 1-10\nmatchups = [(random.randint(1, 10), random.randint(1, 10)) for _ in range(1000)]\n\n# Create arena and run tournament\narena = LambdaArena(comparison)\narena.tournament(matchups)\n\n# Display final rankings\nprint(\"Arena results:\")\nprint(json.dumps(arena.leaderboard(), indent=4))\n```\n\nThis example effectively implements a sorting algorithm using a rating system - not efficient, but demonstrates how Elote works with any comparable objects!\n\n## Development\n\nThe project includes a Makefile that simplifies common development tasks:\n\n```bash\n# Run tests\nmake test\n\n# Run tests with coverage\nmake test-cov\n\n# Lint code\nmake lint\n\n# Auto-fix linting issues\nmake lint-fix\n\n# Format code\nmake format\n\n# Build package\nmake build\n\n# Build documentation\nmake docs\n```\n\n## Contributing\n\nContributions are welcome! If you'd like to help improve Elote:\n\n1. Check the [issues](https://github.com/yourusername/elote/issues) for open tasks\n2. Fork the repository\n3. Create a feature branch\n4. Add your changes\n5. Submit a pull request\n\nFor major changes, please open an issue first to discuss what you'd like to change.\n\n## Blog Posts\n\nHere are some blog posts about Elote:\n\n- [Elote: A Python Package for Rating Systems](https://mcginniscommawill.com/posts/2017-12-06-elote-python-package-rating-systems/) - Introduction to the library\n- [Using Cursor for Library Maintenance](https://mcginniscommawill.com/posts/2025-03-09-cursor-for-library-maintenance/#how-cursor-helps-with-maintenance) - How Cursor helps maintain Elote\n- [Year's End: Looking Back at 2017](https://mcginniscommawill.com/posts/2017-12-28-years-end-looking-back-2017/) - Reflections including Elote development\n\n## References\n\n1. [Glicko Rating System](http://www.glicko.net/glicko/glicko.pdf)\n2. [Glicko-2 Rating System](http://www.glicko.net/glicko/glicko2.pdf)\n3. [Massey Ratings](https://masseyratings.com)\n4. Elo, Arpad (1978). The Rating of Chessplayers, Past and Present. Arco. ISBN 0-668-04721-6.\n5. [ECF Grading System](http://www.ecfgrading.org.uk/new/help.php#elo)\n6. [Deutsche Wertungszahl](https://en.wikipedia.org/wiki/Deutsche_Wertungszahl)\n7. [TrueSkill: A Bayesian Skill Rating System](https://www.microsoft.com/en-us/research/publication/trueskilltm-a-bayesian-skill-rating-system/)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python module for rating bouts (like with Elo Rating)",
"version": "1.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/wdm0006/elote/issues",
"Homepage": "https://github.com/wdm0006/elote"
},
"split_keywords": [
"elo",
" scoring",
" rating"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7f309f3d4c1d4315f8674717773594fae800b2c9a667e232b1798adec657a590",
"md5": "1640ef1e83d60a47efec75854d071f79",
"sha256": "74bbdeada650570a9f162ffa2db60610e3f4e3ee09ef77b4a10026ad1906b43b"
},
"downloads": -1,
"filename": "elote-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "1640ef1e83d60a47efec75854d071f79",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 78506,
"upload_time": "2025-04-03T00:13:52",
"upload_time_iso_8601": "2025-04-03T00:13:52.695968Z",
"url": "https://files.pythonhosted.org/packages/7f/30/9f3d4c1d4315f8674717773594fae800b2c9a667e232b1798adec657a590/elote-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-04-03 00:13:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wdm0006",
"github_project": "elote",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "elote"
}
