ctfy.sdk.admin_resources.competition_boards

  1"""``client.admin.competition_boards`` — a competition's extra boards (#1965 G).
  2
  3A board is a named ``(rule, params)`` over the competition's facts. The
  4primary is the competition's own scoring rule (set with
  5``client.admin.competitions.update``); these are the others — a published
  6standing beside it, or a ``shadow`` trial only the organisers can read.
  7"""
  8
  9from __future__ import annotations
 10
 11from typing import Any
 12
 13from ctfy.core.enums import BoardVisibility, ScoringRuleName
 14from ctfy.core.localized import LocalizedText
 15from ctfy.sdk._helpers import _raise_for_status
 16from ctfy.sdk.base import BaseHttpClient
 17from ctfy.server.models import CompetitionBoardInfo, CompetitionBoardsResponse
 18
 19
 20class AdminCompetitionBoardsResource:
 21    """Add, list, edit, publish and remove one competition's boards. For its
 22    organisers (global admins and the event's own competition admins)."""
 23
 24    def __init__(self, http: BaseHttpClient) -> None:
 25        self._http = http
 26
 27    def list(self, competition_id: str) -> CompetitionBoardsResponse:
 28        """Every board, the primary first and the shadow ones included —
 29        the organiser's read of ``GET /competitions/{id}/boards``."""
 30        resp = self._http.request("GET", f"/competitions/{competition_id}/boards")
 31        _raise_for_status(resp)
 32        return CompetitionBoardsResponse.model_validate(resp.json())
 33
 34    def create(
 35        self,
 36        competition_id: str,
 37        *,
 38        slug: str,
 39        rule: ScoringRuleName,
 40        params: dict[str, Any] | None = None,
 41        title: str | LocalizedText = "",
 42        visibility: BoardVisibility = "shadow",
 43        position: int = 0,
 44    ) -> CompetitionBoardInfo:
 45        """Add a board. It starts ``shadow`` — computed on the real facts and
 46        read by organisers alone — unless ``visibility="published"``.
 47        ``title`` is ``{locale: text}`` (a bare string is read as ``en``)."""
 48        payload: dict[str, Any] = {
 49            "slug": slug,
 50            "rule": rule,
 51            "params": params or {},
 52            "title": title,
 53            "visibility": visibility,
 54            "position": position,
 55        }
 56        resp = self._http.request(
 57            "POST", f"/admin/competitions/{competition_id}/boards", json=payload
 58        )
 59        _raise_for_status(resp)
 60        return CompetitionBoardInfo.model_validate(resp.json())
 61
 62    def update(
 63        self,
 64        competition_id: str,
 65        slug: str,
 66        *,
 67        rule: ScoringRuleName | None = None,
 68        params: dict[str, Any] | None = None,
 69        title: str | LocalizedText | None = None,
 70        visibility: BoardVisibility | None = None,
 71        position: int | None = None,
 72        scoring_change_reason: str | None = None,
 73    ) -> CompetitionBoardInfo:
 74        """Edit one board. Partial: only the arguments you pass are sent.
 75
 76        ⚠️ ``params`` **replaces** the board's params, and a new ``rule``
 77        without ``params`` starts from that rule's defaults. Once the
 78        competition is live, changing a *published* board's scoring needs
 79        ``scoring_change_reason``: the change is recorded and shown on the
 80        board (``422 scoring_change_needs_reason`` without one). A shadow
 81        board is edited freely."""
 82        payload: dict[str, Any] = {}
 83        if rule is not None:
 84            payload["rule"] = rule
 85        if params is not None:
 86            payload["params"] = params
 87        if title is not None:
 88            payload["title"] = title
 89        if visibility is not None:
 90            payload["visibility"] = visibility
 91        if position is not None:
 92            payload["position"] = position
 93        if scoring_change_reason is not None:
 94            payload["scoring_change_reason"] = scoring_change_reason
 95        resp = self._http.request(
 96            "PATCH", f"/admin/competitions/{competition_id}/boards/{slug}", json=payload
 97        )
 98        _raise_for_status(resp)
 99        return CompetitionBoardInfo.model_validate(resp.json())
100
101    def promote(self, competition_id: str, slug: str) -> CompetitionBoardInfo:
102        """Publish a shadow board: put it on the board page's tabs and every
103        surface. Allowed at any time — it adds a standing, it moves none."""
104        return self.update(competition_id, slug, visibility="published")
105
106    def delete(self, competition_id: str, slug: str) -> CompetitionBoardsResponse:
107        """Remove one extra board; returns the boards as they now stand."""
108        resp = self._http.request("DELETE", f"/admin/competitions/{competition_id}/boards/{slug}")
109        _raise_for_status(resp)
110        return CompetitionBoardsResponse.model_validate(resp.json())