icpc-api 0.1.0__py3-none-any.whl

icpc/models/enums.py

@@ -0,0 +1,192 @@
+"""Wire enumerations.
+
+Server returns these lists from the ``/aspectfaces`` form registry. Model fields
+are typed ``Enum | str`` so that unrecognised values arrive as strings.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+__all__ = [
+    "Consent",
+    "ContestType",
+    "EligibilityStatus",
+    "ExportType",
+    "InstitutionUnitType",
+    "MemberRole",
+    "ParticipantRole",
+    "PublicPagesVisibility",
+    "Sex",
+    "ShirtSize",
+    "TeamStatus",
+    "Title",
+    "coach_roles",
+    "contestant_roles",
+]
+
+
+class TeamStatus(StrEnum):
+    """Team registration status. Complete, from ``…team.businessobjects.Team``.
+
+    The frontend labels the third one "Rejected"; the wire value is ``CANCELED``.
+    """
+
+    PENDING = "PENDING"
+    ACCEPTED = "ACCEPTED"
+    CANCELED = "CANCELED"
+
+
+class MemberRole(StrEnum):
+    """A person's role on a team, from ``…team.businessobjects.TeamMember``."""
+
+    COACH = "COACH"
+    COCOACH = "COCOACH"
+    #: A contestant who also coaches: counted as *both* a contestant and a coach.
+    CONTESTANT_COACH = "CONTESTANT_COACH"
+    CONTESTANT = "CONTESTANT"
+    ATTENDEE = "ATTENDEE"
+    RESERVE = "RESERVE"
+    STAFF = "STAFF"
+    #: Not in the server's current option list, but older contests may still
+    #: carry it. Treated like ``CONTESTANT_COACH``: both a contestant and a coach.
+    STUDENT_COACH = "STUDENT_COACH"
+
+
+class ParticipantRole(StrEnum):
+    """A person's role at a contest, independent of any team."""
+
+    CONTESTANT = "CONTESTANT"
+    COACH = "COACH"
+    COCOACH = "COCOACH"
+    RESERVE = "RESERVE"
+    ATTENDEE = "ATTENDEE"
+    STAFF = "STAFF"
+
+
+class Consent(StrEnum):
+    """A registration consent answer.
+
+    Several columns read like booleans — ``includeEmail``,
+    ``employmentOpportunities``, ``informOtherContests``, ``inform``, ``icpcRules``,
+    ``mediaUse`` — but the wire carries words, so ``bool`` simply fails to parse.
+    Complete, from ``…person.businessobjects.PersonInfoAbstract``.
+    """
+
+    AGREE = "AGREE"
+    DISAGREE = "DISAGREE"
+
+
+class Sex(StrEnum):
+    """Complete, from ``…person.businessobjects.PersonInfoAbstract``."""
+
+    FEMALE = "FEMALE"
+    MALE = "MALE"
+
+
+class EligibilityStatus(StrEnum):
+    """Eligibility verdict on a team.
+
+    Complete, from ``…team.businessobjects.Eligibility``. A full-object team write
+    recomputes this and drops any ``VERIFIED_*`` value.
+    """
+
+    NOT_RESOLVED = "NOT_RESOLVED"
+    NO_ISSUES_FOUND = "NO_ISSUES_FOUND"
+    PREDICTED_INELIGIBLE = "PREDICTED_INELIGIBLE"
+    VERIFIED_ELIGIBLE = "VERIFIED_ELIGIBLE"
+    VERIFIED_INELIGIBLE = "VERIFIED_INELIGIBLE"
+    ELIGIBILITY_CHECK_NOT_REQUIRED = "ELIGIBILITY_CHECK_NOT_REQUIRED"
+    VALIDATED_BY_LOWER_CONTEST = "VALIDATED_BY_LOWER_CONTEST"
+
+
+class ContestType(StrEnum):
+    """Complete, from ``…contest.businessobjects.ContestSettings``."""
+
+    WORLD_FINALS = "WORLD_FINALS"
+    REGIONALS = "REGIONALS"
+    QUALIFIER = "QUALIFIER"
+    PRACTICE = "PRACTICE"
+    CAMP = "CAMP"
+
+
+class PublicPagesVisibility(StrEnum):
+    """Whether a contest's public pages list people. Not a boolean, despite the name.
+
+    Complete, from ``…contest.businessobjects.ContestSettings``.
+    """
+
+    WITH_PEOPLE = "WITH_PEOPLE"
+    WITHOUT_PEOPLE = "WITHOUT_PEOPLE"
+
+
+class Title(StrEnum):
+    """Complete, from ``…person.businessobjects.PersonInfoAbstract``."""
+
+    DR = "DR"
+    DRS = "DRS"
+    IR = "IR"
+    MISS = "MISS"
+    MR = "MR"
+    MRS = "MRS"
+    MS = "MS"
+    PROFESSOR = "PROFESSOR"
+    NONE = "NONE"
+
+
+class InstitutionUnitType(StrEnum):
+    """What kind of institution a unit is.
+
+    Observed values only: the ``InstitutionUnit`` schema endpoint answers 500.
+    """
+
+    UNIVERSITY_GRADUATE = "UNIVERSITY_GRADUATE"
+    UNIVERSITY_NO_GRADUATE = "UNIVERSITY_NO_GRADUATE"
+    HIGH_SCHOOL = "HIGH_SCHOOL"
+
+
+class ShirtSize(StrEnum):
+    """Complete, from ``…person.businessobjects.PersonInfoAbstract``."""
+
+    XS = "XS"
+    S = "S"
+    M = "M"
+    L = "L"
+    XL = "XL"
+    XXL = "XXL"
+    XXXL = "XXXL"
+    XXXXL = "XXXXL"
+    XXXXXL = "XXXXXL"
+
+
+class ExportType(StrEnum):
+    """Formats accepted by the ``/export`` sibling of a search endpoint."""
+
+    CSV = "CSV"
+    TSV = "TSV"
+    TAB = "TAB"
+    TXT = "TXT"
+    EXCEL = "EXCEL"
+
+
+def contestant_roles() -> frozenset[str]:
+    """Roles that count as competing."""
+    return frozenset(
+        {
+            MemberRole.CONTESTANT,
+            MemberRole.STUDENT_COACH,
+            MemberRole.CONTESTANT_COACH,
+        }
+    )
+
+
+def coach_roles() -> frozenset[str]:
+    """Roles that count as coaching."""
+    return frozenset(
+        {
+            MemberRole.COACH,
+            MemberRole.COCOACH,
+            MemberRole.STUDENT_COACH,
+            MemberRole.CONTESTANT_COACH,
+        }
+    )

