ctfy.sdk.resources.scoreboard

 1"""``client.scoreboard`` — global standings and per-challenge stats."""
 2
 3from __future__ import annotations
 4
 5from typing import Any
 6
 7from ctfy.sdk._helpers import PagedList, _extract_items, _raise_for_status
 8from ctfy.sdk.base import BaseHttpClient
 9from ctfy.server.models import ChallengeStats, ScoreboardEntry, UserScoreboardEntry
10
11
12class ScoreboardResource:
13    """Global (admin/snapshot) scoreboard surface. Per-competition standings
14    live on :meth:`CompetitionsResource.scoreboard`."""
15
16    def __init__(self, http: BaseHttpClient) -> None:
17        self._http = http
18
19    def get(
20        self, category: str = "", offset: int = 0, limit: int = 50, division: str = ""
21    ) -> PagedList[ScoreboardEntry]:
22        """The global standings.
23
24        ``division`` narrows to one side of a mixed board: ``"human"``
25        or ``"agent"``. Empty — the default — is everybody, which is the
26        board this method has always returned. ⚠️ Split here rather than
27        by filtering the result: the rows are paginated server-side, so a
28        client-side filter yields whichever of one page matched, still
29        carrying their *merged* ranks.
30        """
31        params: dict[str, Any] = {"offset": offset, "limit": limit}
32        if category:
33            params["category"] = category
34        if division:
35            params["division"] = division
36        resp = self._http.request("GET", "/scoreboard", params=params)
37        _raise_for_status(resp)
38        return _extract_items(resp.json(), ScoreboardEntry)
39
40    def challenge_stats(self, offset: int = 0, limit: int = 50) -> PagedList[ChallengeStats]:
41        resp = self._http.request(
42            "GET", "/scoreboard/challenges", params={"offset": offset, "limit": limit}
43        )
44        _raise_for_status(resp)
45        return _extract_items(resp.json(), ChallengeStats)
46
47    def users(self, offset: int = 0, limit: int = 50) -> PagedList[UserScoreboardEntry]:
48        """Per-user (not per-team) global standings."""
49        resp = self._http.request(
50            "GET", "/scoreboard/users", params={"offset": offset, "limit": limit}
51        )
52        _raise_for_status(resp)
53        return _extract_items(resp.json(), UserScoreboardEntry)