icpc-api 0.2.1__tar.gz → 0.4.0__tar.gz

{icpc_api-0.2.1/icpc_api.egg-info → icpc_api-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: icpc-api
-Version: 0.2.1
+Version: 0.4.0
 Summary: Unofficial Python client and CLI for the icpc.global API
 Author-email: Nikita Sychev <root@nsychev.ru>
 License-Expression: MIT

{icpc_api-0.2.1 → icpc_api-0.4.0}/icpc/__init__.py

@@ -14,7 +14,7 @@ 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.2.1"
+__version__ = "0.4.0"
 
 __all__ = [
     "ApiError",

icpc_api-0.4.0/icpc/api/common.py

@@ -0,0 +1,207 @@
+"""``/common``, ``/icpcprofile`` and the ``/aspectfaces`` schema registry."""
+
+from __future__ import annotations
+
+import mimetypes
+
+from icpc.models.base import Row
+from icpc.models.entities import (
+    Globals,
+    Institution,
+    InstitutionSuggestion,
+    InstitutionUnit,
+    SuggestedInstitution,
+)
+from icpc.transport.operation import Operation, Request, list_op, model_op, none_op, scalar_op
+
+__all__ = [
+    "AspectFacesField",
+    "AspectFacesSchema",
+    "approve_suggested_institution",
+    "create_suggested_institution",
+    "globals_",
+    "institution",
+    "institution_suggest",
+    "institution_unit",
+    "institution_units",
+    "schema",
+    "set_institution_logo",
+    "update_institution",
+    "update_institution_unit",
+    "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,
+    )
+
+
+def institution(institution_id: int) -> Operation[Institution]:
+    """An institution, by the ``instId`` of the institution search grids."""
+    return model_op(Request("GET", f"/common/institution/{institution_id}"), Institution)
+
+
+def institution_units(institution_id: int) -> Operation[list[InstitutionUnit]]:
+    """The units of an institution; usually exactly one."""
+    return list_op(
+        Request("GET", f"/common/institutionunit/inst/{institution_id}"), InstitutionUnit
+    )
+
+
+def institution_unit(unit_id: int) -> Operation[InstitutionUnit]:
+    """An institution unit, by the ``instUnitId`` of the institution search grids."""
+    return model_op(Request("GET", f"/common/institutionunit/{unit_id}"), InstitutionUnit)
+
+
+def update_institution(institution: dict[str, object]) -> Operation[Institution]:
+    """Overwrite an institution's names and homepage.
+
+    A full-object replace keyed by ``id`` and ``version``: read with
+    :func:`institution`, change what you want, send it all back.
+    """
+    return model_op(
+        Request("POST", "/common/institution", json=institution, idempotent=False), Institution
+    )
+
+
+def update_institution_unit(unit: dict[str, object]) -> Operation[InstitutionUnit]:
+    """Overwrite an institution unit, address and social links included.
+
+    A full-object replace, like :func:`update_institution`. The unit repeats the
+    institution's names; the two are not kept in sync by the server.
+    """
+    return model_op(
+        Request("POST", "/common/institutionunit", json=unit, idempotent=False), InstitutionUnit
+    )
+
+
+def create_suggested_institution(
+    institution: dict[str, object],
+) -> Operation[SuggestedInstitution]:
+    """Suggest a new institution, as the "can't find my institution" form does.
+
+    Required: ``name`` (7+ characters), ``shortName``, ``homepageUrl`` and
+    ``institutionUnitType``. ``mailingAddress.country`` is a whole country object;
+    take it from :func:`icpc.models.countries.country`.
+    """
+    return model_op(
+        Request("POST", "/common/suggestedinstitution/", json=institution, idempotent=False),
+        SuggestedInstitution,
+    )
+
+
+def approve_suggested_institution(suggestion_id: int) -> Operation[None]:
+    """Turn a suggestion from :func:`create_suggested_institution` into an institution."""
+    return none_op(
+        Request("PUT", f"/common/suggestedinstitution/approve/{suggestion_id}", idempotent=False)
+    )
+
+
+#: What the logo form accepts; the server enforces the same limits.
+LOGO_TYPES = frozenset({"image/svg+xml", "image/jpeg", "image/bmp", "image/png", "image/gif"})
+LOGO_MAX_BYTES = 3_000_000
+
+
+def logo_mime(filename: str, size: int) -> str:
+    """The content type for a logo upload, or ``ValueError`` if the form would refuse it."""
+    mime, _ = mimetypes.guess_type(filename)
+    if mime not in LOGO_TYPES:
+        raise ValueError(f"{filename}: a logo must be SVG, JPEG, BMP, PNG or GIF")
+    if size > LOGO_MAX_BYTES:
+        raise ValueError(f"{filename}: {size} bytes; a logo must be under 3000 kB")
+    return mime
+
+
+def set_institution_logo(
+    institution_id: int, filename: str, content: bytes, mime: str
+) -> Operation[None]:
+    """Upload an institution's logo, replacing any current one.
+
+    Keyed by ``instId``. SVG, JPEG, BMP, PNG or GIF, at most 3000 kB;
+    :func:`logo_mime` checks both and picks ``mime``.
+    """
+    return none_op(
+        Request(
+            "POST",
+            f"/common/logo/institution/{institution_id}",
+            files={"file": (filename, content, mime)},
+            idempotent=False,
+        )
+    )

{icpc_api-0.2.1 → icpc_api-0.4.0}/icpc/cli/main.py

@@ -6,14 +6,17 @@ client exists.
 
 from __future__ import annotations
 
+import copy
 import os
 import sys
 from collections.abc import Sequence
 from dataclasses import dataclass
 from datetime import UTC, datetime
+from pathlib import Path
 from typing import Annotated, Any
 
 import typer
+from pydantic import BaseModel, TypeAdapter, ValidationError
 
 from icpc import errors
 from icpc.api import common as common_api
@@ -42,10 +45,13 @@ from icpc.cli.columns import (
 from icpc.cli.render import OutputFormat, fail, note, render, warn
 from icpc.config import Settings
 from icpc.facade.client import Icpc, Include
-from icpc.models.enums import ExportType, MemberRole, TeamStatus
+from icpc.models.countries import country
+from icpc.models.entities import SiteSettings
+from icpc.models.enums import ExportType, InstitutionUnitType, MemberRole, TeamStatus
 from icpc.search import _generated as endpoints
 from icpc.search.dsl import Filter, SortKey
 from icpc.search.endpoint import SearchEndpoint
+from icpc.search.institutions import institutions
 from icpc.search.surveys import survey_responses
 from icpc.transport.operation import Request, json_op
 
@@ -57,6 +63,7 @@ public_app = typer.Typer(no_args_is_help=True, help="Public endpoints; no login
 person_app = typer.Typer(no_args_is_help=True, help="Look people up.")
 staff_app = typer.Typer(no_args_is_help=True, help="Contest staff.")
 survey_app = typer.Typer(no_args_is_help=True, help="Contest surveys and their answers.")
+institution_app = typer.Typer(no_args_is_help=True, help="Find and edit institutions.")
 app.add_typer(auth_app, name="auth")
 app.add_typer(contest_app, name="contest")
 app.add_typer(team_app, name="team")
@@ -64,6 +71,7 @@ app.add_typer(public_app, name="public")
 app.add_typer(person_app, name="person")
 app.add_typer(staff_app, name="staff")
 app.add_typer(survey_app, name="survey")
+app.add_typer(institution_app, name="institution")
 
 
 @dataclass
@@ -79,12 +87,16 @@ def _ctx(ctx: typer.Context) -> Context:
 def _client(ctx: typer.Context) -> Icpc:
     """Build a client from whatever credentials are available.
 
-    An explicit token in the environment wins, so CI and one-off shells do not
-    need a login; otherwise the tokens cached by ``icpc auth login`` are used.
+    Looks up in the following order:
+    - `ICPC_ID_TOKEN` or `ICPC_REFRESH_TOKEN` environment variables
+    - `ICPC_USERNAME` and `ICPC_PASSWORD` variables
+    - credentials stored with `icpc auth login`
     """
     state = _ctx(ctx)
     if os.environ.get("ICPC_ID_TOKEN") or os.environ.get("ICPC_REFRESH_TOKEN"):
         return Icpc.from_token()
+    if os.environ.get("ICPC_PASSWORD"):
+        return Icpc.from_password(state.username)
     return Icpc.from_store(state.username)
 
 
@@ -334,7 +346,7 @@ def person_show(ctx: typer.Context, person_id: int) -> None:
         render(icpc.send(person_api.get(person_id)), _ctx(ctx).output)
 
 
-@app.command("institution")
+@institution_app.command("find")
 def institution_find(
     ctx: typer.Context,
     name: Annotated[str, typer.Argument(help="Institution name; three characters or more.")],
@@ -346,8 +358,8 @@ def institution_find(
     """Find an institution id, for registering a team.
 
     The id printed here is the one `team register --institution` wants. It is a
-    different number from the `instId` and `instUnitId` columns of the
-    `institutions` grid, which point at other tables.
+    different number from the `instId` and `instUnitId` columns of
+    `institution search`, which point at other tables.
     """
     with _client(ctx) as icpc:
         rows = icpc.send(common_api.institution_suggest(name, size=limit))
@@ -360,6 +372,166 @@ def institution_find(
     render(rows, _ctx(ctx).output, columns=["id", "name", "country", "url"])
 
 
+@institution_app.command("search")
+def institution_search(
+    ctx: typer.Context,
+    name: Annotated[str | None, typer.Argument(help="Substring of instName.")] = None,
+    filter_: Annotated[
+        list[str] | None, typer.Option("--filter", help="COLUMN#VALUE, repeatable.")
+    ] = None,
+    limit: Annotated[int, typer.Option("--limit", help="Stop after this many rows.")] = 20,
+) -> None:
+    """Search every institution, as the admin grid does.
+
+        icpc institution search Massachusetts --filter countryName#"United States"
+
+    `instId` is what `institution show` and `set` take; `instUnitId` is what
+    `unit` and `set-unit` take.
+    """
+    endpoint = institutions()
+    raw = ([f"instName#{name}"] if name else []) + (filter_ or [])
+    q = endpoint.query(filters=_parse_filters(raw))
+    with _client(ctx) as icpc:
+        rows = icpc.all(endpoint, q, max_rows=limit)
+    render(rows, _ctx(ctx).output, columns=list(q.proj))
+
+
+#: Keys of `institution create`: top-level, then the ones that go in mailingAddress.
+_NEW_INSTITUTION = ("name", "shortName", "homepageUrl", "institutionUnitType")
+_NEW_ADDRESS = ("addressLine1", "addressLine2", "addressLine3", "city", "state", "zip", "country")
+
+
+@institution_app.command("set-logo")
+def institution_set_logo(
+    ctx: typer.Context,
+    institution_id: int,
+    path: Annotated[Path, typer.Argument(exists=True, dir_okay=False, help="The image file.")],
+) -> None:
+    """Upload an institution's logo, by instId: SVG, JPEG, BMP, PNG or GIF, under 3000 kB.
+
+    icpc institution set-logo 1145 mit.svg
+    """
+    content = path.read_bytes()
+    try:
+        mime = common_api.logo_mime(path.name, len(content))
+    except ValueError as e:
+        raise typer.BadParameter(str(e)) from None
+    with _client(ctx) as icpc:
+        icpc.send(common_api.set_institution_logo(institution_id, path.name, content, mime))
+    note(f"logo of institution {institution_id} set from {path}")
+
+
+@institution_app.command("create")
+def institution_create(
+    ctx: typer.Context,
+    fields: Annotated[list[str], typer.Argument(help="KEY=VALUE; see below.")],
+) -> None:
+    """Suggest a new institution, as the "can't find my institution" form does.
+
+        icpc institution create "name=Massachusetts Institute of Technology" "shortName=MIT" \\
+            homepageUrl=https://web.mit.edu/ institutionUnitType=UNIVERSITY_GRADUATE \\
+            "addressLine1=77 Massachusetts Avenue" city=Cambridge state=MA zip=02139 country=US
+
+    Keys: name, shortName, homepageUrl, institutionUnitType (HIGH_SCHOOL,
+    UNIVERSITY_NO_GRADUATE, UNIVERSITY_GRADUATE), addressLine1-3, city, state,
+    zip, country (ISO code or name). Values stay strings, so zip=01234 is kept.
+    """
+    values: dict[str, str] = {}
+    for pair in fields:
+        key, sep, value = pair.partition("=")
+        if not sep or key not in _NEW_INSTITUTION + _NEW_ADDRESS:
+            raise typer.BadParameter(
+                f"expected KEY=VALUE with KEY one of {', '.join(_NEW_INSTITUTION + _NEW_ADDRESS)};"
+                f" got {pair!r}"
+            )
+        values[key] = value
+    missing = [k for k in (*_NEW_INSTITUTION, "country") if not values.get(k)]
+    if missing:
+        raise typer.BadParameter(f"missing {', '.join(missing)}")
+    try:
+        InstitutionUnitType(values["institutionUnitType"])
+        values["country"] = country(values["country"]).model_dump(by_alias=True)  # type: ignore[assignment]
+    except ValueError as e:
+        raise typer.BadParameter(str(e)) from None
+    body: dict[str, object] = {k: values[k] for k in _NEW_INSTITUTION}
+    body["mailingAddress"] = {k: values[k] for k in _NEW_ADDRESS if k in values}
+    with _client(ctx) as icpc:
+        render(icpc.send(common_api.create_suggested_institution(body)), _ctx(ctx).output)
+
+
+@institution_app.command("approve")
+def institution_approve(
+    ctx: typer.Context,
+    suggestion_id: Annotated[int, typer.Argument(help="The id `institution create` printed.")],
+) -> None:
+    """Approve a suggested institution, turning it into a real one. Needs a moderator."""
+    with _client(ctx) as icpc:
+        icpc.send(common_api.approve_suggested_institution(suggestion_id))
+    note(f"suggested institution {suggestion_id} approved")
+
+
+@institution_app.command("show")
+def institution_show(ctx: typer.Context, institution_id: int) -> None:
+    """An institution, by instId."""
+    with _client(ctx) as icpc:
+        render(icpc.send(common_api.institution(institution_id)), _ctx(ctx).output)
+
+
+@institution_app.command("units")
+def institution_units(ctx: typer.Context, institution_id: int) -> None:
+    """The units of an institution, by instId; usually exactly one."""
+    with _client(ctx) as icpc:
+        render(icpc.send(common_api.institution_units(institution_id)), _ctx(ctx).output)
+
+
+@institution_app.command("unit")
+def institution_unit(ctx: typer.Context, unit_id: int) -> None:
+    """An institution unit, by instUnitId."""
+    with _client(ctx) as icpc:
+        render(icpc.send(common_api.institution_unit(unit_id)), _ctx(ctx).output)
+
+
+@institution_app.command("set")
+def institution_set(
+    ctx: typer.Context,
+    institution_id: int,
+    changes: Annotated[list[str], typer.Argument(help="KEY=VALUE, e.g. shortName=MIT.")],
+) -> None:
+    """Change an institution's names or homepage.
+
+        icpc institution set 1145 shortName=MIT homepageUrl=https://web.mit.edu/
+
+    The unit repeats these names; change it too with `set-unit`.
+    """
+    _edit(
+        ctx,
+        "institution",
+        common_api.institution(institution_id),
+        common_api.update_institution,
+        changes,
+    )
+
+
+@institution_app.command("set-unit")
+def institution_set_unit(
+    ctx: typer.Context,
+    unit_id: int,
+    changes: Annotated[list[str], typer.Argument(help="KEY=VALUE; nested as a.b=VALUE.")],
+) -> None:
+    """Change an institution unit, address and social links included.
+
+        icpc institution set-unit 1220 shortName=MIT mailingAddress.city=Cambridge \\
+            socialInfo.twitterName=mit
+    """
+    _edit(
+        ctx,
+        "institution unit",
+        common_api.institution_unit(unit_id),
+        common_api.update_institution_unit,
+        changes,
+    )
+
+
 # ------------------------------------------------------------------- staff --
 
 
@@ -568,9 +740,59 @@ def contest_set_site(
         contest_api.site_settings(site_id),
         lambda o: contest_api.update_site_settings(contest_id, o),
         changes,
+        SiteSettings,
     )
 
 
+_NEW_SITE_SETTINGS: dict[str, Any] = {
+    "details": "",
+    "allowRegistration": False,
+    "invitationOnly": False,
+    "homepage": "",
+    "additionalInfo": "",
+    "enforceCapacity": False,
+    "allowTeamChanges": False,
+}
+_NEW_SITE_REQUIRED = ("locationName", "capacity", "siteDelivery", "siteType")
+
+
+@contest_app.command("add-site")
+def contest_add_site(
+    ctx: typer.Context,
+    contest_id: int,
+    fields: Annotated[list[str], typer.Argument(help="KEY=VALUE; see below.")],
+) -> None:
+    """Add a site to a contest.
+
+        icpc contest add-site 1235 "name=World Finals" email=manager@icpc.global \
+            locationName=Dubai capacity=150 siteDelivery=ONSITE siteType=NORMAL \
+            allowRegistration=true enforceCapacity=true
+
+    Required: name, email, locationName, capacity, siteDelivery, siteType.
+    Optional: allowRegistration, invitationOnly, enforceCapacity, allowTeamChanges,
+    details, homepage, additionalInfo.
+    """
+    values = _assignments(fields)
+    body: dict[str, Any] = {"name": values.pop("name", None), "email": values.pop("email", None)}
+    missing = [k for k in ("name", "email") if not body[k]]
+    missing += [k for k in _NEW_SITE_REQUIRED if values.get(k) in (None, "")]
+    if missing:
+        raise typer.BadParameter(f"missing {', '.join(missing)}")
+    known = (*_NEW_SITE_REQUIRED, *_NEW_SITE_SETTINGS)
+    unknown = sorted(set(values) - set(known))
+    if unknown:
+        raise typer.BadParameter(
+            f"unknown {', '.join(unknown)}; known: name, email, {', '.join(known)}"
+        )
+    try:
+        settings = SiteSettings.model_validate({**_NEW_SITE_SETTINGS, **values})
+    except ValidationError as e:
+        raise typer.BadParameter(_validation_message(e)) from None
+    body["siteSettings"] = settings.model_dump(by_alias=True, exclude_unset=True)
+    with _client(ctx) as icpc:
+        render(icpc.send(contest_api.create_site(contest_id, body)), _ctx(ctx).output)
+
+
 @contest_app.command("summary")
 def contest_summary(ctx: typer.Context, contest_id: int) -> None:
     """Team counts by site and by status, from one joined fetch."""
@@ -698,49 +920,82 @@ def contest_load(
 
 
 def _assignments(pairs: list[str]) -> dict[str, Any]:
-    """Parse ``key=value`` arguments, coercing the obvious literals.
+    """Parse ``key=value`` arguments; ``null`` becomes None, the rest stay strings.
 
-    ``true``/``false``/``null`` and bare numbers become JSON values; everything
-    else stays a string. Wrap a value in quotes to force a string.
+    The caller types them by its model, so ``zip=010000`` keeps its zero while
+    ``capacity=50`` turns into a number.
     """
     out: dict[str, Any] = {}
     for pair in pairs:
         key, sep, raw = pair.partition("=")
         if not sep:
             raise typer.BadParameter(f"expected KEY=VALUE, got {pair!r}")
-        low = raw.lower()
-        if low in ("true", "false"):
-            out[key] = low == "true"
-        elif low in ("null", "none"):
-            out[key] = None
-        elif raw.lstrip("-").isdigit():
-            out[key] = int(raw)
-        else:
-            out[key] = raw.strip('"')
+        out[key] = None if raw.lower() in ("null", "none") else raw
     return out
 
 
-def _edit(ctx: typer.Context, label: str, read: Any, write: Any, pairs: list[str]) -> None:
+def _validation_message(e: ValidationError) -> str:
+    return "; ".join(f"{'.'.join(map(str, err['loc']))}: {err['msg']}" for err in e.errors())
+
+
+def _edit(
+    ctx: typer.Context,
+    label: str,
+    read: Any,
+    write: Any,
+    pairs: list[str],
+    model: type[BaseModel] | None = None,
+) -> None:
     """Read a settings object, apply ``key=value`` changes, write it back.
 
     These endpoints are full-object replaces, so the read is not optional: send
-    only the changed keys and everything else is wiped.
+    only the changed keys and everything else is wiped. ``a.b=value`` sets a key
+    of a nested object.
+
+    Values are typed by ``model``, by default the model ``read`` returns. A field
+    the model doesn't declare takes the type of its current value, or stays a
+    string if that is null.
     """
     changes = _assignments(pairs)
     with _client(ctx) as icpc:
         current = icpc.send(read)
-        obj = current if isinstance(current, dict) else current.model_dump(by_alias=True)
-        unknown = [k for k in changes if k not in obj]
-        if unknown:
-            fail(f"{label} has no field(s) {unknown}; known: {', '.join(sorted(obj))}")
-            raise typer.Exit(1)
-        for key, value in changes.items():
-            note(f"{key}: {obj.get(key)!r} -> {value!r}")
-        icpc.send(write({**obj, **changes}))
+        if isinstance(current, BaseModel):
+            model = model or type(current)
+            current = current.model_dump(by_alias=True)
+        obj = copy.deepcopy(current)
+        try:
+            for path, value in changes.items():
+                *parents, key = path.split(".")
+                target = obj
+                for part in parents:
+                    target = target.get(part) if isinstance(target, dict) else None
+                if not isinstance(target, dict) or key not in target:
+                    known = sorted(target) if isinstance(target, dict) else []
+                    fail(f"{label} has no field {path!r}; known here: {', '.join(known)}")
+                    raise typer.Exit(1)
+                old = target[key]
+                if value is not None and isinstance(old, bool | int | float):
+                    target[key] = TypeAdapter(type(old)).validate_python(value)
+                else:
+                    target[key] = value
+            if model is not None:
+                obj = model.model_validate(obj).model_dump(by_alias=True, exclude_unset=True)
+        except ValidationError as e:
+            fail(f"bad value for {label}: {_validation_message(e)}")
+            raise typer.Exit(1) from None
+        for path in changes:
+            note(f"{path}: {_at(current, path)!r} -> {_at(obj, path)!r}")
+        icpc.send(write(obj))
         after = icpc.send(read)
     render(after, _ctx(ctx).output)
 
 
+def _at(obj: Any, path: str) -> Any:
+    for part in path.split("."):
+        obj = obj[part]
+    return obj
+
+
 def _grid(name: str, entity_id: int) -> SearchEndpoint[Any, Any]:
     factory = GRIDS.get(name)
     if factory is None:

{icpc_api-0.2.1 → icpc_api-0.4.0}/icpc/models/common.py

@@ -4,6 +4,9 @@ from __future__ import annotations
 
 import base64
 import binascii
+from typing import Any
+
+from pydantic import SerializerFunctionWrapHandler, model_serializer
 
 from icpc.models.base import Row
 
@@ -28,6 +31,16 @@ class Country(Row):
     number: int | None = None
     currency: str | None = None
     available: bool | None = None
+    #: Only the frontend's bundled list carries this; the server never sends it.
+    uuid: str | None = None
+
+    @model_serializer(mode="wrap")
+    def _drop_missing_uuid(self, handler: SerializerFunctionWrapHandler) -> dict[str, Any]:
+        """Leave out a ``uuid`` the server never sent, so edits send back what they read."""
+        data = handler(self)
+        if data.get("uuid") is None:
+            data.pop("uuid", None)
+        return data
 
 
 class FileRef(Row):