Skip to content

Commit 8b529de

Browse files
simonwclaude
andauthored
Row JSON now returns {"row": {...}} (#3071)
* Row JSON now returns {"row": {...}} /database/table/pk.json previously returned the row as the only item in a "rows" list. It now returns it as an object in a "row" key. Two other keys change to match: "truncated" is no longer included, since a single row lookup cannot be truncated, and the render_cell extra is a single object keyed by column name instead of a list of one. Any ?_shape= option returns the same shapes as table JSON, so ?_shape=objects gives the previous format. Output renderer plugins are still passed a rows list containing the one row. The row edit dialog reads the new shape. Closes #2612, closes #2137 Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
1 parent 2d5e496 commit 8b529de

9 files changed

Lines changed: 151 additions & 45 deletions

File tree

‎datasette/renderer.py‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -141,13 +141,17 @@ async def json_renderer(
141141

142142
# Deal with the _shape option
143143
shape = args.get("_shape", "objects")
144+
# Row pages return {"row": {...}} unless a ?_shape= is requested
145+
single_row = view_name == "row" and "_shape" not in args
144146
# if there's an error, ignore the shape entirely
145147
if error:
146148
shape = "objects"
149+
single_row = False
147150
status_code = 400
148151
data.update(error_body(error, status_code))
149152

150-
if truncated is not None:
153+
# A single row cannot be truncated
154+
if truncated is not None and not single_row:
151155
data["truncated"] = truncated
152156
if shape == "arrayfirst":
153157
if not data["rows"]:
@@ -160,6 +164,18 @@ async def json_renderer(
160164
rows = data.get("rows")
161165
if rows and columns and not isinstance(rows[0], dict):
162166
data["rows"] = [dict(zip(columns, row)) for row in rows]
167+
if single_row:
168+
# Swap "rows" for "row", keeping its position in the output
169+
data = {
170+
("row" if key == "rows" else key): (
171+
(value[0] if value else None) if key == "rows" else value
172+
)
173+
for key, value in data.items()
174+
}
175+
# Likewise the render_cell extra becomes a single object
176+
if "render_cell" in data:
177+
cells = data["render_cell"]
178+
data["render_cell"] = cells[0] if cells else {}
163179
if shape == "object":
164180
shape_error = None
165181
if "primary_keys" not in data:

‎datasette/static/edit-tools.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6817,7 +6817,7 @@ async function saveRowEditDialog(state) {
68176817
}
68186818

68196819
function renderRowEditFields(state, data) {
6820-
var row = data.rows && data.rows.length ? data.rows[0] : null;
6820+
var row = data.row || null;
68216821
var columns = data.columns || (row ? Object.keys(row) : []);
68226822
var primaryKeys = data.primary_keys || [];
68236823
var columnTypes = data.column_types || {};

‎datasette/views/table_extras.py‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -652,13 +652,14 @@ class RenderCellExtra(Extra):
652652
examples: ClassVar[dict[ExtraScope, ExtraExample | list[ExtraExample]]] = {
653653
ExtraScope.ROW: ExtraExample(
654654
value={
655-
"rows": [{"id": 4, "content": "RENDER_CELL_DEMO"}],
656-
"render_cell": [{"content": "<strong>Custom rendered HTML</strong>"}],
655+
"row": {"id": 4, "content": "RENDER_CELL_DEMO"},
656+
"render_cell": {"content": "<strong>Custom rendered HTML</strong>"},
657657
},
658658
note=(
659-
"The ``render_cell`` array has one item for the requested row. "
660-
"The object is keyed by column name. Only columns whose rendered "
661-
"value differs from the default are included."
659+
"The ``render_cell`` object is keyed by column name. Only columns "
660+
"whose rendered value differs from the default are included. If a "
661+
"``?_shape=`` is specified ``render_cell`` is instead a list with "
662+
"one item, matching the ``rows`` list."
662663
),
663664
),
664665
ExtraScope.QUERY: ExtraExample(

‎docs/changelog.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ Unreleased
1616
- The ``allow_csv_stream`` and ``max_csv_mb`` settings have been renamed to :ref:`setting_default_allow_stream` and :ref:`setting_max_stream_mb`, since they now apply to every format that can stream. The previous names continue to work.
1717
- The ``allow_facet`` and ``allow_download`` settings have been renamed to :ref:`setting_default_allow_facet` and :ref:`setting_default_allow_download`, matching :ref:`setting_default_allow_sql`. The previous names continue to work. (:issue:`1410`)
1818
- **Breaking change**: the ``datasette_allow_facet`` template variable has been removed from the table page. Custom ``table.html`` templates that use it should use ``{{ settings.default_allow_facet|tojson }}`` instead.
19+
- **Breaking change**: the JSON for an individual row, such as ``/database/table/1.json``, now returns that row as an object in a ``"row"`` key instead of as the only item in a ``"rows"`` list. The ``"truncated"`` key has been removed from that response and the ``render_cell`` extra is now a single object. Adding any ``?_shape=`` option, such as ``?_shape=objects``, returns the same shapes as table JSON. See :ref:`json_api_row` and the :ref:`upgrade guide <upgrade_guide_v1_row_json>`. (:issue:`2612`, :issue:`2137`)
1920
- **Breaking change**: the ``view_name`` passed to plugin hooks for SQL query pages, both arbitrary SQL and stored queries, is now ``"query"``. Template hooks such as :ref:`plugin_hook_extra_template_vars` were previously passed ``"database"`` for those pages. Output renderers were passed ``"table"`` by ``render`` and ``"database"`` by ``can_render``. See :ref:`the upgrade guide <upgrade_guide_v1_view_name_query>`.
2021
- **Breaking change**: output renderer ``render`` functions must now return a :ref:`Response <internals_response>` object, or ``None``. Returning a dictionary with ``body``, ``content_type``, ``status_code`` and ``headers`` keys, deprecated since Datasette 0.49, is now an error. The ``"callback"`` key, the pre-0.49 name for ``"render"``, has also been removed. See :ref:`the upgrade guide <upgrade_guide_v1_renderer_response>`. (:issue:`954`)
2122
- Output renderers whose ``render`` function accepts the undocumented ``data`` or ``args`` arguments now trigger a ``DeprecationWarning`` when Datasette starts. Those arguments will be removed before Datasette 1.0. Use the ``page`` argument in place of ``data``, and ``request.args`` in place of ``args``. (:issue:`2770`)

‎docs/json_api.rst‎

Lines changed: 37 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,34 @@ Values for named SQL parameters can be provided as additional query string param
154154

155155
The response uses the same default representation described above.
156156

157+
.. _json_api_row:
158+
159+
Rows
160+
----
161+
162+
Every row in a table has its own JSON URL, see :ref:`RowView`. The row is returned as an object in the ``"row"`` key:
163+
164+
::
165+
166+
GET /fixtures/simple_primary_key/1.json
167+
168+
.. code-block:: json
169+
170+
{
171+
"ok": true,
172+
"database": "fixtures",
173+
"table": "simple_primary_key",
174+
"primary_keys": ["id"],
175+
"primary_key_values": ["1"],
176+
"query_ms": 1.2,
177+
"row": {
178+
"id": 1,
179+
"content": "hello"
180+
}
181+
}
182+
183+
Pass any :ref:`?_shape= option <json_api_shapes>` to return the row using the same shapes as table JSON instead. ``?_shape=objects`` returns the table default representation, with the row as the only item in the ``"rows"`` list.
184+
157185
.. _json_api_shapes:
158186

159187
Different shapes
@@ -163,7 +191,7 @@ The ``_shape`` parameter can be used to access alternative formats for the
163191
``rows`` key which may be more convenient for your application. There are three
164192
options:
165193

166-
* ``?_shape=objects`` - ``"rows"`` is a list of JSON key/value objects - the default
194+
* ``?_shape=objects`` - ``"rows"`` is a list of JSON key/value objects - the default for tables and queries
167195
* ``?_shape=arrays`` - ``"rows"`` is a list of lists, where the order of values in each list matches the order of the columns
168196
* ``?_shape=array`` - a JSON array of objects - effectively just the ``"rows"`` key from the default representation
169197
* ``?_shape=array&_nl=on`` - a newline-separated list of JSON objects
@@ -954,22 +982,18 @@ The following extras are available for row JSON responses.
954982
``render_cell``
955983
Rendered HTML for each cell using the render_cell plugin hook (See the :ref:`render_cell() plugin hook <plugin_hook_render_cell>` documentation.)
956984

957-
The ``render_cell`` array has one item for the requested row. The object is keyed by column name. Only columns whose rendered value differs from the default are included.
985+
The ``render_cell`` object is keyed by column name. Only columns whose rendered value differs from the default are included. If a ``?_shape=`` is specified ``render_cell`` is instead a list with one item, matching the ``rows`` list.
958986

959987
.. code-block:: json
960988
961989
{
962-
"rows": [
963-
{
964-
"id": 4,
965-
"content": "RENDER_CELL_DEMO"
966-
}
967-
],
968-
"render_cell": [
969-
{
970-
"content": "<strong>Custom rendered HTML</strong>"
971-
}
972-
]
990+
"row": {
991+
"id": 4,
992+
"content": "RENDER_CELL_DEMO"
993+
},
994+
"render_cell": {
995+
"content": "<strong>Custom rendered HTML</strong>"
996+
}
973997
}
974998
975999
``debug``

‎docs/upgrade_guide.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,27 @@ if view_name in ("database", "query"):
4343
...
4444
```
4545

46+
(upgrade_guide_v1_row_json)=
47+
### Row JSON returns a single `"row"` object
48+
49+
The JSON for an individual row, such as `/databasename/tablename/1.json`, previously returned that row as the only item in a `"rows"` list. It now returns it as an object in a `"row"` key:
50+
51+
```json
52+
{
53+
"ok": true,
54+
"row": {
55+
"id": 1,
56+
"content": "hello"
57+
}
58+
}
59+
```
60+
61+
Two other keys changed to match. The response no longer includes `"truncated"`, which was always `false`. If you request `?_extra=render_cell`, the `"render_cell"` key is now a single object keyed by column name instead of a list containing one object.
62+
63+
Add `?_shape=objects` to the URL to get the previous format, with a `"rows"` list containing that row, a `"truncated"` key and `"render_cell"` as a list. Any other `?_shape=` option returns the same shape as table JSON. See {ref}`json_api_row`.
64+
65+
Output renderer plugins are not affected: on row pages they are still passed a `rows` list containing the one row.
66+
4667
(upgrade_guide_v1_renderer_response)=
4768
### Output renderers must return a `Response`
4869

‎tests/test_api.py‎

Lines changed: 63 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -368,10 +368,54 @@ async def test_invalid_custom_sql(ds_client):
368368

369369
@pytest.mark.asyncio
370370
async def test_row(ds_client):
371-
response = await ds_client.get("/fixtures/simple_primary_key/1.json?_shape=objects")
371+
response = await ds_client.get("/fixtures/simple_primary_key/1.json")
372372
assert response.status_code == 200
373-
assert response.json()["ok"] is True
374-
assert response.json()["rows"] == [{"id": 1, "content": "hello"}]
373+
data = response.json()
374+
assert data["ok"] is True
375+
assert data["row"] == {"id": 1, "content": "hello"}
376+
assert "rows" not in data
377+
assert "truncated" not in data
378+
379+
380+
@pytest.mark.asyncio
381+
@pytest.mark.parametrize(
382+
"shape,expected",
383+
(
384+
("objects", [{"id": 1, "content": "hello"}]),
385+
("arrays", [[1, "hello"]]),
386+
("array", [{"id": 1, "content": "hello"}]),
387+
("arrayfirst", [1]),
388+
("object", {"1": {"id": 1, "content": "hello"}}),
389+
),
390+
)
391+
async def test_row_shape(ds_client, shape, expected):
392+
# Any ?_shape= returns the same shapes as the table JSON
393+
response = await ds_client.get(
394+
f"/fixtures/simple_primary_key/1.json?_shape={shape}"
395+
)
396+
assert response.status_code == 200
397+
data = response.json()
398+
if shape in ("objects", "arrays"):
399+
assert "row" not in data
400+
assert data["truncated"] is False
401+
data = data["rows"]
402+
assert data == expected
403+
404+
405+
@pytest.mark.asyncio
406+
async def test_row_json_cols(ds_client):
407+
response = await ds_client.get("/fixtures/facetable/1.json?_json=tags")
408+
assert response.status_code == 200
409+
assert response.json()["row"]["tags"] == ["tag1", "tag2"]
410+
411+
412+
@pytest.mark.asyncio
413+
async def test_row_not_found_is_an_error(ds_client):
414+
response = await ds_client.get("/fixtures/simple_primary_key/missing.json")
415+
assert response.status_code == 404
416+
data = response.json()
417+
assert data["ok"] is False
418+
assert "row" not in data
375419

376420

377421
@pytest.mark.asyncio
@@ -618,22 +662,18 @@ def render_cell(self, value, column, table, database):
618662
assert response.status_code == 200
619663
data = response.json()
620664

621-
# Verify the response structure
622-
assert "render_cell" in data
623-
assert "rows" in data
665+
# render_cell is a single object to match "row". Only columns
666+
# modified by plugins are included, so there is no "id" key
667+
assert data["render_cell"] == {"name": "<strong>Alice</strong>"}
668+
# The row itself still contains raw values
669+
assert data["row"] == {"id": 1, "name": "Alice"}
624670

625-
# render_cell should be a list with one row (since this is a row page)
626-
# Only columns modified by plugins are included (sparse output)
627-
render_cell = data["render_cell"]
628-
assert len(render_cell) == 1
629-
630-
# The row: id=1, name='Alice'
631-
# The 'name' column should be rendered by our plugin as <strong>Alice</strong>
632-
assert render_cell[0]["name"] == "<strong>Alice</strong>"
633-
# The 'id' column is not included since no plugin modified it
634-
assert "id" not in render_cell[0]
635-
636-
# The regular rows should still contain raw values
671+
# With a ?_shape= render_cell is a list, matching "rows"
672+
response = await ds.client.get(
673+
"/test_row_render/test_render/1.json?_extra=render_cell&_shape=objects"
674+
)
675+
data = response.json()
676+
assert data["render_cell"] == [{"name": "<strong>Alice</strong>"}]
637677
assert data["rows"] == [{"id": 1, "name": "Alice"}]
638678

639679
finally:
@@ -840,9 +880,11 @@ async def test_json_columns_preserve_other_values(endpoint, value, expected):
840880
try:
841881
response = await ds.client.get(path + "?_json=value")
842882
assert response.status_code == 200
843-
assert response.json()["rows"] == [
844-
{"id": 1, "value": expected, "other": '{"keep": true}'}
845-
]
883+
row = {"id": 1, "value": expected, "other": '{"keep": true}'}
884+
if endpoint == "row":
885+
assert response.json()["row"] == row
886+
else:
887+
assert response.json()["rows"] == [row]
846888
finally:
847889
ds.close()
848890

‎tests/test_column_types.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -748,7 +748,7 @@ async def test_row_endpoint_render_cell_with_column_types(ds_ct):
748748
response = await ds_ct.client.get("/data/posts/1.json?_extra=render_cell")
749749
assert response.status_code == 200
750750
data = response.json()
751-
rendered = data["render_cell"][0]
751+
rendered = data["render_cell"]
752752
assert "mailto:" in rendered["author_email"]
753753
assert "href" in rendered["website"]
754754

‎tests/test_playwright.py‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3934,9 +3934,10 @@ def test_export_data_dialog_on_row_page(page, datasette_server):
39343934
json_group = dialog.get_by_role("group", name="JSON", exact=True)
39353935
json_group.get_by_role("button", name="Copy", exact=True).click()
39363936
expect(json_group.get_by_role("button", name="Copied")).to_be_visible()
3937-
assert json.loads(page.evaluate("clipboardText"))["rows"] == [
3938-
{"id": 1, "content": "hello"}
3939-
]
3937+
assert json.loads(page.evaluate("clipboardText"))["row"] == {
3938+
"id": 1,
3939+
"content": "hello",
3940+
}
39403941
csv = dialog.get_by_role("group", name="CSV", exact=True)
39413942
with page.expect_download() as download_info:
39423943
csv.get_by_role("button", name="Download").click()

0 commit comments

Comments
 (0)