peterjclaw / ranker

League ranking for arbitrary numbers of competitors.

League Ranker

Given a collection of entrants and their scores, sort them and return their ranked points.

The mechanism used to allocate the ranked points is a generalised form of that used for the Student Robotics league points (quote from the SR rulebook):

The team with the most game points will be awarded 8 points towards the competition league. The team with the second most will be awarded 6. The team with the third most will be awarded 4 points, and the team with the fewest game points will be awarded 2 points. Teams whose robot was not entered into the round, or who were disqualified from the round, will be awarded no points.

Tied robots will be awarded the average of the points that their combined positions would be awarded. Thus, three robots tied for first place would receive 6 points each (since this is (8+6+4)/3).

The ranker supports an arbitrary number of entrants and zones (as long as there are fewer entrants than zones) and will return points which follow the pattern described above.

The points for the winning team will be 2 × the number of zones, points for subsequent places reduce by 2 points per place. Ties are resolved as described and as a result of the points per place reducing by two, the points for any entrant will always be an integer.

It supports Python 3.7+.

Tests

Tests can be run for the current interpreter by running ./run-tests or for all supported available interpreters by running tox.

ranker's Issues

Clarify that `TGamePoints` must be comparable to itself

The current type signature allows passing game points types which don't implement useful comparisons, which isn't really the case. For example, the following code will error at runtime but passes the type checking:

import league_ranker

class Foo: pass

league_ranker.calc_positions({'a': Foo(), 'b': Foo()})

The fix is likely something like:

diff --git a/league_ranker/__init__.py b/league_ranker/__init__.py
index 426b46c..9c918b8 100644
--- a/league_ranker/__init__.py
+++ b/league_ranker/__init__.py
@@ -2,6 +2,7 @@
 
 from collections import defaultdict
 from typing import (
+    Any,
     Collection,
     Container,
     Dict,
@@ -10,15 +11,22 @@ from typing import (
     Mapping,
     NewType,
     Optional,
+    Protocol,
     Sequence,
     Set,
     Tuple,
     TypeVar,
 )
 
+
+class SupportsLessThan(Protocol):
+    def __lt__(self, __other: Any) -> bool:
+        ...
+
+
 T = TypeVar('T')
 TZone = TypeVar('TZone', bound=Hashable)
-TGamePoints = TypeVar('TGamePoints')
+TGamePoints = TypeVar('TGamePoints', bound=SupportsLessThan)
 
 RankedPosition = NewType('RankedPosition', int)
 LeaguePoints = NewType('LeaguePoints', int)

but will need to account for the supported versions of Python etc.