icpc-api 0.1.0__py3-none-any.whl

icpc/__init__.py

@@ -0,0 +1,32 @@
+"""Unofficial client for the icpc.global API.
+
+Read a whole contest in one call::
+
+    from icpc import Icpc
+
+    with Icpc.from_store() as icpc:
+        teams = icpc.load_contest(1234)
+        print(len(teams.teams), "teams")
+"""
+
+from icpc.config import Settings
+from icpc.errors import ApiError, AuthError, IcpcError, SearchError
+from icpc.facade.client import AsyncIcpc, Icpc, Include
+from icpc.facade.domain import ContestView, Member, Team
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ApiError",
+    "AsyncIcpc",
+    "AuthError",
+    "ContestView",
+    "Icpc",
+    "IcpcError",
+    "Include",
+    "Member",
+    "SearchError",
+    "Settings",
+    "Team",
+    "__version__",
+]

icpc/api/__init__.py

@@ -0,0 +1,18 @@
+"""Low-level endpoints.
+
+Each function is pure: it builds an :class:`~icpc.transport.operation.Operation`
+and performs no I/O. Send one with ``client.send(...)``::
+
+    from icpc import Icpc
+    from icpc.api import team
+
+    with Icpc.from_store() as icpc:
+        roster = icpc.send(team.members(1234567))
+
+Not all endpoints are wrapped here. Please fill an issue for missing ones or use
+`icpc raw`.
+"""
+
+from icpc.api import common, contest, person, public, staff, team
+
+__all__ = ["common", "contest", "person", "public", "staff", "team"]

icpc/api/common.py

@@ -0,0 +1,97 @@
+"""``/common``, ``/icpcprofile`` and the ``/aspectfaces`` schema registry."""
+
+from __future__ import annotations
+
+from icpc.models.base import Row
+from icpc.models.entities import Globals, InstitutionSuggestion
+from icpc.transport.operation import Operation, Request, list_op, model_op, scalar_op
+
+__all__ = [
+    "AspectFacesField",
+    "AspectFacesSchema",
+    "globals_",
+    "institution_suggest",
+    "schema",
+    "wf_year",
+]
+
+
+def globals_() -> Operation[Globals]:
+    """Site-wide settings: the current World Finals and regionals years."""
+    return model_op(Request("GET", "/common/globals/all"), Globals)
+
+
+def wf_year() -> Operation[int]:
+    """The current World Finals year."""
+    return scalar_op(Request("GET", "/common/globals/WFYear"), int)
+
+
+def suggested_institution(institution_id: int) -> Operation[dict[str, object]]:
+    """A suggested-institution record."""
+    return model_op(
+        Request("GET", f"/common/suggestedinstitution/{institution_id}"), dict[str, object]
+    )
+
+
+class AspectFacesField(Row):
+    """One field of a server-side form definition."""
+
+    name: str | None = None
+    tag: str | None = None
+    label: str | None = None
+    label_key: str | None = None
+    placeholder: str | None = None
+    order: int | None = None
+    #: Allowed values, when the field is a choice — the closest thing to an enum
+    #: definition this API publishes.
+    options: list[object] | None = None
+    constraints: object | None = None
+    tooltip: str | None = None
+
+
+class AspectFacesSchema(Row):
+    """``GET /aspectfaces/<java.class.Name>`` — a form definition."""
+
+    name: str | None = None
+    fields: list[AspectFacesField] | None = None
+    obj: object | None = None
+
+
+def schema(java_class: str, *associations: str) -> Operation[AspectFacesSchema]:
+    """Fetch a server-side form definition.
+
+    This is the only schema the API exposes. It is the authoritative source for
+    enum option lists and required-field constraints, and therefore the right place
+    to look before constructing a write payload::
+
+        schema("global.icpc.base.model.team.businessobjects.Team", "teamInfo")
+    """
+    path = f"/aspectfaces/{java_class}"
+    if associations:
+        path += "->" + ",".join(associations)
+    return model_op(Request("GET", path), AspectFacesSchema)
+
+
+def countries() -> Operation[list[dict[str, object]]]:
+    """The country list used by the registration forms."""
+    return list_op(Request("GET", "/common/country/all"), dict[str, object])
+
+
+def institution_suggest(
+    name: str, *, page: int = 1, size: int = 10
+) -> Operation[list[InstitutionSuggestion]]:
+    """Look an institution up by name, as the UI's picker does.
+
+    The ``id`` it returns is the ``institutionUnitId`` that
+    :func:`icpc.api.team.register` expects. Take care: it is a different number
+    from both the ``instId`` and the ``instUnitId`` columns of the institution
+    search grid, which are ids in other tables entirely.
+    """
+    return list_op(
+        Request(
+            "GET",
+            "/common/institutionunit/suggest",
+            params={"name": name, "page": page, "size": size},
+        ),
+        InstitutionSuggestion,
+    )

