From 7be6a7815229b070c75c2730d12cb5a994fd492a Mon Sep 17 00:00:00 2001 From: Sava Znatnov Date: Sat, 10 Oct 2026 23:31:03 +0700 Subject: [PATCH] feat(forms)!: `forms answers list` is a listing like every other, and `columns-list` gives its columns MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The answers of a form are listed with the three handles of every listing: `--limit`, `--all` and `--next` in the CLI, `limit` / `all` / `next` in the tool, a lazy `Listing[Answer]` in the SDK. The columns the cells of an answer stand in are read by a command of their own, `forms answers columns-list` (`forms_answers_columns_list`, `forms.answers.columns_list`): the API has no request for them alone, so it reads one answer to learn them. BREAKING CHANGE: `forms answers list -o json` prints `{items, truncated, next, total}` instead of `{columns, answers, next}`: a script reads `.items[]` where it read `.answers[]`, and takes the columns from `forms answers columns-list`. `forms.answers.list()` returns `Listing[Answer]` instead of `AnswersResponse`, and the tool `forms_answers_list` returns the listing object. Decision 3-Б of #538. Co-Authored-By: Claude Opus 5.5 --- .agents/skills/yandex-360-forms/SKILL.md | 3 +- .claude/skills/yandex-360-forms/SKILL.md | 3 +- .opencode/skills/yandex-360-forms/SKILL.md | 3 +- README.md | 10 +- README.ru.md | 4 +- docs/assets/coverage.svg | 10 +- docs/en/reference/cli/forms.md | 32 +++++ docs/en/reference/mcp/forms.md | 23 +++- docs/examples/services/cards.en.md | 2 +- docs/examples/services/cards.ru.md | 2 +- .../services/comparison.operations.en.md | 2 +- .../services/comparison.operations.ru.md | 2 +- docs/examples/services/comparison.row.en.md | 2 +- docs/examples/services/comparison.row.ru.md | 2 +- docs/examples/services/forms.header.en.md | 2 +- docs/examples/services/forms.header.ru.md | 2 +- e2e/scenarios/forms/survey_options.yaml | 10 +- .../skills/yandex-360-forms/SKILL.md | 3 +- src/ycli/yandex/forms/answers/cli.py | 34 ++++- src/ycli/yandex/forms/answers/client.py | 69 +++++++---- src/ycli/yandex/forms/answers/endpoints.py | 17 +++ src/ycli/yandex/forms/answers/mcp.py | 39 ++++-- src/ycli/yandex/forms/answers/models.py | 4 +- tests/architecture/test_arch1.py | 2 - tests/snapshots/cli_signatures.txt | 3 +- tests/snapshots/mcp_output_schemas.txt | 3 +- tests/snapshots/mcp_signatures.txt | 3 +- tests/unit/yandex/forms/answers/cases.py | 117 +++++++++--------- .../unit/yandex/forms/answers/test_client.py | 24 +++- 29 files changed, 297 insertions(+), 135 deletions(-) diff --git a/.agents/skills/yandex-360-forms/SKILL.md b/.agents/skills/yandex-360-forms/SKILL.md index 5d6c75ace..c099067e9 100644 --- a/.agents/skills/yandex-360-forms/SKILL.md +++ b/.agents/skills/yandex-360-forms/SKILL.md @@ -60,6 +60,7 @@ The OAuth token needs `forms:read` / `forms:write` scopes (see the auth section | List questions (schema) | `uv run ycli forms questions list ` | `forms_questions_list` | | Get one question | `uv run ycli forms questions get ` | `forms_questions_get` | | List answers (responses) | `uv run ycli forms answers list [--all]` | `forms_answers_list` | +| The columns the cells of an answer stand in | `uv run ycli forms answers columns-list ` | `forms_answers_columns_list` | | Fillable form view (option ids!) | `uv run ycli forms filling get ` | `forms_filling_get` | | Suggest values for a question | `uv run ycli forms filling suggest --question --text …` | `forms_filling_suggest` | | Keysets | `uv run ycli forms keysets list\|get …` | `forms_keysets_list` / `forms_keysets_get` | @@ -79,7 +80,7 @@ forms.me.get() # auth probe forms.surveys.list() # list forms forms.surveys.get("") # form settings forms.questions.list("") # schema -forms.answers.list("") # responses +forms.answers.list("") # responses; forms.answers.columns_list("") names their cells ``` --- diff --git a/.claude/skills/yandex-360-forms/SKILL.md b/.claude/skills/yandex-360-forms/SKILL.md index 347ea42b8..1e4e7af83 100644 --- a/.claude/skills/yandex-360-forms/SKILL.md +++ b/.claude/skills/yandex-360-forms/SKILL.md @@ -62,6 +62,7 @@ The OAuth token needs `forms:read` / `forms:write` scopes (see the auth section | List questions (schema) | `uv run ycli forms questions list ` | `forms_questions_list` | | Get one question | `uv run ycli forms questions get ` | `forms_questions_get` | | List answers (responses) | `uv run ycli forms answers list [--all]` | `forms_answers_list` | +| The columns the cells of an answer stand in | `uv run ycli forms answers columns-list ` | `forms_answers_columns_list` | | Fillable form view (option ids!) | `uv run ycli forms filling get ` | `forms_filling_get` | | Suggest values for a question | `uv run ycli forms filling suggest --question --text …` | `forms_filling_suggest` | | Keysets | `uv run ycli forms keysets list\|get …` | `forms_keysets_list` / `forms_keysets_get` | @@ -81,7 +82,7 @@ forms.me.get() # auth probe forms.surveys.list() # list forms forms.surveys.get("") # form settings forms.questions.list("") # schema -forms.answers.list("") # responses +forms.answers.list("") # responses; forms.answers.columns_list("") names their cells ``` --- diff --git a/.opencode/skills/yandex-360-forms/SKILL.md b/.opencode/skills/yandex-360-forms/SKILL.md index 347ea42b8..1e4e7af83 100644 --- a/.opencode/skills/yandex-360-forms/SKILL.md +++ b/.opencode/skills/yandex-360-forms/SKILL.md @@ -62,6 +62,7 @@ The OAuth token needs `forms:read` / `forms:write` scopes (see the auth section | List questions (schema) | `uv run ycli forms questions list ` | `forms_questions_list` | | Get one question | `uv run ycli forms questions get ` | `forms_questions_get` | | List answers (responses) | `uv run ycli forms answers list [--all]` | `forms_answers_list` | +| The columns the cells of an answer stand in | `uv run ycli forms answers columns-list ` | `forms_answers_columns_list` | | Fillable form view (option ids!) | `uv run ycli forms filling get ` | `forms_filling_get` | | Suggest values for a question | `uv run ycli forms filling suggest --question --text …` | `forms_filling_suggest` | | Keysets | `uv run ycli forms keysets list\|get …` | `forms_keysets_list` / `forms_keysets_get` | @@ -81,7 +82,7 @@ forms.me.get() # auth probe forms.surveys.list() # list forms forms.surveys.get("") # form settings forms.questions.list("") # schema -forms.answers.list("") # responses +forms.answers.list("") # responses; forms.answers.columns_list("") names their cells ``` --- diff --git a/README.md b/README.md index c04024742..a515951ce 100644 --- a/README.md +++ b/README.md @@ -132,9 +132,9 @@ Timeouts, retries, limits, logging and the exit codes are in the [configuration ## Coverage -467 operations across 88 resources: Tracker 190, Wiki 58, Forms 85, DataLens 134 +468 operations across 88 resources: Tracker 190, Wiki 58, Forms 86, DataLens 134 -`ycli` wraps **467 operations across 88 resources** of the Tracker, Wiki, Forms, and DataLens API. Every one is reachable from the **Python SDK** and the **CLI**, and 457 **MCP** tools serve them to agents (455 per service plus `schema_get`, `status_get`). +`ycli` wraps **468 operations across 88 resources** of the Tracker, Wiki, Forms, and DataLens API. Every one is reachable from the **Python SDK** and the **CLI**, and 458 **MCP** tools serve them to agents (456 per service plus `schema_get`, `status_get`). > **Legend.** ✅ in **CLI** or **MCP** means the resource is reachable on that surface; MCP tools carry honest hints (reads are `readOnlyHint`, writes say whether they are destructive or idempotent), and `ycli mcp start --read-only` serves only the reads. Resource and operation names link to the official **Yandex API reference**. An operation has one of three states against what Yandex publishes. **Covered** (no mark): ycli sends every published parameter and reads every published field. **Partial** (◐): ycli wraps it and differs somewhere; the mark links to the row that says where and why. **Not covered** (○): Yandex publishes it and ycli does not wrap it; these are listed under each service. Wiki, Forms and DataLens are measured against their OpenAPI documents; Tracker publishes none, so its state is measured against the reference pages (operations, and query parameters where a page lists them). DataLens is in progress, wrapped section by section: the operations of a section ycli has not begun are pending, not missing. Generated from the code by [`scripts/gen_coverage.py`](scripts/gen_coverage.py); do not edit by hand. @@ -259,7 +259,7 @@ Timeouts, retries, limits, logging and the exit codes are in the [configuration ### Forms
-16 resources · 85 operations · 78 MCP tools +16 resources · 86 operations · 79 MCP tools **Surveys & questions** @@ -275,7 +275,7 @@ Timeouts, retries, limits, logging and the exit codes are in the [configuration | Resource | Operations | CLI | MCP | |----------|------------|:---:|:---:| -| [answers](https://yandex.ru/support/forms/en/api-ref/answers/events_b2b_v1_views_answers_get_answers_public_view) | [get](https://yandex.ru/support/forms/en/api-ref/answers/events_b2b_v1_views_answers_get_answer_public_view) · [list](https://yandex.ru/support/forms/en/api-ref/answers/events_b2b_v1_views_answers_get_answers_public_view) · [export](https://yandex.ru/support/forms/en/api-ref/answers/events_b2b_v1_views_answers_export_answers_public_view) · [export_results_get](https://yandex.ru/support/forms/en/api-ref/answers/events_b2b_v1_views_answers_export_answers_results_public_view) · [export_download](https://yandex.ru/support/forms/en/api-ref/answers/events_b2b_v1_views_answers_export_answers_results_public_view) · [integrations_list](https://yandex.ru/support/forms/en/api-ref/events/events_b2b_v1_views_answers_get_integrations_public_view) · [delete](https://yandex.ru/support/forms/en/api-ref/answers/events_b2b_v1_views_answers_get_answers_public_view) · [restore](https://yandex.ru/support/forms/en/api-ref/answers/events_b2b_v1_views_answers_get_answers_public_view) | ✅ | ✅ | +| [answers](https://yandex.ru/support/forms/en/api-ref/answers/events_b2b_v1_views_answers_get_answers_public_view) | [get](https://yandex.ru/support/forms/en/api-ref/answers/events_b2b_v1_views_answers_get_answer_public_view) · [list](https://yandex.ru/support/forms/en/api-ref/answers/events_b2b_v1_views_answers_get_answers_public_view) · [columns_list](https://yandex.ru/support/forms/en/api-ref/answers/events_b2b_v1_views_answers_get_answers_public_view) · [export](https://yandex.ru/support/forms/en/api-ref/answers/events_b2b_v1_views_answers_export_answers_public_view) · [export_results_get](https://yandex.ru/support/forms/en/api-ref/answers/events_b2b_v1_views_answers_export_answers_results_public_view) · [export_download](https://yandex.ru/support/forms/en/api-ref/answers/events_b2b_v1_views_answers_export_answers_results_public_view) · [integrations_list](https://yandex.ru/support/forms/en/api-ref/events/events_b2b_v1_views_answers_get_integrations_public_view) · [delete](https://yandex.ru/support/forms/en/api-ref/answers/events_b2b_v1_views_answers_get_answers_public_view) · [restore](https://yandex.ru/support/forms/en/api-ref/answers/events_b2b_v1_views_answers_get_answers_public_view) | ✅ | ✅ | | [operations](https://yandex.ru/support/forms/en/api-ref/operations/events_v1_views_operations_get_operation_view) | [get](https://yandex.ru/support/forms/en/api-ref/operations/events_v1_views_operations_get_operation_view) | ✅ | ✅ | **Integrations** @@ -396,7 +396,7 @@ Timeouts, retries, limits, logging and the exit codes are in the [configuration
-Every resource and operation above deep-links to the Yandex API reference: 406 of 467 operations resolve to their own endpoint page and 19 to their resource's page. No public API reference exists yet for `datalens.cloudenvironments`, `datalens.cloudenvironments.create`, `datalens.cloudenvironments.delete`, `datalens.cloudenvironments.get`, `datalens.cloudenvironments.list`, `datalens.cloudenvironments.update`, `datalens.cloudenvironmentstorage`, `datalens.cloudenvironmentstorage.bucket_download_url_create`, `datalens.cloudenvironmentstorage.bucket_object_metadata_get`, `datalens.cloudenvironmentstorage.bucket_objects_list`, `datalens.cloudenvironmentstorage.bucket_upload_url_create`, `datalens.lakehouseoperations`, `datalens.lakehouseoperations.get`, `datalens.restcatalogs`, `datalens.restcatalogs.create`, `datalens.restcatalogs.list`, `datalens.sparkapplications`, `datalens.sparkapplications.cancel`, `datalens.sparkapplications.create`, `datalens.sparkapplications.get`, `datalens.sparkapplications.list`, `datalens.sparkapplications.log_list`, `datalens.sparkclusters`, `datalens.sparkclusters.create`, `datalens.sparkclusters.delete`, `datalens.sparkclusters.get`, `datalens.sparkclusters.list`, `datalens.sparkclusters.resource_presets_get`, `datalens.sparkclusters.resource_presets_list`, `datalens.sparkclusters.start`, `datalens.sparkclusters.stop`, `datalens.sqlqueries`, `datalens.sqlqueries.create`, `datalens.sqlqueries.delete`, `datalens.sqlqueries.get`, `datalens.sqlqueries.run`, `datalens.sqlqueries.update`, `datalens.tenant`, `datalens.tenant.details_get`, `datalens.trinoclusters`, `datalens.trinoclusters.catalog_create`, `datalens.trinoclusters.catalog_delete`, `datalens.trinoclusters.create`, `datalens.trinoclusters.delete`, `datalens.trinoclusters.get`, `datalens.trinoclusters.list`, `datalens.trinoclusters.resource_preset_get`, `datalens.trinoclusters.resource_presets_list`, `datalens.trinoclusters.start`, `datalens.trinoclusters.stop`, `tracker.linktypes`, `tracker.linktypes.list`, shown as plain text. See `CONTRIBUTING.md` for the intentional exclusions (UI-only endpoints with no public REST API) and per-method notes. +Every resource and operation above deep-links to the Yandex API reference: 406 of 468 operations resolve to their own endpoint page and 20 to their resource's page. No public API reference exists yet for `datalens.cloudenvironments`, `datalens.cloudenvironments.create`, `datalens.cloudenvironments.delete`, `datalens.cloudenvironments.get`, `datalens.cloudenvironments.list`, `datalens.cloudenvironments.update`, `datalens.cloudenvironmentstorage`, `datalens.cloudenvironmentstorage.bucket_download_url_create`, `datalens.cloudenvironmentstorage.bucket_object_metadata_get`, `datalens.cloudenvironmentstorage.bucket_objects_list`, `datalens.cloudenvironmentstorage.bucket_upload_url_create`, `datalens.lakehouseoperations`, `datalens.lakehouseoperations.get`, `datalens.restcatalogs`, `datalens.restcatalogs.create`, `datalens.restcatalogs.list`, `datalens.sparkapplications`, `datalens.sparkapplications.cancel`, `datalens.sparkapplications.create`, `datalens.sparkapplications.get`, `datalens.sparkapplications.list`, `datalens.sparkapplications.log_list`, `datalens.sparkclusters`, `datalens.sparkclusters.create`, `datalens.sparkclusters.delete`, `datalens.sparkclusters.get`, `datalens.sparkclusters.list`, `datalens.sparkclusters.resource_presets_get`, `datalens.sparkclusters.resource_presets_list`, `datalens.sparkclusters.start`, `datalens.sparkclusters.stop`, `datalens.sqlqueries`, `datalens.sqlqueries.create`, `datalens.sqlqueries.delete`, `datalens.sqlqueries.get`, `datalens.sqlqueries.run`, `datalens.sqlqueries.update`, `datalens.tenant`, `datalens.tenant.details_get`, `datalens.trinoclusters`, `datalens.trinoclusters.catalog_create`, `datalens.trinoclusters.catalog_delete`, `datalens.trinoclusters.create`, `datalens.trinoclusters.delete`, `datalens.trinoclusters.get`, `datalens.trinoclusters.list`, `datalens.trinoclusters.resource_preset_get`, `datalens.trinoclusters.resource_presets_list`, `datalens.trinoclusters.start`, `datalens.trinoclusters.stop`, `tracker.linktypes`, `tracker.linktypes.list`, shown as plain text. See `CONTRIBUTING.md` for the intentional exclusions (UI-only endpoints with no public REST API) and per-method notes. ### Against the published API diff --git a/README.ru.md b/README.ru.md index aa41228bb..b0d71eada 100644 --- a/README.ru.md +++ b/README.ru.md @@ -131,9 +131,9 @@ YANDEX_ID_ORGANIZATION_ID=... # идентификатор вашей орг ## Покрытие API -Операций: 467, ресурсов: 88 +Операций: 468, ресурсов: 88 -Операций API Трекера, Вики, Форм и DataLens: **467** (Трекер — 190, Вики — 58, Формы — 85, DataLens — 134), ресурсов: **88**; все операции доступны из **Python SDK** и **CLI**. MCP-инструментов для агентов: **457**. Таблицы по ресурсам и операциям — в [английском README](README.md#coverage). +Операций API Трекера, Вики, Форм и DataLens: **468** (Трекер — 190, Вики — 58, Формы — 86, DataLens — 134), ресурсов: **88**; все операции доступны из **Python SDK** и **CLI**. MCP-инструментов для агентов: **458**. Таблицы по ресурсам и операциям — в [английском README](README.md#coverage). Из опубликованных Яндексом операций обёрнуто: Трекер — 188 из 190, Вики — 56 из 56, Формы — 84 из 84, DataLens — 134 из 143. Чего ycli пока не умеет (параметры запросов, поля ответов), перечислено в разделе [Against the published API](README.md#against-the-published-api); сверка повторяется каждую неделю. diff --git a/docs/assets/coverage.svg b/docs/assets/coverage.svg index ec23a5617..cfd779435 100644 --- a/docs/assets/coverage.svg +++ b/docs/assets/coverage.svg @@ -1,11 +1,11 @@ -ycli wraps 467 operations across 88 resources +ycli wraps 468 operations across 88 resources -467 +468 operations 88 resources -457 +458 MCP tools Tracker @@ -14,8 +14,8 @@ 58 operations · 56 MCP tools Forms - -85 operations · 78 MCP tools + +86 operations · 79 MCP tools DataLens 134 operations · 134 MCP tools diff --git a/docs/en/reference/cli/forms.md b/docs/en/reference/cli/forms.md index 6c4178d3d..3f63d8b60 100644 --- a/docs/en/reference/cli/forms.md +++ b/docs/en/reference/cli/forms.md @@ -1454,6 +1454,7 @@ $ ycli forms answers [OPTIONS] COMMAND [ARGS]... * `get`: Fetch one answer (GET /answers). * `list`: List a form's responses, filtered... +* `columns-list`: List the columns the cells of a response... * `export`: Export a form's answers (POST... * `integrations-list`: List the integration runs an answer... * `delete`: Delete an answer (DELETE... @@ -1487,6 +1488,10 @@ $ ycli forms answers get [OPTIONS] List a form's responses, filtered (auto-paginated; --all for everything). +The cells of a response stand in the order of `forms answers columns-list`, asked with +the same --questions and --use-slugs; `--answer-format raw` gives the data keyed by +question instead, which needs no columns. + **Usage**: ```console @@ -1501,6 +1506,7 @@ $ ycli forms answers list [OPTIONS] SURVEY_ID * `--limit INTEGER RANGE`: Max items to fetch (default: the configured cap). [x>=1] * `--all`: Fetch everything, ignoring the cap. +* `--next TOKEN`: Go on from where an earlier run stopped, with the token it printed: the token carries its listing; give what is required again, and nothing else but the limit. * `--questions TEXT`: Comma-separated question ids to return answers for. * `--use-slugs / --no-use-slugs`: Name questions and options by slug, not id. * `--date-from TEXT`: ISO-8601: answers given at or after. @@ -1516,6 +1522,32 @@ $ ycli forms answers list [OPTIONS] SURVEY_ID * `--body-file FILE`: A JSON object (YAML in a .yaml / .yml file) laid under the request body: -F and the command's flags win over it. Objects merge; a list is replaced, not added to. YAML guesses types (no, 1.10): quote a value meant as text. * `--help`: Show this message and exit. +### `ycli forms answers columns-list` + +List the columns the cells of a response stand in (reads one response to learn them). + +**Usage**: + +```console +$ ycli forms answers columns-list [OPTIONS] SURVEY_ID +``` + +**Arguments**: + +* `SURVEY_ID`: Form id, e.g. 6818ceffe010db4f59d11329. [required] + +**Options**: + +* `--questions TEXT`: Comma-separated question ids to return columns for. +* `--use-slugs / --no-use-slugs`: Name questions by slug, not id. +* `-o, --format [auto|json|yaml|pretty|csv|markdown|ndjson|name]`: Output format (auto = pretty on a TTY, JSON when piped). +* `-y, --yes`: Do not ask before an operation that deletes data. +* `--dry-run`: Do not send a write: print the request it would send instead. Reads still run, and only the first write of a command is shown. A secret in the body (a password, a token) is printed as ***. +* `--profile NAME`: Use the credentials saved as this profile (YCLI_PROFILE); the environment's and .env's are then not read. `ycli auth profiles` lists them. +* `-F, --field TEXT`: Set any field of the request body: key=value, key[sub]=value for a nested one (JSON-coerced; repeatable). key=@FILE (@- for stdin) gives the file's text as it is; a string that starts with @ goes in JSON quotes ('text="@ivan"'). A flag of the command wins over it. Objects merge; a list replaces the one below it. Give a secret from a file, not typed here: a command line stays in the shell history. Write that file with no line break at its end (printf %s 'secret' > file), or the break goes out with the secret. +* `--body-file FILE`: A JSON object (YAML in a .yaml / .yml file) laid under the request body: -F and the command's flags win over it. Objects merge; a list is replaced, not added to. YAML guesses types (no, 1.10): quote a value meant as text. +* `--help`: Show this message and exit. + ### `ycli forms answers export` Export a form's answers (POST /answers/export) — async; --wait downloads the file. diff --git a/docs/en/reference/mcp/forms.md b/docs/en/reference/mcp/forms.md index e95c5a67b..44a26799c 100644 --- a/docs/en/reference/mcp/forms.md +++ b/docs/en/reference/mcp/forms.md @@ -7,7 +7,7 @@ generated: true # Forms MCP tools -78 tools. +79 tools. ## `forms_me_get` @@ -588,10 +588,11 @@ item is a self-describing question record (``{id, label, type, value, …}``). *List Forms answers* · read-only -A form's responses, at most ``limit`` (drains pages via the next cursor). +A form's responses, across pages, at most ``limit``. -Returns the ``{columns, answers, next}`` envelope; ``next`` is always ``None`` -in the merged result. +The cells of a response (``data``) stand in the order of ``answers_columns_list``, asked +with the same ``questions`` and ``use_slugs``; ``answer_format="raw"`` gives the data +keyed by question instead. | Parameter | Type | Required | Description | |---|---|:---:|---| @@ -604,6 +605,20 @@ in the merged result. | `ordering` | `asc` · `desc` or string or null | | ``asc`` is oldest first; the default is ``desc``. | | `page_size` | integer or null | | Answers per request (the API's default is 25). | | `answer_format` | `default` · `raw` or string or null | | ``default`` (cells aligned to ``columns``) or ``raw`` (each answer's data as stored, with no ``columns``). | +| `all` | boolean | | Return everything, ignoring the cap. A long listing is better taken in pieces: `limit`, then `next`. | +| `next` | string or null | | Go on from where an earlier call stopped, with the `next` it returned: the token carries its listing; give what is required again, and nothing else but the limit. | + +## `forms_answers_columns_list` + +*List Forms answer columns* · read-only + +The columns the cells of a response stand in; one response is read to learn them. + +| Parameter | Type | Required | Description | +|---|---|:---:|---| +| `survey_id` | string | yes | Form id (24-char hex), from ``surveys_list``. | +| `questions` | string or null | | Comma-separated question ids to return columns for. | +| `use_slugs` | boolean or null | | Name questions by slug instead of id. | ## `forms_answers_export` diff --git a/docs/examples/services/cards.en.md b/docs/examples/services/cards.en.md index 8ba34e684..29379419e 100644 --- a/docs/examples/services/cards.en.md +++ b/docs/examples/services/cards.en.md @@ -20,7 +20,7 @@ Surveys, questions, answers, publishing. - `85 operations` + `86 operations` CLI · MCP · Python diff --git a/docs/examples/services/cards.ru.md b/docs/examples/services/cards.ru.md index 30c8d859f..85e1cb190 100644 --- a/docs/examples/services/cards.ru.md +++ b/docs/examples/services/cards.ru.md @@ -20,7 +20,7 @@ Опросы, вопросы, ответы, публикация. - `операций: 85` + `операций: 86` CLI · MCP · Python diff --git a/docs/examples/services/comparison.operations.en.md b/docs/examples/services/comparison.operations.en.md index c99ae94e3..e9caaf1c7 100644 --- a/docs/examples/services/comparison.operations.en.md +++ b/docs/examples/services/comparison.operations.en.md @@ -1 +1 @@ -A tool count is not an operation count: one tool can cover several API operations, and one operation can be split across tools. ycli wraps 467 operations of the four APIs, and each is also a command and a Python method. +A tool count is not an operation count: one tool can cover several API operations, and one operation can be split across tools. ycli wraps 468 operations of the four APIs, and each is also a command and a Python method. diff --git a/docs/examples/services/comparison.operations.ru.md b/docs/examples/services/comparison.operations.ru.md index a30d70e1f..27c7a3870 100644 --- a/docs/examples/services/comparison.operations.ru.md +++ b/docs/examples/services/comparison.operations.ru.md @@ -1 +1 @@ -Число инструментов — не число операций: один инструмент может покрывать несколько операций API, а одна операция — делиться между инструментами. ycli оборачивает 467 операций четырёх API, и каждая из них — ещё и команда, и метод Python. +Число инструментов — не число операций: один инструмент может покрывать несколько операций API, а одна операция — делиться между инструментами. ycli оборачивает 468 операций четырёх API, и каждая из них — ещё и команда, и метод Python. diff --git a/docs/examples/services/comparison.row.en.md b/docs/examples/services/comparison.row.en.md index ef931f36b..42f22ae5a 100644 --- a/docs/examples/services/comparison.row.en.md +++ b/docs/examples/services/comparison.row.en.md @@ -1 +1 @@ -| ycli | Tracker, Wiki, Forms, DataLens | 457: Tracker 187, Wiki 56, Forms 78, DataLens 134, and `schema_get`, `status_get` | yes | `ycli mcp start --read-only` | all | \ No newline at end of file +| ycli | Tracker, Wiki, Forms, DataLens | 458: Tracker 187, Wiki 56, Forms 79, DataLens 134, and `schema_get`, `status_get` | yes | `ycli mcp start --read-only` | all | \ No newline at end of file diff --git a/docs/examples/services/comparison.row.ru.md b/docs/examples/services/comparison.row.ru.md index 2fbd1b85d..76bd8f3ed 100644 --- a/docs/examples/services/comparison.row.ru.md +++ b/docs/examples/services/comparison.row.ru.md @@ -1 +1 @@ -| ycli | Трекер, Вики, Формы, DataLens | 457: Трекер 187, Вики 56, Формы 78, DataLens 134 и `schema_get`, `status_get` | да | `ycli mcp start --read-only` | все | \ No newline at end of file +| ycli | Трекер, Вики, Формы, DataLens | 458: Трекер 187, Вики 56, Формы 79, DataLens 134 и `schema_get`, `status_get` | да | `ycli mcp start --read-only` | все | \ No newline at end of file diff --git a/docs/examples/services/forms.header.en.md b/docs/examples/services/forms.header.en.md index 9fe1409f7..19891755b 100644 --- a/docs/examples/services/forms.header.en.md +++ b/docs/examples/services/forms.header.en.md @@ -2,4 +2,4 @@ Surveys, questions, answers, publishing. -`85 operations` · CLI · MCP · Python +`86 operations` · CLI · MCP · Python diff --git a/docs/examples/services/forms.header.ru.md b/docs/examples/services/forms.header.ru.md index 8e650f33a..a8f45cb33 100644 --- a/docs/examples/services/forms.header.ru.md +++ b/docs/examples/services/forms.header.ru.md @@ -2,4 +2,4 @@ Опросы, вопросы, ответы, публикация. -`операций: 85` · CLI · MCP · Python +`операций: 86` · CLI · MCP · Python diff --git a/e2e/scenarios/forms/survey_options.yaml b/e2e/scenarios/forms/survey_options.yaml index b0d0cdbbc..6cedbd76a 100644 --- a/e2e/scenarios/forms/survey_options.yaml +++ b/e2e/scenarios/forms/survey_options.yaml @@ -50,12 +50,16 @@ steps: - id: answers run: forms answers list ${id} --ordering asc --page-size 1 --use-slugs --date-from 2020-01-01T00:00:00Z --date-to 2099-01-01T00:00:00Z --all expect: - "length(answers)": 0 + "length(items)": 0 - id: answers-raw run: forms answers list ${id} --answer-format raw --all expect: - "length(answers)": 0 - "length(columns)": 0 + "length(items)": 0 + # A form nobody answered: the columns are read all the same. + - id: answer-columns + run: forms answers columns-list ${id} --use-slugs + expect: + "type(@)": array - id: me run: forms me get expect: diff --git a/plugins/yandex-360/skills/yandex-360-forms/SKILL.md b/plugins/yandex-360/skills/yandex-360-forms/SKILL.md index 4ed1f63fb..6a03b5230 100644 --- a/plugins/yandex-360/skills/yandex-360-forms/SKILL.md +++ b/plugins/yandex-360/skills/yandex-360-forms/SKILL.md @@ -59,6 +59,7 @@ The OAuth token needs `forms:read` / `forms:write` scopes (see the auth section | List questions (schema) | `uv run ycli forms questions list ` | `forms_questions_list` | | Get one question | `uv run ycli forms questions get ` | `forms_questions_get` | | List answers (responses) | `uv run ycli forms answers list [--all]` | `forms_answers_list` | +| The columns the cells of an answer stand in | `uv run ycli forms answers columns-list ` | `forms_answers_columns_list` | | Fillable form view (option ids!) | `uv run ycli forms filling get ` | `forms_filling_get` | | Suggest values for a question | `uv run ycli forms filling suggest --question --text …` | `forms_filling_suggest` | | Keysets | `uv run ycli forms keysets list\|get …` | `forms_keysets_list` / `forms_keysets_get` | @@ -78,7 +79,7 @@ forms.me.get() # auth probe forms.surveys.list() # list forms forms.surveys.get("") # form settings forms.questions.list("") # schema -forms.answers.list("") # responses +forms.answers.list("") # responses; forms.answers.columns_list("") names their cells ``` --- diff --git a/src/ycli/yandex/forms/answers/cli.py b/src/ycli/yandex/forms/answers/cli.py index 6015e49b7..c639fbd79 100644 --- a/src/ycli/yandex/forms/answers/cli.py +++ b/src/ycli/yandex/forms/answers/cli.py @@ -6,14 +6,16 @@ from ycli.cli.output import BinaryResult from ycli.cli.progress import wait_for -from ycli.cli.typedefs import AllOption, LimitOption, values_option +from ycli.cli.typedefs import AllOption, LimitOption, NextOption, values_option from ycli.settings import AppConfig +from ycli.yandex.core.listing import Listing from ycli.yandex.forms.answers.models import ( + Answer, AnswerDetails, AnswerExport, AnswerFormat, AnswerIntegration, - AnswersResponse, + Column, ExportFormat, ExportUpload, ) @@ -50,6 +52,7 @@ def list_( survey_id: SurveyIDArg, limit: LimitOption = None, all_: AllOption = False, + next_: NextOption = None, questions: Annotated[ str | None, typer.Option(help="Comma-separated question ids to return answers for.") ] = None, @@ -80,12 +83,18 @@ def list_( *, config: AppConfig, forms: FormsClient, -) -> AnswersResponse: - """List a form's responses, filtered (auto-paginated; --all for everything).""" +) -> Listing[Answer]: + """List a form's responses, filtered (auto-paginated; --all for everything). + + The cells of a response stand in the order of `forms answers columns-list`, asked with + the same --questions and --use-slugs; `--answer-format raw` gives the data keyed by + question instead, which needs no columns. + """ cap = config.http.cap(limit, all_=all_) return forms.answers.list( survey_id, limit=cap, + next=next_, questions=questions, use_slugs=use_slugs, date_from=date_from, @@ -96,6 +105,23 @@ def list_( ) +@app.command() +def columns_list( + survey_id: SurveyIDArg, + questions: Annotated[ + str | None, typer.Option(help="Comma-separated question ids to return columns for.") + ] = None, + use_slugs: Annotated[ + bool | None, + typer.Option("--use-slugs/--no-use-slugs", help="Name questions by slug, not id."), + ] = None, + *, + forms: FormsClient, +) -> ItemList[Column]: + """List the columns the cells of a response stand in (reads one response to learn them).""" + return forms.answers.columns_list(survey_id, questions=questions, use_slugs=use_slugs) + + def _finish_export( forms: FormsClient, config: AppConfig, diff --git a/src/ycli/yandex/forms/answers/client.py b/src/ycli/yandex/forms/answers/client.py index 187cfc9d6..8f07077eb 100644 --- a/src/ycli/yandex/forms/answers/client.py +++ b/src/ycli/yandex/forms/answers/client.py @@ -2,21 +2,20 @@ from __future__ import annotations -from dataclasses import replace from typing import TYPE_CHECKING from ycli.yandex.core.resource import Resource from ycli.yandex.forms.answers import endpoints -from ycli.yandex.forms.answers.models import ( - Answer, - AnswerDetails, - AnswerExport, - AnswerIntegration, - AnswersResponse, - Column, -) if TYPE_CHECKING: + from ycli.yandex.core.listing import Listing + from ycli.yandex.forms.answers.models import ( + Answer, + AnswerDetails, + AnswerExport, + AnswerIntegration, + Column, + ) from ycli.yandex.forms.models import OperationResult from ycli.yandex.models import ItemList @@ -48,6 +47,7 @@ def list( survey_id: str, *, limit: int | None = None, + next: str | None = None, questions: str | None = None, use_slugs: bool | None = None, date_from: str | None = None, @@ -55,30 +55,33 @@ def list( ordering: str | None = None, page_size: int | None = None, answer_format: str | None = None, - ) -> AnswersResponse: - """Every answer across pages, at most ``limit`` (``None`` = all). + ) -> Listing[Answer]: + """``GET /surveys/{id}/answers`` → the form's answers, page by page, at most ``limit``. - ``columns`` come from the first page (identical across pages); the merged ``next`` is - ``None``. + The cells of an answer (``data``) stand in the order of :meth:`columns_list`, asked + with the same ``questions`` and ``use_slugs``; ``answer_format="raw"`` gives each + answer's data keyed by question instead, which needs no columns. Args: survey_id: The form's id. limit: The most answers to return; ``None`` returns every answer. + next: What an earlier call returned as ``next``. The token carries its listing; + give what is required again, and nothing else but the limit. questions: The comma-separated question ids to return answers for. use_slugs: Name questions and options by slug instead of id. date_from: ISO-8601 start of the period the answers were given in. date_to: ISO-8601 end of that period. ordering: ``asc`` (oldest first) or ``desc`` (the API's default). page_size: The most answers a page holds (the API's default is 25). - answer_format: ``default`` (cells aligned to ``columns``) or ``raw`` (each answer's - data as the API stores it, with no ``columns``). + answer_format: ``default`` (cells in the order of the columns) or ``raw`` (each + answer's data as the API stores it). Returns: - The answers of every page, with the first page's columns. + The form's answers. Examples: - >>> len(forms.answers.list("686d0a1b2c3d4e5f00000030", limit=500).answers) - 2 + >>> [answer.id for answer in forms.answers.list("686d0a1b2c3d4e5f00000030", limit=500)] + [2, 1] """ paged = endpoints.list_( survey_id, @@ -90,15 +93,31 @@ def list( page_size=page_size, answer_format=answer_format, ) - columns: list[Column] = [] + return self._session.iterate(paged, limit=limit, next=next) - def items_of(page: AnswersResponse) -> list[Answer]: - if not columns: - columns.extend(page.columns) - return page.answers + def columns_list( + self, survey_id: str, *, questions: str | None = None, use_slugs: bool | None = None + ) -> ItemList[Column]: + """``GET /surveys/{id}/answers`` → the columns the cells of an answer stand in. - answers = list(self._session.iterate(replace(paged, items_of=items_of), limit=limit)) - return AnswersResponse(columns=columns, answers=answers, next=None) + The API has no request for the columns alone: one answer is read to learn them, and + left out. A form nobody answered yet has its columns all the same. + + Args: + survey_id: The form's id. + questions: The comma-separated question ids to return columns for. + use_slugs: Name questions by slug instead of id. + + Returns: + The columns, in the order of the cells of :meth:`list` asked the same way. + + Examples: + >>> forms.answers.columns_list("686d0a1b2c3d4e5f00000037").root[0].text + 'Name' + """ + return self._session.send( + endpoints.columns_list(survey_id, questions=questions, use_slugs=use_slugs) + ) def export(self, survey_id: str, body: AnswerExport) -> OperationResult: """``POST /surveys/{id}/answers/export`` — start an export → ``202`` with its operation. diff --git a/src/ycli/yandex/forms/answers/endpoints.py b/src/ycli/yandex/forms/answers/endpoints.py index 60bd819b9..bf6b7a0ba 100644 --- a/src/ycli/yandex/forms/answers/endpoints.py +++ b/src/ycli/yandex/forms/answers/endpoints.py @@ -20,6 +20,7 @@ AnswerExport, AnswerIntegration, AnswersResponse, + Column, ) from ycli.yandex.forms.models import OperationResult from ycli.yandex.models import ItemList @@ -73,6 +74,22 @@ def list_( ) +def _columns(response: httpx2.Response) -> ItemList[Column]: + return ItemList[Column](AnswersResponse.model_validate(response.json()).columns) + + +def columns_list( + survey_id: str, *, questions: str | None, use_slugs: bool | None +) -> Endpoint[ItemList[Column]]: + """``GET /surveys/{id}/answers`` for its ``columns``: the API has no request for them alone. + + One answer is asked for, the least a page holds, and left out of the result. + """ + params = {"questions": questions, "use_slugs": use_slugs, "page_size": 1} + path = f"surveys/{segment(survey_id)}/answers" + return Endpoint(HTTPMethod.GET, path, params=params, parser=_columns) + + def export(survey_id: str, body: AnswerExport) -> Endpoint[OperationResult]: return Endpoint( HTTPMethod.POST, f"surveys/{segment(survey_id)}/answers/export", OperationResult, json=body diff --git a/src/ycli/yandex/forms/answers/mcp.py b/src/ycli/yandex/forms/answers/mcp.py index 17ffc86ce..ce0ce7f3c 100644 --- a/src/ycli/yandex/forms/answers/mcp.py +++ b/src/ycli/yandex/forms/answers/mcp.py @@ -12,11 +12,12 @@ from ycli.settings import AppConfig from ycli.yandex.forms.answers.models import ( + Answer, AnswerDetails, AnswerExport, AnswerFormat, AnswerIntegration, - AnswersResponse, + Column, ) from ycli.yandex.forms.client import FormsClient from ycli.yandex.forms.dependencies import ( @@ -24,13 +25,15 @@ LIMIT_CAP, RO, WRITE, + All, + Next, SurveyID, app_config, forms_client, new_server, ) from ycli.yandex.forms.models import OperationResult -from ycli.yandex.models import Ack, ItemList, SortDirection +from ycli.yandex.models import Ack, ItemList, Listed, SortDirection mcp = new_server("forms-answers") @@ -87,17 +90,22 @@ def list_( "data as stored, with no ``columns``)." ), ] = None, + all: All = False, + next: Next = None, client: FormsClient = Depends(forms_client), config: AppConfig = Depends(app_config), -) -> AnswersResponse: - """A form's responses, at most ``limit`` (drains pages via the next cursor). +) -> Listed[Answer]: + """A form's responses, across pages, at most ``limit``. - Returns the ``{columns, answers, next}`` envelope; ``next`` is always ``None`` - in the merged result. + The cells of a response (``data``) stand in the order of ``answers_columns_list``, asked + with the same ``questions`` and ``use_slugs``; ``answer_format="raw"`` gives the data + keyed by question instead. """ + cap = config.http.tool_cap(limit, all_=all) return client.answers.list( survey_id, - limit=config.http.tool_cap(limit), + limit=cap, + next=next, questions=questions, use_slugs=use_slugs, date_from=date_from, @@ -105,7 +113,22 @@ def list_( ordering=ordering, page_size=page_size, answer_format=answer_format, - ) + ).collect() + + +@mcp.tool(name="answers_columns_list", annotations={**RO, "title": "List Forms answer columns"}) +def columns_list( + survey_id: SurveyID, + questions: Annotated[ + str | None, Field(description="Comma-separated question ids to return columns for.") + ] = None, + use_slugs: Annotated[ + bool | None, Field(description="Name questions by slug instead of id.") + ] = None, + client: FormsClient = Depends(forms_client), +) -> ItemList[Column]: + """The columns the cells of a response stand in; one response is read to learn them.""" + return client.answers.columns_list(survey_id, questions=questions, use_slugs=use_slugs) @mcp.tool(name="answers_export", annotations={**WRITE, "title": "Export Forms answers"}) diff --git a/src/ycli/yandex/forms/answers/models.py b/src/ycli/yandex/forms/answers/models.py index 0db0ae8c1..8f70c276a 100644 --- a/src/ycli/yandex/forms/answers/models.py +++ b/src/ycli/yandex/forms/answers/models.py @@ -24,7 +24,7 @@ class Column(APIModel): 'T' """ - id: int | None = Field(default=None, description="Id of the column.") + id: Annotated[int | None, Identity()] = Field(default=None, description="Id of the column.") slug: str | None = Field(default=None, description="Slug of the column.") type: str | None = Field(default=None, description="Question type of the column.") text: str | None = Field(default=None, description="Heading of the column, the question text.") @@ -44,7 +44,7 @@ class Answer(APIModel): [{'value': 'x'}] """ - id: int | None = Field(default=None, description="Id of the answer.") + id: Annotated[int | None, Identity()] = Field(default=None, description="Id of the answer.") created: str | None = Field( default=None, description="When the answer was submitted (ISO 8601)." ) diff --git a/tests/architecture/test_arch1.py b/tests/architecture/test_arch1.py index 4b81432dc..26d9ff1cb 100644 --- a/tests/architecture/test_arch1.py +++ b/tests/architecture/test_arch1.py @@ -964,8 +964,6 @@ def test_arch1_argument_check_bites(): # the pages of a listing takes `next` (#502), and so do its command and its tool: the check of # arguments above holds the surfaces to the method. ARCH1_LISTINGS_WITHOUT_NEXT = { - "forms.answers.list": "returns the columns with the answers, which a listing has no place " - "for; its own answer is with the owner", "wiki.comments.thread_list": "rebuilds one thread from every comment of the page: there is " "no page of the service to go on from", } diff --git a/tests/snapshots/cli_signatures.txt b/tests/snapshots/cli_signatures.txt index 99e573698..3648e70fa 100644 --- a/tests/snapshots/cli_signatures.txt +++ b/tests/snapshots/cli_signatures.txt @@ -142,11 +142,12 @@ forms access grant: --action:TEXT! --body-file:FILE --cloud-uid:TEXT --dry-run:B forms access list: --body-file:FILE --dry-run:BOOLEAN=False --field:TEXT --format:CHOICE --profile:TEXT --yes:BOOLEAN=False SURVEY_ID:TEXT! forms access revoke: --action:TEXT! --body-file:FILE --cloud-uid:TEXT --dry-run:BOOLEAN=False --field:TEXT --format:CHOICE --group-id:TEXT --group-src:TEXT --profile:TEXT --uid:TEXT --yes:BOOLEAN=False SURVEY_ID:TEXT! forms access update: --access:TEXT! --action:TEXT! --body-file:FILE --dry-run:BOOLEAN=False --field:TEXT --format:CHOICE --profile:TEXT --yes:BOOLEAN=False SURVEY_ID:TEXT! +forms answers columns-list: --body-file:FILE --dry-run:BOOLEAN=False --field:TEXT --format:CHOICE --profile:TEXT --questions:TEXT --use-slugs:BOOLEAN --yes:BOOLEAN=False SURVEY_ID:TEXT! forms answers delete: --body-file:FILE --dry-run:BOOLEAN=False --field:TEXT --format:CHOICE --profile:TEXT --yes:BOOLEAN=False ANSWER_ID:INTEGER! SURVEY_ID:TEXT! forms answers export: --body-file:FILE --column:TEXT --dry-run:BOOLEAN=False --field:TEXT --finished-at:TEXT --format:TEXT --limit:INTEGER --output:TEXT --pk:INTEGER --profile:TEXT --started-at:TEXT --upload-files:BOOLEAN --upload:TEXT --wait:BOOLEAN=True --yes:BOOLEAN=False SURVEY_ID:TEXT! forms answers get: --answer-id:INTEGER --answer-key:TEXT --body-file:FILE --dry-run:BOOLEAN=False --field:TEXT --format:CHOICE --profile:TEXT --yes:BOOLEAN=False forms answers integrations-list: --answer-id:INTEGER --answer-key:TEXT --body-file:FILE --dry-run:BOOLEAN=False --field:TEXT --format:CHOICE --profile:TEXT --yes:BOOLEAN=False -forms answers list: --all:BOOLEAN=False --answer-format:TEXT --body-file:FILE --date-from:TEXT --date-to:TEXT --dry-run:BOOLEAN=False --field:TEXT --format:CHOICE --limit:INTEGER RANGE --ordering:TEXT --page-size:INTEGER --profile:TEXT --questions:TEXT --use-slugs:BOOLEAN --yes:BOOLEAN=False SURVEY_ID:TEXT! +forms answers list: --all:BOOLEAN=False --answer-format:TEXT --body-file:FILE --date-from:TEXT --date-to:TEXT --dry-run:BOOLEAN=False --field:TEXT --format:CHOICE --limit:INTEGER RANGE --next:TEXT --ordering:TEXT --page-size:INTEGER --profile:TEXT --questions:TEXT --use-slugs:BOOLEAN --yes:BOOLEAN=False SURVEY_ID:TEXT! forms answers restore: --body-file:FILE --dry-run:BOOLEAN=False --field:TEXT --format:CHOICE --profile:TEXT --yes:BOOLEAN=False ANSWER_ID:INTEGER! SURVEY_ID:TEXT! forms auth status: --body-file:FILE --dry-run:BOOLEAN=False --field:TEXT --format:CHOICE --profile:TEXT --yes:BOOLEAN=False forms conditions hook create: --body-file:FILE --dry-run:BOOLEAN=False --field:TEXT --format:CHOICE --item:TEXT --operator:TEXT --profile:TEXT --yes:BOOLEAN=False HOOK_ID:INTEGER! SURVEY_ID:TEXT! diff --git a/tests/snapshots/mcp_output_schemas.txt b/tests/snapshots/mcp_output_schemas.txt index 980aa7a76..4f13475cf 100644 --- a/tests/snapshots/mcp_output_schemas.txt +++ b/tests/snapshots/mcp_output_schemas.txt @@ -136,11 +136,12 @@ forms_access_grant f3b96b4ea415f565 forms_access_list f3b96b4ea415f565 forms_access_revoke f3b96b4ea415f565 forms_access_update f3b96b4ea415f565 +forms_answers_columns_list acef33813751203e forms_answers_delete 5037df4f3953d287 forms_answers_export 960968a8ff927610 forms_answers_get 018c88b46dc62547 forms_answers_integrations_list f5e22d8a55fb109f -forms_answers_list 3e369efca3a90379 +forms_answers_list 48e7d1be7dc8c061 forms_answers_restore 5037df4f3953d287 forms_conditions_hook_create f041d92f27feb05a forms_conditions_hook_delete 5037df4f3953d287 diff --git a/tests/snapshots/mcp_signatures.txt b/tests/snapshots/mcp_signatures.txt index 8b67faca8..9638eae5d 100644 --- a/tests/snapshots/mcp_signatures.txt +++ b/tests/snapshots/mcp_signatures.txt @@ -136,11 +136,12 @@ forms_access_grant(body:object!, survey_id:string!) forms_access_list(survey_id:string!) forms_access_revoke(body:object!, survey_id:string!) forms_access_update(body:object!, survey_id:string!) +forms_answers_columns_list(questions:string|null=None, survey_id:string!, use_slugs:boolean|null=None) forms_answers_delete(answer_id:integer!, survey_id:string!) forms_answers_export(body:object!, survey_id:string!) forms_answers_get(answer_id:integer|null=None, answer_key:string|null=None) forms_answers_integrations_list(answer_id:integer|null=None, answer_key:string|null=None) -forms_answers_list(answer_format:string|string|null=None, date_from:string|null=None, date_to:string|null=None, limit:integer|null=None, ordering:string|string|null=None, page_size:integer|null=None, questions:string|null=None, survey_id:string!, use_slugs:boolean|null=None) +forms_answers_list(all:boolean=False, answer_format:string|string|null=None, date_from:string|null=None, date_to:string|null=None, limit:integer|null=None, next:string|null=None, ordering:string|string|null=None, page_size:integer|null=None, questions:string|null=None, survey_id:string!, use_slugs:boolean|null=None) forms_answers_restore(answer_id:integer!, survey_id:string!) forms_conditions_hook_create(body:object!, hook_id:integer!, survey_id:string!) forms_conditions_hook_delete(condition_id:integer!, hook_id:integer!, survey_id:string!) diff --git a/tests/unit/yandex/forms/answers/cases.py b/tests/unit/yandex/forms/answers/cases.py index da7c9b858..d82401769 100644 --- a/tests/unit/yandex/forms/answers/cases.py +++ b/tests/unit/yandex/forms/answers/cases.py @@ -49,6 +49,15 @@ {"id": 5, "status": "canceled", "type": "function", "function_id": "d4e0abc"}, ] +COLUMNS_OF = "686d0a1b2c3d4e5f00000037" +COLUMN = { + "id": 17, + "slug": "answer_short_text_1", + "type": "string", + "text": "Name", + "has_scores": False, +} +COLUMNS_PAGE = {"columns": [COLUMN], "answers": [{"id": 1, "data": [{"value": "Ann"}]}]} FILTERED = "686d0a1b2c3d4e5f00000036" FILTERS = { "questions": "17,18", @@ -94,23 +103,10 @@ (Sent("GET", f"surveys/{SID}/answers"), Reply(json=FIRST_PAGE)), (Sent("GET", f"surveys/{SID}/answers", {"id": "2"}), Reply(json=PAGE)), ], - output={ - "columns": [ - { - "id": None, - "slug": "answer_short_text_1", - "type": None, - "text": None, - "has_scores": None, - "label": "Name", - } - ], - "answers": [ - {"id": 2, "created": None, "uid": None, "data": ["Bob"]}, - {"id": 1, "created": None, "uid": None, "data": ["Ann"]}, - ], - "next": None, - }, + output=[ + {"id": 2, "created": None, "uid": None, "data": ["Bob"]}, + {"id": 1, "created": None, "uid": None, "data": ["Ann"]}, + ], ), # A limit below the page keeps only that many answers (MCP always uses the configured cap). Case( @@ -125,20 +121,7 @@ Reply(json={**PAGE, "answers": [{"id": 1}, {"id": 2}]}), ) ], - output={ - "columns": [ - { - "id": None, - "slug": "answer_short_text_1", - "type": None, - "text": None, - "has_scores": None, - "label": "Name", - } - ], - "answers": [{"id": 1, "created": None, "uid": None, "data": []}], - "next": None, - }, + output=[{"id": 1, "created": None, "uid": None, "data": []}], ), Case( "forms.answers.list", @@ -153,23 +136,49 @@ ) ], env={"YCLI__HTTP__MAX_ITEMS": "1"}, - output={ - "columns": [ - { - "id": None, - "slug": "answer_short_text_1", - "type": None, - "text": None, - "has_scores": None, - "label": "Name", - } - ], - "answers": [ - {"id": 7, "created": None, "uid": None, "data": []}, - {"id": 8, "created": None, "uid": None, "data": []}, - ], - "next": None, - }, + output=[ + {"id": 7, "created": None, "uid": None, "data": []}, + {"id": 8, "created": None, "uid": None, "data": []}, + ], + ), + # The columns alone: one answer is asked for and left out of what is returned. + Case( + "forms.answers.columns_list", + args=(COLUMNS_OF,), + cli=["forms", "answers", "columns-list", COLUMNS_OF], + mcp=("forms_answers_columns_list", {"survey_id": COLUMNS_OF}), + exchanges=[ + ( + Sent("GET", f"surveys/{COLUMNS_OF}/answers", {"page_size": "1"}), + Reply(json=COLUMNS_PAGE), + ) + ], + output=[COLUMN], + ), + # A form nobody answered has its columns all the same; the two options go as given. + Case( + "forms.answers.columns_list", + args=(COLUMNS_OF,), + kwargs={"questions": "17,18", "use_slugs": True}, + cli=[ + *("forms", "answers", "columns-list", COLUMNS_OF), + *("--questions", "17,18", "--use-slugs"), + ], + mcp=( + "forms_answers_columns_list", + {"survey_id": COLUMNS_OF, "questions": "17,18", "use_slugs": True}, + ), + exchanges=[ + ( + Sent( + "GET", + f"surveys/{COLUMNS_OF}/answers", + {"questions": "17,18", "use_slugs": "true", "page_size": "1"}, + ), + Reply(json={**COLUMNS_PAGE, "answers": []}), + ) + ], + output=[COLUMN], ), Case( "forms.answers.export", @@ -318,13 +327,9 @@ Reply(json={"answers": [{"id": 32, "uid": "9105", "data": {"name": "Bob"}}]}), ), ], - output={ - "columns": [], - "answers": [ - {"id": 31, "created": None, "uid": "9104", "data": {"name": "Ann"}}, - {"id": 32, "created": None, "uid": "9105", "data": {"name": "Bob"}}, - ], - "next": None, - }, + output=[ + {"id": 31, "created": None, "uid": "9104", "data": {"name": "Ann"}}, + {"id": 32, "created": None, "uid": "9105", "data": {"name": "Bob"}}, + ], ), ] diff --git a/tests/unit/yandex/forms/answers/test_client.py b/tests/unit/yandex/forms/answers/test_client.py index 442785b62..54fcff745 100644 --- a/tests/unit/yandex/forms/answers/test_client.py +++ b/tests/unit/yandex/forms/answers/test_client.py @@ -39,9 +39,8 @@ def test_list_all_carries_the_dead_v3_cursor_onto_v1(api): ) api.add("GET", ANSWERS, json={"columns": [{"slug": "ignored"}], "answers": [{"id": 2}]}) with FormsClient(oauth_token="t", organization_id="o") as client: - result = client.answers.list(SID) - assert [answer.id for answer in result.answers] == [1, 2] - assert [column.slug for column in result.columns] == ["q1"] + result = list(client.answers.list(SID)) + assert [answer.id for answer in result] == [1, 2] assert str(api.calls[1].url) == f"{ANSWERS}?id=100" @@ -66,4 +65,21 @@ async def test_the_tool_stops_at_its_limit(api): api.add("GET", f"{BASE}/surveys/s1/answers", json={"answers": answers, "columns": []}) async with Client(mcp) as client: result = await client.call_tool("forms_answers_list", {"survey_id": "s1", "limit": 2}) - assert [answer["id"] for answer in result.structured_content["answers"]] == [1, 2] + assert [answer["id"] for answer in result.structured_content["items"]] == [1, 2] + + +def test_the_cells_of_an_answer_stand_in_the_order_of_the_columns_asked_the_same_way(api): + """What the help of ``list`` says: as many cells as ``columns-list`` gives columns.""" + page = { + "columns": [{"id": 17, "slug": "name"}, {"id": 18, "slug": "city"}], + "answers": [{"id": 1, "data": [{"value": "Ann"}, None]}], + } + api.add("GET", ANSWERS, json=page) + api.add("GET", ANSWERS, json=page) + with FormsClient(oauth_token="t", organization_id="o") as client: + columns = client.answers.columns_list(SID, questions="17,18", use_slugs=True) + (answer,) = client.answers.list(SID, questions="17,18", use_slugs=True) + assert len(answer.data) == len(columns.root) == 2 + asked = [dict(call.url.params) for call in api.calls] + assert asked[0] == {"questions": "17,18", "use_slugs": "true", "page_size": "1"} + assert asked[1] == {"questions": "17,18", "use_slugs": "true"}