Skip to content

feat(cli): -o csv, -o markdown and -o ndjson print a table or one item on a line - #568

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

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

Conversation

@bim-ba

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

Copy link
Copy Markdown
Owner

First of the two output-format PRs decided in #561 (and #498). The second, -o name, follows.

What it does

  • -o csv and -o markdown print a table; -o ndjson prints one item on a line. They work on every command: a result that is one object is a table of one row, or one line.
  • The columns are the fields the model declares (Р5-Б), so the header does not depend on the reply. A nested object becomes columns named through a dot (status.key); a list stays one cell of JSON text (Р4-А).
  • An empty listing prints its header. The command's declared return type is read where get_type_hints(command) already runs (cli/inject.py) and travels beside the result as Declared(result, returns), the way feat!: every listing takes limit, everything and next on the SDK, the CLI and the MCP server #534 carries Continuable. It does not go through a context: typer 0.26.8 vendors click, and the root result callback has no context to read.
  • ndjson prints the items alone; where a listing stopped is said on stderr (Р12-А).
  • csv: UTF-8 with no byte order mark, lines end with a line feed, cells are the service's text as it came (Р13). The how-to says that a spreadsheet reads a cell starting with = as a formula.
  • Nothing changes for MCP or the SDK (Р10, Р11).

An invariant changes — please look

ARCH-4 and its enforcing check change in this PR (Р14-А): csv.writer and csv.DictWriter join the serializers that only cli/output.py may call. ARCHITECTURE.md, tests/architecture/test_arch4.py and two biting cases are edited together.

Choices the decisions did not spell out (accepted by the architect)

  • A result that wraps one object in a root model is that object; a mapping is one value cell of JSON text.
  • Items that are not objects (Listing[str]) are one column, value.
  • A model that declares no field, and a model that holds itself (parent), is one cell of JSON text.
  • A listing of several kinds (forms subscriptions list, datalens collections content-list) has the columns of every declared kind.
  • A line break inside a Markdown cell is <br>.
  • A field the service added that the model does not declare has no column; -o json prints it.

Checked

  • uv run pytest: 6217 passed, 5 skipped, coverage 100% (lines and branches); lint-imports, ty, ruff clean. That run was on this tree before the last edit, which added a Raises: section to one docstring; after it, tests/unit/cli and the new contract test were rerun (1159 passed) and the pre-commit hooks passed.
  • Every contract case that has a command (723) is printed in the three formats and measured against -o json: the ndjson lines equal the items, every csv cell equals the JSON value under its column, every Markdown line has the same number of cells, and text, counts and bytes print the same in every format.
  • Column names are checked against the keys pydantic's serialization schema names, for every model the cases load (more than 500). This replaced a per-case check ("every column is a key of an item"), which stopped holding once a listing prints the columns of kinds its reply does not contain.
  • Each new check was seen failing on its defect: a column named by the field instead of the API key; the declared type ignored (empty listing with no header); csv.writer called outside output.py.

Not run

  • No live service: the formats were not tried against Tracker, Wiki, Forms or DataLens.
  • How Excel or Google Sheets open the file (with or without a byte order mark) was not measured.
  • The e2e scenarios.

🤖 Generated with Claude Code

…ne item on a line

A table has the columns the model declares, so the header is the same whatever the reply holds: a nested object becomes `status.key` columns, a list stays one cell of JSON text, a result that is one object is a table of one row. An empty listing prints its header too: the command's declared return type travels beside the result (`Declared`), read where the type hints of a command are already read. `ndjson` prints the items alone; where a listing stopped is said on stderr.

`csv` is UTF-8 with no byte order mark, lines end with a line feed, cells are the service's text as it came.

ARCH-4 changes with its check in this commit: `csv.writer` and `csv.DictWriter` are serializers only `output.py` may call.

Decisions of #561 (Р3-А, Р4-А, Р5-Б, Р12-А, Р13, Р14-А).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch was previously deployed

1 inactive deployment
yandex-e2e — 2c0259b7 Deployed Oct 10, 2026 by bim-ba via live (all) #700
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