icpc/api/contest.py

@@ -0,0 +1,253 @@
+"""``/contest`` endpoints (the authenticated ones)."""
+
+from __future__ import annotations
+
+from icpc.models.common import NamedRef
+from icpc.models.entities import (
+    Breadcrumb,
+    Contest,
+    ContestManager,
+    ContestSettings,
+    ContestStats,
+    RegistrationInfo,
+    SiteRow,
+    SiteTreeNode,
+)
+from icpc.transport.operation import (
+    Operation,
+    Request,
+    list_op,
+    model_op,
+    none_op,
+    scalar_op,
+)
+
+__all__ = [
+    "add_manager",
+    "breadcrumbs",
+    "create_site",
+    "create_subcontest",
+    "delete",
+    "delete_site",
+    "get",
+    "managers",
+    "next_contest",
+    "previous_contest",
+    "registration_info",
+    "settings",
+    "site",
+    "site_settings",
+    "site_table",
+    "site_tree",
+    "sites",
+    "stats",
+    "update",
+    "update_registration_info",
+    "update_settings",
+    "update_site_settings",
+]
+
+
+def get(contest_id: int) -> Operation[Contest]:
+    """A contest and its settings."""
+    return model_op(Request("GET", f"/contest/{contest_id}"), Contest)
+
+
+def settings(contest_id: int) -> Operation[ContestSettings]:
+    """Just the settings block."""
+    return model_op(Request("GET", f"/contest/settings/contest/{contest_id}"), ContestSettings)
+
+
+def sites(contest_id: int) -> Operation[list[NamedRef]]:
+    """The contest's sites, id and name only."""
+    return list_op(Request("GET", f"/contest/{contest_id}/sites"), NamedRef)
+
+
+def site_table(contest_id: int) -> Operation[list[SiteRow]]:
+    """Sites with capacity and registration flags — the site administration grid."""
+    return list_op(Request("GET", f"/contest/site/contest/{contest_id}/table"), SiteRow)
+
+
+def site_tree(contest_id: int) -> Operation[list[SiteTreeNode]]:
+    """The subtree of contests below this one."""
+    return list_op(Request("GET", f"/contest/site/tree/{contest_id}"), SiteTreeNode)
+
+
+def root_tree(*, eager: bool = False) -> Operation[list[SiteTreeNode]]:
+    """The top of the contest tree. ``eager`` expands every descendant in one call."""
+    path = "/contest/site/tree/root/eager" if eager else "/contest/site/tree/root"
+    return list_op(Request("GET", path), SiteTreeNode)
+
+
+def breadcrumbs(contest_id: int) -> Operation[list[Breadcrumb]]:
+    """Where this contest sits in the hierarchy, upwards."""
+    return list_op(Request("GET", f"/contest/{contest_id}/breadcrumbs"), Breadcrumb)
+
+
+def stats(contest_id: int) -> Operation[ContestStats]:
+    """Counts of sites, managers, and pending versus accepted teams."""
+    return model_op(Request("GET", f"/contest/info/contest/{contest_id}/stats"), ContestStats)
+
+
+def registration_info(contest_id: int) -> Operation[RegistrationInfo]:
+    """Registration windows and which sections registrants must fill in."""
+    return model_op(
+        Request("GET", f"/contest/registrationinfo/contest/{contest_id}"), RegistrationInfo
+    )
+
+
+def managers(contest_id: int) -> Operation[list[ContestManager]]:
+    """Who can administer this contest, and with which permissions."""
+    return list_op(Request("GET", f"/contest/access/contest/{contest_id}/managers"), ContestManager)
+
+
+def has_access(contest_id: int) -> Operation[bool]:
+    """Whether the current account may administer this contest."""
+    return scalar_op(Request("GET", f"/contest/access/contest/{contest_id}"), bool)
+
+
+def next_contest(contest_id: int) -> Operation[int]:
+    """Id of the next contest in the same series."""
+    return scalar_op(Request("GET", f"/contest/info/contest/{contest_id}/next"), int)
+
+
+def previous_contest(contest_id: int) -> Operation[int]:
+    """Id of the previous contest in the same series."""
+    return scalar_op(Request("GET", f"/contest/info/contest/{contest_id}/previous"), int)
+
+
+# ------------------------------------------------------------------ writes --
+
+
+def create_subcontest(parent_id: int, contest: dict[str, object]) -> Operation[Contest]:
+    """Create a contest beneath ``parent_id``.
+
+    There is no endpoint for creating a *top-level* contest; every contest is
+    either a child of another or the product of a rollover.
+
+    ``contest`` is a Contest object. ``name``, ``shortName`` and ``email`` are
+    required; ``abbreviation`` must match ``^[a-zA-Z-]*$`` and be 3 to 42 characters.
+    ``GET /aspectfaces/global.icpc.base.model.contest.businessobjects.Contest``
+    is the authoritative field list — ``icpc schema`` prints it.
+
+    The child inherits ``year`` and ``icpcYear`` from its parent, and is created
+    with an "Administrative Site" already attached.
+    """
+    return model_op(
+        Request("POST", f"/contest/{parent_id}/subcontest/create", json=contest, idempotent=False),
+        Contest,
+    )
+
+
+def delete(contest_id: int) -> Operation[None]:
+    """Delete a contest. Used by the UI for subcontests and camps."""
+    return none_op(Request("DELETE", f"/contest/{contest_id}", idempotent=False))
+
+
+def create_site(contest_id: int, site: dict[str, object]) -> Operation[dict[str, object]]:
+    """Add a site to a contest. ``name`` (3 to 128 characters) and ``email`` are required.
+
+    New sites start closed: ``allowRegistration`` is false, so
+    :func:`icpc.api.team.site_registrable` reports false until it is opened.
+    """
+    return Operation(
+        Request("POST", f"/contest/site/create/{contest_id}", json=site, idempotent=False),
+        lambda r: dict(r.json()) if r.content else {},
+    )
+
+
+def delete_site(site_id: int) -> Operation[None]:
+    """Remove a site."""
+    return none_op(Request("DELETE", f"/contest/site/{site_id}", idempotent=False))
+
+
+def add_manager(contest_id: int, person_id: int, *, recursive: bool = False) -> Operation[str]:
+    """Grant a person administrative access to a contest.
+
+    ``recursive`` extends the grant to every contest beneath this one. Requires
+    the ``contestGrantPermissions`` right on the contest.
+    """
+    return Operation(
+        Request(
+            "POST",
+            f"/contest/access/contest/{contest_id}/manager",
+            json={"recursive": recursive, "person": {"id": person_id}},
+            idempotent=False,
+        ),
+        lambda r: r.text,
+    )
+
+
+def update(contest_id: int, contest: dict[str, object]) -> Operation[Contest]:
+    """Overwrite a contest's own fields — name, dates, hosts, email.
+
+    A full-object replace: read with :func:`get`, change what you want, send it
+    all back. The web UI keeps ``abbreviation``, ``archivalDate`` and
+    ``lastRevalidationAt`` read-only even though the endpoint accepts them.
+    """
+    return model_op(
+        Request("POST", f"/contest/{contest_id}", json=contest, idempotent=False), Contest
+    )
+
+
+def update_settings(contest_id: int, settings: dict[str, object]) -> Operation[ContestSettings]:
+    """Overwrite the contest settings block — certification, public pages, type."""
+    return model_op(
+        Request("POST", f"/contest/settings/contest/{contest_id}", json=settings, idempotent=False),
+        ContestSettings,
+    )
+
+
+def update_registration_info(
+    contest_id: int, info: dict[str, object]
+) -> Operation[RegistrationInfo]:
+    """Overwrite the registration rules — team sizes, windows, what registrants must give.
+
+    ``allowStudentCoach`` lives here, and must be true before a team can be
+    registered with a contestant coach.
+    """
+    return model_op(
+        Request(
+            "POST",
+            f"/contest/registrationinfo/contest/{contest_id}",
+            json=info,
+            idempotent=False,
+        ),
+        RegistrationInfo,
+    )
+
+
+def site_settings(site_id: int) -> Operation[dict[str, object]]:
+    """The settings of one site, as embedded in :func:`site`."""
+    return Operation(
+        Request("GET", f"/contest/site/{site_id}"),
+        lambda r: dict(r.json().get("siteSettings") or {}),
+    )
+
+
+def site(site_id: int) -> Operation[dict[str, object]]:
+    """One site, with its settings nested under ``siteSettings``."""
+    return Operation(Request("GET", f"/contest/site/{site_id}"), lambda r: dict(r.json()))
+
+
+def update_site_settings(
+    contest_id: int, settings: dict[str, object]
+) -> Operation[dict[str, object]]:
+    """Overwrite a site's settings — capacity, and whether it is open.
+
+    Note the path is keyed by *contest*, while the settings object identifies the
+    site; read one with :func:`site_settings`.
+
+    ``allowRegistration`` and ``allowTeamChanges`` are worth knowing about: while
+    ``allowTeamChanges`` is false, adding or removing a team member answers
+    **500**, not a clean refusal.
+    """
+    return Operation(
+        Request(
+            "POST",
+            f"/contest/site/sitesettings/contest/{contest_id}",
+            json=settings,
+            idempotent=False,
+        ),
+        lambda r: dict(r.json()) if r.content else {},
+    )