icpc/models/mixins.py

@@ -0,0 +1,44 @@
+"""Behaviour attached to generated rows that carry JSON-in-a-string columns.
+
+The annotations are under ``TYPE_CHECKING`` on purpose: pydantic collects fields
+from every base class's annotations, and re-declaring them here would fight with the
+generated ones. At runtime these are plain attribute reads on the model.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from icpc.models.blobs import TeamMemberBlob, parse_extra_fields, parse_members
+
+__all__ = ["HasExtraFields", "HasTeamMembers"]
+
+
+class HasTeamMembers:
+    """A row whose ``teamMembers`` column holds the roster as a JSON string."""
+
+    if TYPE_CHECKING:
+        team_members: str | None
+
+    @property
+    def member_blobs(self) -> list[TeamMemberBlob]:
+        """The roster embedded in this row. Useful if ``teammember`` was not
+        fetched.
+        """
+        return parse_members(self.team_members)
+
+
+class HasExtraFields:
+    """A row whose ``extraField`` column holds custom-question answers."""
+
+    if TYPE_CHECKING:
+        extra_field: str | None
+
+    @property
+    def extras(self) -> dict[str, str]:
+        """Answers to the contest's custom registration questions.
+
+        Keys are the contest's own question labels, so they differ between
+        contests and are frequently not in English.
+        """
+        return parse_extra_fields(self.extra_field)

icpc/search/__init__.py

@@ -0,0 +1,99 @@
+"""The ``q=`` search DSL, typed columns, and the generated endpoint catalogue."""
+
+from icpc.search import _generated as endpoints
+from icpc.search._generated import (
+    CertificateFields,
+    ContestParticipantFields,
+    InstitutionFields,
+    PromoteFields,
+    StaffFields,
+    StaffFundingFields,
+    StaffMemberFields,
+    StaffTshirtFields,
+    StandingsFields,
+    TeamFields,
+    TeamMemberFields,
+    TeamSummaryFields,
+    Top20Fields,
+    TransportationMissingFields,
+    TshirtFields,
+    contest_institutions,
+    contest_missing_transportation,
+    contest_participants,
+    contest_promote_candidates,
+    contest_public_staff_members,
+    contest_staff,
+    contest_staff_certificates,
+    contest_staff_funding,
+    contest_staff_members,
+    contest_staff_tshirts,
+    contest_standings,
+    contest_team_certificates,
+    contest_team_members,
+    contest_team_summaries,
+    contest_teams,
+    contest_top20,
+    site_coach_tshirts,
+    site_cocoach_tshirts,
+    site_contestant_tshirts,
+    site_home_teams,
+    site_institutions,
+    site_participants,
+    site_team_certificates,
+    site_team_members,
+    site_teams,
+)
+from icpc.search.dsl import Direction, Filter, FilterMode, Q, SortKey
+from icpc.search.endpoint import SearchEndpoint
+from icpc.search.fields import Field
+
+__all__ = [
+    "CertificateFields",
+    "ContestParticipantFields",
+    "Direction",
+    "Field",
+    "Filter",
+    "FilterMode",
+    "InstitutionFields",
+    "PromoteFields",
+    "Q",
+    "SearchEndpoint",
+    "SortKey",
+    "StaffFields",
+    "StaffFundingFields",
+    "StaffMemberFields",
+    "StaffTshirtFields",
+    "StandingsFields",
+    "TeamFields",
+    "TeamMemberFields",
+    "TeamSummaryFields",
+    "Top20Fields",
+    "TransportationMissingFields",
+    "TshirtFields",
+    "contest_institutions",
+    "contest_missing_transportation",
+    "contest_participants",
+    "contest_promote_candidates",
+    "contest_public_staff_members",
+    "contest_staff",
+    "contest_staff_certificates",
+    "contest_staff_funding",
+    "contest_staff_members",
+    "contest_staff_tshirts",
+    "contest_standings",
+    "contest_team_certificates",
+    "contest_team_members",
+    "contest_team_summaries",
+    "contest_teams",
+    "contest_top20",
+    "endpoints",
+    "site_coach_tshirts",
+    "site_cocoach_tshirts",
+    "site_contestant_tshirts",
+    "site_home_teams",
+    "site_institutions",
+    "site_participants",
+    "site_team_certificates",
+    "site_team_members",
+    "site_teams",
+]