Skip to content

feat(cli): -o name prints the identifier of each object, what the command that reads it takes - #569

Merged
bim-ba merged 1 commit into
mainfrom
feat/output-name
Oct 10, 2026
Merged

bim-ba merged 1 commit into
mainfrom
feat/output-name

Conversation

@bim-ba

@bim-ba bim-ba commented Oct 10, 2026

Copy link
Copy Markdown
Owner

Second of the two output-format PRs decided in #561 (and #498); the first was #568.

What it does

  • -o name prints the identifier of each object on a line: the field the command that reads it takes. ycli tracker issues search 'Queue: TEST' -o name | xargs -n1 ycli tracker issues get works, and issues create … -o name gives the key of what was made.
  • A reply model marks that one field with Identity() (Р1-А: the same mark, no second one; it stays in ycli/yandex/sync/marks.py, and lint-imports keeps all 6 contracts).
  • An object inside another one prints its own identifier (Р2-А).
  • A command whose result has no such field is refused before it sends anything, exit code 2 (Р2-Г).
  • A reply that leaves the identifier of an item out is an error (YandexUnexpectedReplyError, exit code 1) and nothing is printed, so a script never acts on fewer objects than were listed.
  • With --dry-run the plan comes back in place of the object and is printed as JSON. An item that is not an object (a tag) is its own name.

Coverage

Print names Refused
Listing commands (105) 71 34
Commands that answer with one object (378) 165 213

The 34 are every DataLens listing (27 generated item classes behind one reason) and five classes with no identifier of their own, each with its reason in NO_NAME of tests/architecture/test_names.py. The 213 are acknowledgements, counts, operation statuses, permissions — and the DataLens single objects, which the next PR names.

DataLens is not in this PR. Its models are generated from the specification and are not edited by hand. The next PR lets each DataLens resource name the API key of its identifier where the generator reads it; the test here fails the day no generated model is left unnamed, so the reason cannot outlive its cause.

Checks added

  • tests/architecture/test_names.py: the item class of every listing has exactly one Identity() field or a stated reason, checked both ways, with a biting case; and every create / get / update of a resource whose listing prints names prints one too (holds with no exception).
  • tests/contract/test_output_formats.py: every contract case that has a command (723) under -o name prints one non-empty line per item that is a value of that item, or exits 2 with the refusal while the mock saw no request. Seven operations have a case whose reply leaves the identifier out; they are named in the test and assert the error, both ways. Their replies are unchanged.
  • tests/unit/cli/test_inject.py: -o name is recognised as the text typer holds before the command runs.

A defect the bite pass found, and its evidence

In an earlier commit of this branch the refusal never fired when --format name stood before the command: the code compared the choice with is, and typer holds it as text there. The per-case test was green anyway, because its "text, a count, bytes print the same in every format" escape accepted any output equal to -o json. Both are fixed. Measured both ways on the per-case test: intact → 724 passed; refusal disabled → 312 failed, 411 passed. The unit test above fails with is and passes with ==.

Other checks seen failing on their defect, then restored: a listing item losing its mark (the architecture test failed); an unnamed item printing an empty line (the sparse-operations test and the unit test failed).

Checked

  • uv run pytest: 6951 passed, 5 skipped, coverage 100% (lines and branches); lint-imports, ty, ruff clean. That run was on the tree before the last edit, which added an Args: section to one docstring; after it the CLI unit tests, the architecture test, the contract format tests and the doctests of output.py were rerun (1893 passed) and the pre-commit hooks passed.

Not run

  • No live service: -o name | xargs … get was not tried against Tracker, Wiki or Forms.
  • The e2e scenarios.

The marked fields

82 fields in 54 files, put there by a one-off codemod (not in the repository). The field is what the resource's read command takes; where a resource has get and get-by-id, plain get decides.