icpc/api/person.py

@@ -0,0 +1,139 @@
+"""``/person`` endpoints."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from icpc.models.entities import (
+    ContactInfo,
+    ContestReference,
+    Degree,
+    Person,
+    PersonBasic,
+    PersonInfo,
+    PersonName,
+    PersonSuggestion,
+    RegistrationStatus,
+)
+from icpc.transport.operation import Operation, Request, list_op, model_op, scalar_op
+
+__all__ = [
+    "ReferenceRole",
+    "available",
+    "contact_info",
+    "degree",
+    "get",
+    "info",
+    "name",
+    "references",
+    "registration_status",
+    "suggest",
+    "whoami",
+]
+
+#: The UI's person picker waits for this many characters before querying.
+SUGGEST_MIN_LENGTH = 3
+
+
+def whoami() -> Operation[PersonBasic]:
+    """The account behind the current token. The cheapest way to check auth works."""
+    return model_op(Request("GET", "/person/info/basic"), PersonBasic)
+
+
+def get(person_id: int) -> Operation[Person]:
+    """A full person record, including the nested personal information."""
+    return model_op(Request("GET", f"/person/{person_id}"), Person)
+
+
+def info(person_id: int) -> Operation[PersonInfo]:
+    """The latest personal-information snapshot for a person."""
+    return model_op(Request("GET", f"/person/info/person/{person_id}/latest"), PersonInfo)
+
+
+def name(person_id: int) -> Operation[PersonName]:
+    """Just the names — cheaper than :func:`get` when resolving an id."""
+    return model_op(Request("GET", f"/person/name/{person_id}"), PersonName)
+
+
+def contact_info(person_id: int) -> Operation[ContactInfo]:
+    """Phone, emergency contact and shipping address."""
+    return model_op(Request("GET", f"/person/contactinfo/person/{person_id}"), ContactInfo)
+
+
+def degree(person_id: int) -> Operation[Degree]:
+    """Area of study, degree pursued, and graduation dates."""
+    return model_op(Request("GET", f"/person/degree/person/{person_id}"), Degree)
+
+
+def registration_status(person_id: int) -> Operation[RegistrationStatus]:
+    """Whether this person's registration is complete, and what the UI shows them."""
+    return model_op(
+        Request("GET", f"/person/registration/registrationStatus/{person_id}"),
+        RegistrationStatus,
+    )
+
+
+def available(username: str) -> Operation[bool]:
+    """Whether a username is free."""
+    return scalar_op(Request("GET", f"/person/available/{username}"), bool)
+
+
+def is_owner(person_id: int) -> Operation[bool]:
+    """Whether the current account owns this person record."""
+    return scalar_op(Request("GET", f"/person/isowner/{person_id}"), bool)
+
+
+def suggest(name: str, *, page: int = 1, size: int = 10) -> Operation[list[PersonSuggestion]]:
+    """Look a person up by name or email, as the UI's picker does.
+
+    This is how you turn "Nikita Sychev" or an email address into the person id
+    that team registration and staff creation need. The UI waits for three
+    characters before querying; shorter terms are accepted but match very widely.
+
+    ``page`` is 1-based, as everywhere else in this API.
+    """
+    return list_op(
+        Request("GET", "/person/suggest", params={"name": name, "page": page, "size": size}),
+        PersonSuggestion,
+    )
+
+
+class ReferenceRole(StrEnum):
+    """Roles a person can hold in a contest, as ``/person/references`` spells them."""
+
+    #: Administrative access — what the cabinet's front page lists.
+    CONTEST_MANAGER = "contestmanager"
+    SITE_MANAGER = "sitemanager"
+    STAFF_MEMBER = "staffmember"
+    #: Fills in the team and site fields as well.
+    TEAM_MEMBER = "teammember"
+    SPONSOR = "sponsor"
+    MASTER = "master"
+    SLAVE = "slave"
+
+
+def references(
+    person_id: int,
+    icpc_year: int,
+    role: ReferenceRole | str = ReferenceRole.CONTEST_MANAGER,
+    *,
+    page: int = 1,
+    size: int = 200,
+) -> Operation[list[ContestReference]]:
+    """Contests a person is attached to in ``role``, for one ICPC season.
+
+    ``icpc_year`` is the **ICPC year**, not the calendar year: NERC-2026 runs in
+    calendar 2026 but has ``icpcYear`` 2027, so it is listed under 2027. It is
+    the same number the cabinet's year picker shows.
+
+    ``contestmanager`` is the administrative access the front page lists.
+    ``teammember`` additionally fills in the team and site fields.
+    """
+    return list_op(
+        Request(
+            "GET",
+            f"/person/references/{person_id}/{icpc_year}/{role}/search",
+            params={"q": "proj:;", "page": page, "size": size},
+        ),
+        ContestReference,
+    )

