API

All public names are exported through elo_mmr_py.__all__, and the distribution contains py.typed plus a stub for the native module.

elo_mmr_py.rate

rate(
    contests: Sequence[Contest],
    system: RatingSystem = 'mmr',
    mu_noob: float = 1500.0,
    sig_noob: float = 350.0,
    load_checkpoint: StrPath | None = None,
    save_checkpoint: StrPath | None = None,
) -> dict[str, Player]

Rate participants and return their complete histories.

Parameters:

Name	Type	Description	Default
contests	Sequence[Contest]	Chronologically ordered competitions to process.	required
system	RatingSystem	Rating system name or an EloMmrConfig. mmr is exact and remains the default; mmr-fast is an opt-in approximation.	'mmr'
mu_noob	float	Initial mean rating for newly observed participants.	1500.0
sig_noob	float	Initial rating uncertainty for newly observed participants.	350.0
load_checkpoint	StrPath | None	Optional v2 or legacy v1 checkpoint to continue.	None
save_checkpoint	StrPath | None	Optional path atomically replaced with a v2 checkpoint.	None

Returns:

Type	Description
dict[str, Player]	A mapping from participant names to latest ratings and all event objects.

Raises:

Type	Description
ValueError	If inputs or checkpoint contents are invalid.
OSError	If a checkpoint cannot be read or written.
RuntimeError	If the underlying Rust calculation fails unexpectedly.

elo_mmr_py.rate_latest

rate_latest(
    contests: Sequence[Contest],
    system: RatingSystem = 'mmr',
    mu_noob: float = 1500.0,
    sig_noob: float = 350.0,
    load_checkpoint: StrPath | None = None,
    save_checkpoint: StrPath | None = None,
) -> dict[str, PlayerRating]

Rate participants without materializing their histories in Python.

This is the preferred API for leaderboards and services that only need each participant's current rating, uncertainty, and number of rated contests. Checkpoint semantics and validation are identical to rate.

elo_mmr_py.Rater

Rater(system: RatingSystem = 'mmr', mu_noob: float = 1500.0, sig_noob: float = 350.0)

Incrementally maintain ratings without replaying previous contests.

contests_processed property

contests_processed: int

last_time_seconds property

last_time_seconds: int | None

mu_noob property

mu_noob: float

ratings property

ratings: dict[str, PlayerRating]

Return a new latest-rating snapshot containing O(players) objects.

sig_noob property

sig_noob: float

system property

system: RatingSystemName

system_config property

system_config: EloMmrConfig | None

add

add(contest: Contest) -> None

Process one contest in place.

extend

extend(contests: Sequence[Contest]) -> None

Validate and process a chronological batch in place.

load classmethod

load(path: StrPath) -> Self

Restore an incremental rater from a canonical v2 checkpoint.

save

save(path: StrPath) -> None

Atomically save the current state as a canonical v2 checkpoint.

All operations on one Rater instance are serialized. In particular, ratings waits for an in-progress add() or extend() to finish before it builds a consistent snapshot; two simultaneous snapshot reads also run one at a time. Separate Rater instances can compute in parallel.

The complete executable example is included from its tested source file:

"""Incrementally update and restore a leaderboard."""

from __future__ import annotations

from pathlib import Path
from tempfile import TemporaryDirectory

from elo_mmr_py import Contest, Rater


def main() -> None:
    rater = Rater()
    rater.add(
        Contest(
            [('Ada', 0, 0), ('Grace', 1, 1), ('Linus', 2, 2)],
            name='Opening round',
            time_seconds=1_700_000_000,
        )
    )
    rater.extend(
        [
            Contest(
                [('Grace', 0, 0), ('Ada', 1, 1), ('Linus', 2, 2)],
                name='Final round',
                time_seconds=1_700_003_600,
            )
        ]
    )

    with TemporaryDirectory(prefix='elo-mmr-example-') as directory:
        checkpoint = Path(directory) / 'ratings.json'
        rater.save(checkpoint)
        restored = Rater.load(checkpoint)

    for player in sorted(restored.ratings.values(), key=lambda item: -item.rating):
        print(player.name, player.rating, round(player.mu, 2), player.update_time_seconds)


if __name__ == '__main__':
    main()

elo_mmr_py.Player dataclass

Player(name: str, rating: int, events: list[PlayerEvent])

A participant's latest rounded rating and complete event history.

events instance-attribute

events: list[PlayerEvent]

name instance-attribute

name: str

rating instance-attribute

rating: int

elo_mmr_py.Contest

name property

name: str

perf_ceiling property

perf_ceiling: float | None

standings property

standings: list[tuple[str, int, int]]

time_seconds property

time_seconds: int

url property

url: str | None

weight property

weight: float

__new__

__new__(
    standings: Sequence[tuple[str, int, int]],
    name: str | None = ...,
    time_seconds: int | None = ...,
    url: str | None = ...,
    *,
    weight: float = ...,
    perf_ceiling: float | None = ...,
) -> Contest

Tie and ordering rules are explained in Contest representation.

elo_mmr_py.EloMmrConfig

drift_per_day property

drift_per_day: float

noob_delay property

noob_delay: list[float]

sig_limit property

sig_limit: float

split_ties property

split_ties: bool

subsample_bucket property

subsample_bucket: float

subsample_size property

subsample_size: int | None

system property

system: Literal['mmr', 'mmr-fast', 'mmx', 'mmx-fast']

weight_limit property

weight_limit: float

__new__

__new__(
    system: Literal['mmr', 'mmr-fast', 'mmx', 'mmx-fast'] = ...,
    *,
    weight_limit: float = ...,
    noob_delay: Sequence[float] | None = ...,
    sig_limit: float = ...,
    drift_per_day: float = ...,
    split_ties: bool = ...,
    subsample_size: int | None = ...,
    subsample_bucket: float | None = ...,
) -> EloMmrConfig

Defaults and validation are defined in the canonical rating-system configuration guide.

elo_mmr_py.PlayerEvent

contest_index property

contest_index: int

perf_score property

perf_score: int

place property

place: int

rating_mu property

rating_mu: int

rating_sig property

rating_sig: int

elo_mmr_py.PlayerRating

contests_played property

contests_played: int

mu property

mu: float

name property

name: str

rating property

rating: int

rating_sig property

rating_sig: int

sig property

sig: float

update_time_seconds property

update_time_seconds: int

contest_index is global across checkpoint batches. rating, rating_mu, rating_sig, and perf_score are rounded integer presentation values. mu and sig expose the corresponding full-precision posterior values.