Class Field Decided by
forms.answers.models.AnswerDetails id no get to decide: key, else slug, else id
forms.answers.models.AnswerIntegration id no get to decide: key, else slug, else id
forms.filling.models.FillableForm id the get argument
forms.filling.models.SubmitResult id the get argument
forms.filling.models.Suggestion id the get argument, checked by hand against its help
forms.history.models.HistoryEvent id no get to decide: key, else slug, else id
forms.hooks.models.Hook id the get argument
forms.images.models.Image id no get to decide: key, else slug, else id
forms.keysets.models.Keyset id the get argument
forms.me.models.User id no get to decide: key, else slug, else id
forms.models.Condition id the get argument
forms.models.OperationResult id the get argument
forms.notifications.models.Notification id the get argument
forms.notifications.models.NotificationAction id the get argument
forms.notifications.models.NotificationDetails id the get argument
forms.notifications.models.NotificationStatus id the get argument
forms.questions.models.Question id the get argument, checked by hand against its help
forms.questions.models.QuestionMoveResult id the get argument
forms.subscriptions.models.EmailSubscription id the get argument
forms.subscriptions.models.FunctionSubscription id the get argument
forms.subscriptions.models.HTTPSubscription id the get argument
forms.subscriptions.models.JSONRPCSubscription id the get argument
forms.subscriptions.models.TrackerCommentSubscription id the get argument
forms.subscriptions.models.TrackerSubscription id the get argument
forms.subscriptions.models.WikiSubscription id the get argument
forms.surveys.models.Survey id the get argument
forms.variables.models.VariableInfo name by hand: no id; a variable is called by its name
status.models.SavedProfile name by hand: --profile takes the name
sync.files.FileState path by hand: the file
sync.kind.KindSummary name by hand: --kind takes the name
sync.plan.Planned path by hand: the file
sync.pull.Pulled path by hand: the file
sync.push.Pushed path by hand: the file
tracker.attachments.models.Attachment id the get argument
tracker.autoactions.models.Autoaction id the get argument
tracker.autoactions.models.AutoactionLogEntry id the get argument
tracker.autoactions.models.AutoactionRunEntry id the get argument
tracker.boards.models.Board id the get argument
tracker.bulk.models.BulkChange id the get argument
tracker.bulk.models.BulkIssueResult issue by hand: the key of the issue the result is about
tracker.changelog.models.ChangelogEntry id no get to decide: key, else slug, else id
tracker.columns.models.Column id the get argument
tracker.comments.models.Comment id the get argument
tracker.components.models.Component id the get argument
tracker.dashboards.models.Dashboard id no get to decide: key, else slug, else id
tracker.dashboards.models.Widget id no get to decide: key, else slug, else id
tracker.entities.models.Attachment id the get argument
tracker.entities.models.BulkChangeOperation id the get argument
tracker.entities.models.Comment id the get argument
tracker.entities.models.Entity id the get argument
tracker.entities.models.EntityEvent id the get argument
tracker.fields.models.CustomField id the get argument, checked by hand against its help
tracker.fields.models.FieldCategoryRecord id the get argument
tracker.filters.models.Filter id the get argument
tracker.issuetypes.models.IssueType key no get to decide: key, else slug, else id
tracker.links.models.Link id no get to decide: key, else slug, else id
tracker.localfields.models.LocalField key the get argument
tracker.macros.models.Macro id the get argument
tracker.models.Application id no get to decide: key, else slug, else id
tracker.models.Issue key the get argument
tracker.models.IssueChecklistItem id no get to decide: key, else slug, else id
tracker.models.LinkType id no get to decide: key, else slug, else id
tracker.models.User login by hand: users get takes a login
tracker.priorities.models.Priority key no get to decide: key, else slug, else id
tracker.projects.models.Project id the get argument, checked by hand against its help
tracker.queues.models.Queue key by hand: queues get takes a key or an id
tracker.queues.models.QueueField id the get argument
tracker.queues.models.QueueVersionInfo id the get argument
tracker.remotelinks.models.RemoteLink id no get to decide: key, else slug, else id
tracker.resolutions.models.Resolution key no get to decide: key, else slug, else id
tracker.sprints.models.Sprint id the get argument
tracker.statuses.models.Status key no get to decide: key, else slug, else id
tracker.transitions.models.Transition id no get to decide: key, else slug, else id
tracker.triggers.models.Trigger id the get argument
tracker.triggers.models.WebhookLogEntry id the get argument
tracker.workflows.models.Workflow id the get argument
tracker.worklog.models.Worklog id no get to decide: key, else slug, else id
wiki.access.models.PageAccess id no get to decide: key, else slug, else id
wiki.attachments.models.AttachedFile id the get argument
wiki.comments.models.Comment id no get to decide: key, else slug, else id
wiki.comments.models.CommentCreated id no get to decide: key, else slug, else id
wiki.grids.models.ColumnSuggestion slug no get to decide: key, else slug, else id
wiki.grids.models.Grid id the get argument
wiki.pages.models.GridRef id no get to decide: key, else slug, else id
wiki.pages.models.PageDetails slug the get argument
wiki.pages.models.PageRef slug the get argument
wiki.pages.models.PageRevision id no get to decide: key, else slug, else id
wiki.recovery.models.RecoveredPage slug no get to decide: key, else slug, else id
wiki.uploadsessions.models.UploadSession session_id the get argument, checked by hand against its help

🤖 Generated with Claude Code

…ommand that reads it takes

A reply model marks the one field its resource's read command takes with `Identity()`; `-o name` prints it on a line for each item, so `ycli … list -o name | xargs -n1 ycli … get` works, and `create -o name` gives the key of what was made. An object inside another one prints its own identifier.

A command whose result has no such field is refused before it sends anything (exit code 2). A reply that leaves the identifier of an item out is an error and nothing is printed, so a script never acts on fewer objects than were listed. The plan of `--dry-run` is printed as JSON.

The hand-written models of Tracker, Wiki and Forms are marked (82 fields). The models generated from the DataLens specification are not: their resources will name the identifier where the generator reads it, in the next change.

Decisions of #561 (Р1-А, Р2-А, Р2-Г) and #498.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@bim-ba
bim-ba merged commit 418691f into main Oct 10, 2026
13 checks passed
@bim-ba
bim-ba deleted the feat/output-name branch October 10, 2026 15:09

This branch was previously deployed

1 inactive deployment
yandex-e2e — f62ace0e Deployed Oct 10, 2026 by bim-ba via live (all) #702
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant