ctfy.sdk.resources.scoreboard

 1"""``client.scoreboard`` — global standings, per-challenge stats, snapshots."""
 2
 3from __future__ import annotations
 4
 5from typing import Any
 6
 7from ctfy.core.state.models import ScoreboardSnapshotState
 8from ctfy.sdk._helpers import PagedList, _extract_items, _raise_for_status
 9from ctfy.sdk.base import BaseHttpClient
10from ctfy.server.models import ChallengeStats, ScoreboardEntry, UserScoreboardEntry
11
12
13class ScoreboardResource:
14    """Global (admin/snapshot) scoreboard surface. Per-competition standings
15    live on :meth:`CompetitionsResource.scoreboard`."""
16
17    def __init__(self, http: BaseHttpClient) -> None:
18        self._http = http
19
20    def get(
21        self, category: str = "", offset: int = 0, limit: int = 50
22    ) -> PagedList[ScoreboardEntry]:
23        params: dict[str, Any] = {"offset": offset, "limit": limit}
24        if category:
25            params["category"] = category
26        resp = self._http.request("GET", "/scoreboard", params=params)
27        _raise_for_status(resp)
28        return _extract_items(resp.json(), ScoreboardEntry)
29
30    def challenge_stats(self, offset: int = 0, limit: int = 50) -> PagedList[ChallengeStats]:
31        resp = self._http.request(
32            "GET", "/scoreboard/challenges", params={"offset": offset, "limit": limit}
33        )
34        _raise_for_status(resp)
35        return _extract_items(resp.json(), ChallengeStats)
36
37    def history(
38        self,
39        *,
40        team_id: str = "",
41        days: int = 30,
42        offset: int = 0,
43        limit: int = 50,
44    ) -> PagedList[ScoreboardSnapshotState]:
45        """Persisted scoreboard snapshots (rank-over-time). Filter to
46        one team with ``team_id``."""
47        params: dict[str, Any] = {"days": days, "offset": offset, "limit": limit}
48        if team_id:
49            params["team_id"] = team_id
50        resp = self._http.request("GET", "/scoreboard/history", params=params)
51        _raise_for_status(resp)
52        return _extract_items(resp.json(), ScoreboardSnapshotState)
53
54    def users(self, offset: int = 0, limit: int = 50) -> PagedList[UserScoreboardEntry]:
55        """Per-user (not per-team) global standings."""
56        resp = self._http.request(
57            "GET", "/scoreboard/users", params={"offset": offset, "limit": limit}
58        )
59        _raise_for_status(resp)
60        return _extract_items(resp.json(), UserScoreboardEntry)