From 5c8510dfc29b2f1d8af52498c2da7abb9fe0f591 Mon Sep 17 00:00:00 2001 From: Nikolaos Paximadakis Date: Sun, 22 Nov 2026 00:10:42 +0100 Subject: [PATCH] dataflow docstrings: cross-check against the current backend source Re-read the dataflow routes on the backend branch closest to live. The listings, paging, create and delete behave as before. Corrections: dataflow_datasets now says an unknown dataflow id answers 500 (the access check fails first, seen live), not an empty 200, and lists the admin and national coordinator access; dataflows lists the filters keys the backend reads; delete_dataflow notes that a Business dataflow needs an admin. Adds a mocked test for the 500 and regenerates the reference page. --- CHANGELOG.md | 5 +++++ docs/reference/dataflow.md | 24 ++++++++++++++++++------ reportnet_api/resources/dataflow_ext.py | 24 ++++++++++++++++++------ tests/test_resources_dataflow_ext.py | 24 +++++++++++++++++++++++- 4 files changed, 64 insertions(+), 13 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 10d7607..3c1406d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,11 @@ release (0.x.y) only fixes bugs. Breaking changes are called out below. ## Unreleased +- `dataflow` docstrings checked against the current backend source: + `dataflow_datasets` now says an unknown dataflow id answers 500 (not an empty + 200), and lists the admin and national coordinator access; `dataflows` lists + the `filters` keys the backend reads; `delete_dataflow` notes that a Business + dataflow needs an admin. - New `easy.list_representatives(client, dataflow_id)`: the countries assigned to a dataflow as a table, with the country code and name joined from the provider listing (one lookup per provider group). Lead reporter email addresses are left out diff --git a/docs/reference/dataflow.md b/docs/reference/dataflow.md index fc5af62..976b1b2 100644 --- a/docs/reference/dataflow.md +++ b/docs/reference/dataflow.md @@ -69,11 +69,15 @@ the dataflow with its datasets (`designDatasets`, `reportingDatasets`, `dataColl Not stated in the API spec. -Reporters must pass `provider_id`. Requires a dataflow role (or a -matching ApiKey / data custodian-steward reference access). +Reporters must pass `provider_id`. Requires a dataflow role (including +national coordinator), a matching ApiKey, data custodian/steward +reference access, or the `ADMIN` role. Representatives are filtered to +the caller's own unless the caller is the dataflow's requester. -Returns `None` when the backend answers 200 with an empty body (it -swallows its own errors, e.g. for an unknown dataflow). +An unknown dataflow id answers `500` (`ServerError`): the access check +fails before the lookup. A dataflow the caller has no access to +answers `403`. Returns `None` when the backend answers 200 with an +empty body (it swallows its own errors after the access check). ### dataflows @@ -108,6 +112,13 @@ signs in as the key's owner, so it lists the owner's dataflows. `ValueError`. A backend-side failure comes back as an empty 200 page, indistinguishable from "no dataflows". +`filters` is the web app's filter map, all values strings. Keys the +backend reads include `name`, `description`, `obligation`, +`legal_instrument`, `status` (`OPEN`, `CLOSED`, `DESIGN`), `pinned` +and date ranges such as `deadline_date_from`/`deadline_date_to`. The +key `role` (e.g. `"LEAD_REPORTER"`) keeps only the dataflows where +the user holds that role. + ### delete_dataflow delete a dataflow with its design datasets, documents and representatives. @@ -127,7 +138,8 @@ delete a dataflow with its design datasets, documents and representatives. Not stated in the API spec. `DataflowControllerImpl#deleteDataFlow`. Requires `DATAFLOW_STEWARD` or -`DATAFLOW_CUSTODIAN` on the dataflow. `423` while a schema import or -a schema copy into it is running. The backend logs and swallows its +`DATAFLOW_CUSTODIAN` on the dataflow; a `BUSINESS` dataflow needs an +admin (`403` otherwise). `423` while a schema import or a schema copy +into it is running. The backend logs and swallows its own failures (`DataflowServiceImpl#deleteDataFlow`), so a 200 does not prove the dataflow is gone: `dataflow_datasets()` afterwards does. diff --git a/reportnet_api/resources/dataflow_ext.py b/reportnet_api/resources/dataflow_ext.py index 1b92b2b..2363ec7 100644 --- a/reportnet_api/resources/dataflow_ext.py +++ b/reportnet_api/resources/dataflow_ext.py @@ -126,6 +126,13 @@ def dataflows( `page_size` and `page_num` (0-based); giving only one raises `ValueError`. A backend-side failure comes back as an empty 200 page, indistinguishable from "no dataflows". + + `filters` is the web app's filter map, all values strings. Keys the + backend reads include `name`, `description`, `obligation`, + `legal_instrument`, `status` (`OPEN`, `CLOSED`, `DESIGN`), `pinned` + and date ranges such as `deadline_date_from`/`deadline_date_to`. The + key `role` (e.g. `"LEAD_REPORTER"`) keeps only the dataflows where + the user holds that role. """ path, params, body = _list_request(kind, filters, order_header, asc, page_size, page_num) response = self._client.request("POST", path, params=params, json=body) @@ -139,11 +146,15 @@ def dataflow_datasets( (`designDatasets`, `reportingDatasets`, `dataCollections`, `euDatasets`, `referenceDatasets`, `testDatasets`). - Reporters must pass `provider_id`. Requires a dataflow role (or a - matching ApiKey / data custodian-steward reference access). + Reporters must pass `provider_id`. Requires a dataflow role (including + national coordinator), a matching ApiKey, data custodian/steward + reference access, or the `ADMIN` role. Representatives are filtered to + the caller's own unless the caller is the dataflow's requester. - Returns `None` when the backend answers 200 with an empty body (it - swallows its own errors, e.g. for an unknown dataflow). + An unknown dataflow id answers `500` (`ServerError`): the access check + fails before the lookup. A dataflow the caller has no access to + answers `403`. Returns `None` when the backend answers 200 with an + empty body (it swallows its own errors after the access check). """ params = {} if provider_id is None else {"providerId": provider_id} response = self._client.request("GET", f"/dataflow/v1/{dataflow_id}", params=params) @@ -184,8 +195,9 @@ def delete_dataflow(self, dataflow_id: int) -> None: datasets, documents and representatives. `DataflowControllerImpl#deleteDataFlow`. Requires `DATAFLOW_STEWARD` or - `DATAFLOW_CUSTODIAN` on the dataflow. `423` while a schema import or - a schema copy into it is running. The backend logs and swallows its + `DATAFLOW_CUSTODIAN` on the dataflow; a `BUSINESS` dataflow needs an + admin (`403` otherwise). `423` while a schema import or a schema copy + into it is running. The backend logs and swallows its own failures (`DataflowServiceImpl#deleteDataFlow`), so a 200 does not prove the dataflow is gone: `dataflow_datasets()` afterwards does. """ diff --git a/tests/test_resources_dataflow_ext.py b/tests/test_resources_dataflow_ext.py index 5d6b2fb..9031403 100644 --- a/tests/test_resources_dataflow_ext.py +++ b/tests/test_resources_dataflow_ext.py @@ -8,7 +8,13 @@ import pytest import respx -from reportnet_api import AsyncReportnetClient, ReportnetAPIError, ReportnetClient, ValidationError +from reportnet_api import ( + AsyncReportnetClient, + ReportnetAPIError, + ReportnetClient, + ServerError, + ValidationError, +) BASE_URL = "https://api.reportnet.europa.eu" PAGE = {"dataflows": [{"id": 1, "name": "x"}], "totalRecords": 1, "filteredRecords": 1} @@ -100,6 +106,22 @@ async def run() -> object: assert asyncio.run(run()) is None +def test_dataflow_datasets_unknown_id_is_server_error() -> None: + # Live shape for an unknown id: the access check fails with a 500. + body = { + "status": 500, + "error": "Internal Server Error", + "message": ( + "status 500 reading DataFlowControllerZuul#accessReferenceEntity(EntityClassEnum,Long)" + ), + } + with respx.mock(base_url=BASE_URL) as mock: + mock.get("/dataflow/v1/1").mock(return_value=httpx.Response(500, json=body)) + with ReportnetClient(base_url=BASE_URL, token="t") as client: + with pytest.raises(ServerError): + client.dataflow.dataflow_datasets(1) + + def test_create_dataflow_returns_new_id() -> None: with respx.mock(base_url=BASE_URL) as mock: route = mock.post("/dataflow").mock(return_value=httpx.Response(200, text="13555"))