Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion datasette/renderer.py
Original file line number Diff line number Diff line change
Expand Up @@ -141,13 +141,17 @@ async def json_renderer(

# Deal with the _shape option
shape = args.get("_shape", "objects")
# Row pages return {"row": {...}} unless a ?_shape= is requested
single_row = view_name == "row" and "_shape" not in args
# if there's an error, ignore the shape entirely
if error:
shape = "objects"
single_row = False
status_code = 400
data.update(error_body(error, status_code))

if truncated is not None:
# A single row cannot be truncated
if truncated is not None and not single_row:
data["truncated"] = truncated
if shape == "arrayfirst":
if not data["rows"]:
Expand All @@ -160,6 +164,18 @@ async def json_renderer(
rows = data.get("rows")
if rows and columns and not isinstance(rows[0], dict):
data["rows"] = [dict(zip(columns, row)) for row in rows]
if single_row:
# Swap "rows" for "row", keeping its position in the output
data = {
("row" if key == "rows" else key): (
(value[0] if value else None) if key == "rows" else value
)
for key, value in data.items()
}
# Likewise the render_cell extra becomes a single object
if "render_cell" in data:
cells = data["render_cell"]
data["render_cell"] = cells[0] if cells else {}
if shape == "object":
shape_error = None
if "primary_keys" not in data:
Expand Down
2 changes: 1 addition & 1 deletion datasette/static/edit-tools.js
Original file line number Diff line number Diff line change
Expand Up @@ -6817,7 +6817,7 @@ async function saveRowEditDialog(state) {
}

function renderRowEditFields(state, data) {
var row = data.rows && data.rows.length ? data.rows[0] : null;
var row = data.row || null;
var columns = data.columns || (row ? Object.keys(row) : []);
var primaryKeys = data.primary_keys || [];
var columnTypes = data.column_types || {};
Expand Down
11 changes: 6 additions & 5 deletions datasette/views/table_extras.py
Original file line number Diff line number Diff line change
Expand Up @@ -652,13 +652,14 @@ class RenderCellExtra(Extra):
examples: ClassVar[dict[ExtraScope, ExtraExample | list[ExtraExample]]] = {
ExtraScope.ROW: ExtraExample(
value={
"rows": [{"id": 4, "content": "RENDER_CELL_DEMO"}],
"render_cell": [{"content": "<strong>Custom rendered HTML</strong>"}],
"row": {"id": 4, "content": "RENDER_CELL_DEMO"},
"render_cell": {"content": "<strong>Custom rendered HTML</strong>"},
},
note=(
"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."
"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."
),
),
ExtraScope.QUERY: ExtraExample(
Expand Down
1 change: 1 addition & 0 deletions docs/changelog.rst
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,7 @@ Unreleased
- 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.
- 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`)
- **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.
- **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`)
- **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>`.
- **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`)
- 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`)
Expand Down
50 changes: 37 additions & 13 deletions docs/json_api.rst
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,34 @@ Values for named SQL parameters can be provided as additional query string param

The response uses the same default representation described above.

.. _json_api_row:

Rows
----

Every row in a table has its own JSON URL, see :ref:`RowView`. The row is returned as an object in the ``"row"`` key:

::

GET /fixtures/simple_primary_key/1.json

.. code-block:: json
{
"ok": true,
"database": "fixtures",
"table": "simple_primary_key",
"primary_keys": ["id"],
"primary_key_values": ["1"],
"query_ms": 1.2,
"row": {
"id": 1,
"content": "hello"
}
}
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.

.. _json_api_shapes:

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

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

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.
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.

.. code-block:: json
{
"rows": [
{
"id": 4,
"content": "RENDER_CELL_DEMO"
}
],
"render_cell": [
{
"content": "<strong>Custom rendered HTML</strong>"
}
]
"row": {
"id": 4,
"content": "RENDER_CELL_DEMO"
},
"render_cell": {
"content": "<strong>Custom rendered HTML</strong>"
}
}
``debug``
Expand Down
21 changes: 21 additions & 0 deletions docs/upgrade_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,27 @@ if view_name in ("database", "query"):
...
```

(upgrade_guide_v1_row_json)=
### Row JSON returns a single `"row"` object

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:

```json
{
"ok": true,
"row": {
"id": 1,
"content": "hello"
}
}
```

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.

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`.

Output renderer plugins are not affected: on row pages they are still passed a `rows` list containing the one row.

(upgrade_guide_v1_renderer_response)=
### Output renderers must return a `Response`

Expand Down
84 changes: 63 additions & 21 deletions tests/test_api.py
Original file line number Diff line number Diff line change
Expand Up @@ -368,10 +368,54 @@ async def test_invalid_custom_sql(ds_client):

@pytest.mark.asyncio
async def test_row(ds_client):
response = await ds_client.get("/fixtures/simple_primary_key/1.json?_shape=objects")
response = await ds_client.get("/fixtures/simple_primary_key/1.json")
assert response.status_code == 200
assert response.json()["ok"] is True
assert response.json()["rows"] == [{"id": 1, "content": "hello"}]
data = response.json()
assert data["ok"] is True
assert data["row"] == {"id": 1, "content": "hello"}
assert "rows" not in data
assert "truncated" not in data


@pytest.mark.asyncio
@pytest.mark.parametrize(
"shape,expected",
(
("objects", [{"id": 1, "content": "hello"}]),
("arrays", [[1, "hello"]]),
("array", [{"id": 1, "content": "hello"}]),
("arrayfirst", [1]),
("object", {"1": {"id": 1, "content": "hello"}}),
),
)
async def test_row_shape(ds_client, shape, expected):
# Any ?_shape= returns the same shapes as the table JSON
response = await ds_client.get(
f"/fixtures/simple_primary_key/1.json?_shape={shape}"
)
assert response.status_code == 200
data = response.json()
if shape in ("objects", "arrays"):
assert "row" not in data
assert data["truncated"] is False
data = data["rows"]
assert data == expected


@pytest.mark.asyncio
async def test_row_json_cols(ds_client):
response = await ds_client.get("/fixtures/facetable/1.json?_json=tags")
assert response.status_code == 200
assert response.json()["row"]["tags"] == ["tag1", "tag2"]


@pytest.mark.asyncio
async def test_row_not_found_is_an_error(ds_client):
response = await ds_client.get("/fixtures/simple_primary_key/missing.json")
assert response.status_code == 404
data = response.json()
assert data["ok"] is False
assert "row" not in data


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

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

# render_cell should be a list with one row (since this is a row page)
# Only columns modified by plugins are included (sparse output)
render_cell = data["render_cell"]
assert len(render_cell) == 1

# The row: id=1, name='Alice'
# The 'name' column should be rendered by our plugin as <strong>Alice</strong>
assert render_cell[0]["name"] == "<strong>Alice</strong>"
# The 'id' column is not included since no plugin modified it
assert "id" not in render_cell[0]

# The regular rows should still contain raw values
# With a ?_shape= render_cell is a list, matching "rows"
response = await ds.client.get(
"/test_row_render/test_render/1.json?_extra=render_cell&_shape=objects"
)
data = response.json()
assert data["render_cell"] == [{"name": "<strong>Alice</strong>"}]
assert data["rows"] == [{"id": 1, "name": "Alice"}]

finally:
Expand Down Expand Up @@ -840,9 +880,11 @@ async def test_json_columns_preserve_other_values(endpoint, value, expected):
try:
response = await ds.client.get(path + "?_json=value")
assert response.status_code == 200
assert response.json()["rows"] == [
{"id": 1, "value": expected, "other": '{"keep": true}'}
]
row = {"id": 1, "value": expected, "other": '{"keep": true}'}
if endpoint == "row":
assert response.json()["row"] == row
else:
assert response.json()["rows"] == [row]
finally:
ds.close()

Expand Down
2 changes: 1 addition & 1 deletion tests/test_column_types.py
Original file line number Diff line number Diff line change
Expand Up @@ -748,7 +748,7 @@ async def test_row_endpoint_render_cell_with_column_types(ds_ct):
response = await ds_ct.client.get("/data/posts/1.json?_extra=render_cell")
assert response.status_code == 200
data = response.json()
rendered = data["render_cell"][0]
rendered = data["render_cell"]
assert "mailto:" in rendered["author_email"]
assert "href" in rendered["website"]

Expand Down
7 changes: 4 additions & 3 deletions tests/test_playwright.py
Original file line number Diff line number Diff line change
Expand Up @@ -3934,9 +3934,10 @@ def test_export_data_dialog_on_row_page(page, datasette_server):
json_group = dialog.get_by_role("group", name="JSON", exact=True)
json_group.get_by_role("button", name="Copy", exact=True).click()
expect(json_group.get_by_role("button", name="Copied")).to_be_visible()
assert json.loads(page.evaluate("clipboardText"))["rows"] == [
{"id": 1, "content": "hello"}
]
assert json.loads(page.evaluate("clipboardText"))["row"] == {
"id": 1,
"content": "hello",
}
csv = dialog.get_by_role("group", name="CSV", exact=True)
with page.expect_download() as download_info:
csv.get_by_role("button", name="Download").click()
Expand Down
Loading