icpc/api/public.py

@@ -0,0 +1,65 @@
+"""``/contest/public`` — the endpoints that need no token.
+
+Their requests set ``auth=False``, so a client built with no credentials at all can
+still reach them.
+"""
+
+from __future__ import annotations
+
+from icpc.models.entities import ContestUnder, PublicContest, RegionalRef, StandingRow
+from icpc.search.dsl import Q
+from icpc.transport.operation import Operation, Request, list_op, model_op
+
+__all__ = ["contest", "contests_under", "regionals", "standings"]
+
+
+def regionals(year: int) -> Operation[list[RegionalRef]]:
+    """The regional contests of a season."""
+    return list_op(Request("GET", f"/contest/public/regionals/{year}", auth=False), RegionalRef)
+
+
+def contests_under(contest_id: int) -> Operation[list[ContestUnder]]:
+    """Sub-contests of a contest, with registration counts."""
+    return list_op(
+        Request("GET", f"/contest/public/contests-under/{contest_id}", auth=False), ContestUnder
+    )
+
+
+def contest(abbreviation: str) -> Operation[PublicContest]:
+    """A contest by *abbreviation*, not id.
+
+    The abbreviation is sometimes year-suffixed (``NERC-2026``); a plain one that
+    404s is usually worth retrying with the season appended.
+    """
+    return model_op(Request("GET", f"/contest/public/{abbreviation}", auth=False), PublicContest)
+
+
+def standings(contest_id: int, *, page: int = 1, size: int = 1000) -> Operation[list[StandingRow]]:
+    """Published standings for a contest.
+
+    This is a search endpoint like the authenticated ones, but the empty projection
+    is what the public pages send, and it returns the default columns.
+    """
+    return list_op(
+        Request(
+            "GET",
+            f"/contest/public/search/contest/{contest_id}",
+            params={"q": Q().render(), "page": page, "size": size},
+            auth=False,
+        ),
+        StandingRow,
+    )
+
+
+def schedules(contest_id: int) -> Operation[list[dict[str, object]]]:
+    """The contest's published schedule entries."""
+    return list_op(
+        Request("GET", f"/contest/public/{contest_id}/schedules", auth=False), dict[str, object]
+    )
+
+
+def regional_results(year: int) -> Operation[list[dict[str, object]]]:
+    """The regional results tree for a season, contests nested under their parents."""
+    return list_op(
+        Request("GET", f"/contest/public/regionalresults/{year}", auth=False), dict[str, object]
+    )

icpc/api/staff.py

@@ -0,0 +1,83 @@
+"""``/contest/staffmember`` — contest staff.
+
+A *staff member* is a person attached to a site with a badge and certificate
+role. That is distinct from a *contest manager*, who has administrative
+permissions on the contest; managers live in :mod:`icpc.api.contest`.
+"""
+
+from __future__ import annotations
+
+from icpc.models._generated import StaffMemberRow
+from icpc.transport.operation import Operation, Request, model_op, none_op
+
+__all__ = ["add", "delete", "get", "update"]
+
+
+def get(staff_member_id: int) -> Operation[StaffMemberRow]:
+    """One staff member."""
+    return model_op(Request("GET", f"/contest/staffmember/{staff_member_id}"), StaffMemberRow)
+
+
+def add(
+    site_id: int,
+    person_id: int,
+    *,
+    badge_role: str,
+    certificate_role: str,
+    show_in_public_pages: bool = False,
+) -> Operation[dict[str, object]]:
+    """Attach a person to a site as staff.
+
+    Both roles are free text — they are printed on the badge and the certificate,
+    so they are whatever the contest wants to call the job. The web form refuses
+    to submit without both, and this mirrors that by requiring them.
+
+    Resolve ``person_id`` with :func:`icpc.api.person.suggest`.
+    """
+    return Operation(
+        Request(
+            "POST",
+            f"/contest/staffmember/site/{site_id}",
+            json={
+                "smId": None,
+                "personId": person_id,
+                "badgeRole": badge_role,
+                "certificateRole": certificate_role,
+                "showInPublicPages": show_in_public_pages,
+            },
+            idempotent=False,
+        ),
+        lambda r: dict(r.json()) if r.content else {},
+    )
+
+
+def update(
+    site_id: int,
+    staff_member_id: int,
+    person_id: int,
+    *,
+    badge_role: str,
+    certificate_role: str,
+    show_in_public_pages: bool = False,
+) -> Operation[dict[str, object]]:
+    """Change an existing staff member. Same body as :func:`add`, plus ``smId``."""
+    return Operation(
+        Request(
+            "PUT",
+            f"/contest/staffmember/site/{site_id}",
+            json={
+                "smId": staff_member_id,
+                "personId": person_id,
+                "badgeRole": badge_role,
+                "certificateRole": certificate_role,
+                "showInPublicPages": show_in_public_pages,
+            },
+            idempotent=False,
+        ),
+        lambda r: dict(r.json()) if r.content else {},
+    )
+
+
+def delete(staff_member_id: int) -> Operation[None]:
+    """Remove a staff member."""
+    return none_op(Request("DELETE", f"/contest/staffmember/{staff_member_id}", idempotent=False))