reportnet-api 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,239 @@
1
+ """Hand-written Dataflow resource (listings, dataflow detail, create, delete).
2
+
3
+ The Dataflow tag is absent from spec/api-docs.json ("Known spec-
4
+ snapshot gap"), and the four listing routes, create and delete are
5
+ `@ApiOperation(hidden = true)` in `DataflowControllerImpl` (`dataflow-service`).
6
+ This file is never touched by the generators.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from typing import TYPE_CHECKING, Any, Literal
12
+
13
+ from .._exceptions import ReportnetAPIError
14
+
15
+ if TYPE_CHECKING:
16
+ import httpx
17
+
18
+ from ..async_client import AsyncReportnetClient
19
+ from ..client import ReportnetClient
20
+
21
+ DataflowKind = Literal["reporting", "reference", "business", "citizen_science"]
22
+ DataflowType = Literal["REPORTING", "REFERENCE", "BUSINESS", "CITIZEN_SCIENCE"]
23
+
24
+ _LIST_PATHS: dict[str, str] = {
25
+ "reporting": "/dataflow/getDataflows",
26
+ "reference": "/dataflow/referenceDataflows",
27
+ "business": "/dataflow/businessDataflows",
28
+ "citizen_science": "/dataflow/citizenScienceDataflows",
29
+ }
30
+
31
+
32
+ def _list_request(
33
+ kind: str,
34
+ filters: dict[str, str] | None,
35
+ order_header: str | None,
36
+ asc: bool | None,
37
+ page_size: int | None,
38
+ page_num: int | None,
39
+ ) -> tuple[str, dict[str, Any], dict[str, str] | None]:
40
+ try:
41
+ path = _LIST_PATHS[kind]
42
+ except KeyError:
43
+ raise ValueError(f"kind must be one of {sorted(_LIST_PATHS)}, got {kind!r}") from None
44
+ if (page_size is None) != (page_num is None):
45
+ raise ValueError(
46
+ "page_size and page_num must be given together (backend ignores either alone)"
47
+ )
48
+ params = {
49
+ "orderHeader": order_header,
50
+ "asc": None if asc is None else str(asc).lower(),
51
+ "pageSize": page_size,
52
+ "pageNum": page_num,
53
+ }
54
+ return path, {k: v for k, v in params.items() if v is not None}, filters
55
+
56
+
57
+ def _create_body(
58
+ name: str,
59
+ description: str,
60
+ obligation_id: int | None,
61
+ dataflow_type: str,
62
+ fields: dict[str, Any] | None,
63
+ ) -> dict[str, Any]:
64
+ # What the web app sends (DataflowRepository.create); `releasable` is forced
65
+ # to true server side anyway.
66
+ body: dict[str, Any] = {
67
+ "name": name,
68
+ "description": description,
69
+ "type": dataflow_type,
70
+ "releasable": True,
71
+ }
72
+ if obligation_id is not None:
73
+ body["obligation"] = {"obligationId": obligation_id}
74
+ clash = sorted(set(fields or {}) & {"name", "description", "type", "obligation"})
75
+ if clash:
76
+ raise ValueError(f"pass {clash} as arguments, not in fields")
77
+ body.update(fields or {})
78
+ return body
79
+
80
+
81
+ def _created_id(response: httpx.Response) -> int:
82
+ # ResponseEntity<String> holding the new id; tolerate a JSON-quoted string.
83
+ text = response.text.strip().strip('"')
84
+ if not text.isdigit():
85
+ raise ReportnetAPIError(
86
+ f"POST /dataflow answered {response.status_code} without a dataflow id: {text[:200]!r}",
87
+ status_code=response.status_code,
88
+ response_body=response.text,
89
+ request=response.request,
90
+ response=response,
91
+ )
92
+ return int(text)
93
+
94
+
95
+ def _json_or_none(response: httpx.Response) -> dict[str, Any] | None:
96
+ # The backend swallows EEAException and returns null -> an empty 200 body.
97
+ if not response.content.strip():
98
+ return None
99
+ result: dict[str, Any] = response.json()
100
+ return result
101
+
102
+
103
+ class DataflowResource:
104
+ def __init__(self, client: ReportnetClient) -> None:
105
+ self._client = client
106
+
107
+ def dataflows(
108
+ self,
109
+ kind: DataflowKind = "reporting",
110
+ *,
111
+ filters: dict[str, str] | None = None,
112
+ order_header: str | None = None,
113
+ asc: bool | None = None,
114
+ page_size: int | None = None,
115
+ page_num: int | None = None,
116
+ ) -> dict[str, Any]:
117
+ """POST /dataflow/{getDataflows,referenceDataflows,businessDataflows,
118
+ citizenScienceDataflows}: dataflows visible to the logged user.
119
+
120
+ Returns the `PaginatedDataflowVO` dict: `dataflows`, `totalRecords`,
121
+ `filteredRecords`. Backend rule is `isAuthenticated()`; an ApiKey
122
+ signs in as the key's owner, so it lists the owner's dataflows.
123
+
124
+ `asc=None` omits the param, which the backend treats as `False`: with
125
+ `order_header` set that is a descending sort. Paging needs both
126
+ `page_size` and `page_num` (0-based); giving only one raises
127
+ `ValueError`. A backend-side failure comes back as an empty 200 page,
128
+ indistinguishable from "no dataflows".
129
+ """
130
+ path, params, body = _list_request(kind, filters, order_header, asc, page_size, page_num)
131
+ response = self._client.request("POST", path, params=params, json=body)
132
+ result: dict[str, Any] = response.json()
133
+ return result
134
+
135
+ def dataflow_datasets(
136
+ self, dataflow_id: int, *, provider_id: int | None = None
137
+ ) -> dict[str, Any] | None:
138
+ """GET /dataflow/v1/{dataflowId}: the dataflow with its datasets
139
+ (`designDatasets`, `reportingDatasets`, `dataCollections`,
140
+ `euDatasets`, `referenceDatasets`, `testDatasets`).
141
+
142
+ Reporters must pass `provider_id`. Requires a dataflow role (or a
143
+ matching ApiKey / data custodian-steward reference access).
144
+
145
+ Returns `None` when the backend answers 200 with an empty body (it
146
+ swallows its own errors, e.g. for an unknown dataflow).
147
+ """
148
+ params = {} if provider_id is None else {"providerId": provider_id}
149
+ response = self._client.request("GET", f"/dataflow/v1/{dataflow_id}", params=params)
150
+ return _json_or_none(response)
151
+
152
+ def create_dataflow(
153
+ self,
154
+ name: str,
155
+ description: str,
156
+ *,
157
+ obligation_id: int | None = None,
158
+ dataflow_type: DataflowType = "REPORTING",
159
+ fields: dict[str, Any] | None = None,
160
+ ) -> int:
161
+ """POST /dataflow: create a dataflow and return its new id.
162
+
163
+ `DataflowControllerImpl#createDataFlow`, body a `DataFlowVO`. Requires
164
+ the user role `DATA_CUSTODIAN`, `DATA_STEWARD`, `DATA_REQUESTER` or
165
+ `ADMIN` (a login token; an ApiKey carries no such role). `name` and
166
+ `description` must not be blank, and every type but `REFERENCE` needs
167
+ `obligation_id` (a ROD obligation id), else `400`. `BUSINESS` needs an
168
+ admin (`401` otherwise) plus `dataProviderGroupId`/`fmeUserId` in
169
+ `fields`. `fields` adds other `DataFlowVO` keys as-is (e.g.
170
+ `deadlineDate`, which must be after today for non-reference types);
171
+ `name`, `description`, `type` or `obligation` in it raise `ValueError`.
172
+ A 200 whose body is not an id raises `ReportnetAPIError`.
173
+
174
+ The dataflow starts in `DESIGN` status, with the caller as its
175
+ custodian. A name already used by any dataflow (case-insensitive)
176
+ answers `500` "There was an unknown error creating the dataflow."
177
+ """
178
+ body = _create_body(name, description, obligation_id, dataflow_type, fields)
179
+ response = self._client.request("POST", "/dataflow", json=body)
180
+ return _created_id(response)
181
+
182
+ def delete_dataflow(self, dataflow_id: int) -> None:
183
+ """DELETE /dataflow/{dataflowId}: delete a dataflow with its design
184
+ datasets, documents and representatives.
185
+
186
+ `DataflowControllerImpl#deleteDataFlow`. Requires `DATAFLOW_STEWARD` or
187
+ `DATAFLOW_CUSTODIAN` on the dataflow. `423` while a schema import or
188
+ a schema copy into it is running. The backend logs and swallows its
189
+ own failures (`DataflowServiceImpl#deleteDataFlow`), so a 200 does not
190
+ prove the dataflow is gone: `dataflow_datasets()` afterwards does.
191
+ """
192
+ self._client.request("DELETE", f"/dataflow/{dataflow_id}")
193
+
194
+
195
+ class AsyncDataflowResource:
196
+ def __init__(self, client: AsyncReportnetClient) -> None:
197
+ self._client = client
198
+
199
+ async def dataflows(
200
+ self,
201
+ kind: DataflowKind = "reporting",
202
+ *,
203
+ filters: dict[str, str] | None = None,
204
+ order_header: str | None = None,
205
+ asc: bool | None = None,
206
+ page_size: int | None = None,
207
+ page_num: int | None = None,
208
+ ) -> dict[str, Any]:
209
+ """Async counterpart of DataflowResource.dataflows."""
210
+ path, params, body = _list_request(kind, filters, order_header, asc, page_size, page_num)
211
+ response = await self._client.request("POST", path, params=params, json=body)
212
+ result: dict[str, Any] = response.json()
213
+ return result
214
+
215
+ async def dataflow_datasets(
216
+ self, dataflow_id: int, *, provider_id: int | None = None
217
+ ) -> dict[str, Any] | None:
218
+ """Async counterpart of DataflowResource.dataflow_datasets."""
219
+ params = {} if provider_id is None else {"providerId": provider_id}
220
+ response = await self._client.request("GET", f"/dataflow/v1/{dataflow_id}", params=params)
221
+ return _json_or_none(response)
222
+
223
+ async def create_dataflow(
224
+ self,
225
+ name: str,
226
+ description: str,
227
+ *,
228
+ obligation_id: int | None = None,
229
+ dataflow_type: DataflowType = "REPORTING",
230
+ fields: dict[str, Any] | None = None,
231
+ ) -> int:
232
+ """Async counterpart of DataflowResource.create_dataflow."""
233
+ body = _create_body(name, description, obligation_id, dataflow_type, fields)
234
+ response = await self._client.request("POST", "/dataflow", json=body)
235
+ return _created_id(response)
236
+
237
+ async def delete_dataflow(self, dataflow_id: int) -> None:
238
+ """Async counterpart of DataflowResource.delete_dataflow."""
239
+ await self._client.request("DELETE", f"/dataflow/{dataflow_id}")
@@ -0,0 +1,274 @@
1
+ # Generated from spec/api-docs.json by scripts/generate_resources.py.
2
+ # Do not edit by hand.
3
+
4
+ from __future__ import annotations
5
+
6
+ import os
7
+ from typing import TYPE_CHECKING
8
+
9
+ from .._core import stream_upload_file
10
+ from ..models import generated
11
+
12
+ if TYPE_CHECKING:
13
+ from ..async_client import AsyncReportnetClient
14
+ from ..client import ReportnetClient
15
+
16
+
17
+ class DatasetSchemaResource:
18
+ def __init__(self, client: ReportnetClient) -> None:
19
+ self._client = client
20
+
21
+ def export_field_schemas(
22
+ self,
23
+ dataset_schema_id: str,
24
+ dataset_id: int | None = None,
25
+ table_schema_id: str | None = None,
26
+ ) -> str:
27
+ """Allowed roles: CUSTODIAN, STEWARD, EDITOR WRITE"""
28
+ params = {"datasetId": dataset_id, "tableSchemaId": table_schema_id}
29
+ params = {k: v for k, v in params.items() if v is not None}
30
+ url = f"/dataschema/v1/{dataset_schema_id}/exportFieldSchemas"
31
+ response = self._client.request(
32
+ "GET", url, params=params, headers={"Accept": "application/octet-stream, */*;q=0.1"}
33
+ )
34
+ return response.text
35
+
36
+ def export_field_schemas_from_dataset(
37
+ self,
38
+ dataset_id: int,
39
+ ) -> str:
40
+ """Allowed roles: CUSTODIAN, STEWARD, EDITOR WRITE"""
41
+ params = None
42
+ url = f"/dataschema/v1/dataset/{dataset_id}/exportFieldSchemas"
43
+ response = self._client.request(
44
+ "GET", url, params=params, headers={"Accept": "application/octet-stream, */*;q=0.1"}
45
+ )
46
+ return response.text
47
+
48
+ def find_data_schema_by_dataset_id(
49
+ self,
50
+ dataset_id: int,
51
+ ) -> generated.DataSetSchemaVO:
52
+ """Allowed roles:
53
+
54
+ Reporting dataset: STEWARD, LEAD REPORTER, CUSTODIAN, OBSERVER, REPORTER WRITE, REPORTER READ, NATIONAL COORDINATOR, STEWARD SUPPORT
55
+
56
+ Data collection: CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT
57
+
58
+ Test dataset: CUSTODIAN, STEWARD ,OBSERVER, STEWARD SUPPORT
59
+
60
+ Reference dataset: CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT
61
+
62
+ Design dataset: CUSTODIAN, STEWARD, EDITOR READ, EDITOR WRITE
63
+
64
+ EU dataset: CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT"""
65
+ params = None
66
+ url = f"/dataschema/v1/datasetId/{dataset_id}"
67
+ response = self._client.request("GET", url, params=params)
68
+ return generated.DataSetSchemaVO.model_validate(response.json())
69
+
70
+ def get_simple_schema(
71
+ self,
72
+ dataset_id: int,
73
+ dataflow_id: int | None = None,
74
+ provider_id: int | None = None,
75
+ ) -> generated.SimpleDatasetSchemaVO:
76
+ """Allowed roles:
77
+
78
+ Reporting dataset: STEWARD, LEAD REPORTER, CUSTODIAN, REPORTER WRITE, REPORTER READ, NATIONAL COORDINATOR
79
+
80
+ Data collection: CUSTODIAN, STEWARD
81
+
82
+ Test dataset: CUSTODIAN, STEWARD, STEWARD SUPPORT
83
+
84
+ Design dataset: CUSTODIAN, STEWARD, EDITOR WRITE
85
+
86
+ EU dataset: CUSTODIAN, STEWARD"""
87
+ params = {"dataflowId": dataflow_id, "providerId": provider_id}
88
+ params = {k: v for k, v in params.items() if v is not None}
89
+ url = f"/dataschema/v1/getSimpleSchema/dataset/{dataset_id}"
90
+ response = self._client.request("GET", url, params=params)
91
+ return generated.SimpleDatasetSchemaVO.model_validate(response.json())
92
+
93
+ def get_table_schemas_ids(
94
+ self,
95
+ dataset_id: int,
96
+ dataflow_id: int | None = None,
97
+ provider_id: int | None = None,
98
+ ) -> list[generated.TableSchemaIdNameVO]:
99
+ """Allowed roles:
100
+
101
+ Reporting dataset: STEWARD, LEAD REPORTER, CUSTODIAN, REPORTER WRITE, REPORTER READ, NATIONAL COORDINATOR
102
+
103
+ Data collection: CUSTODIAN, STEWARD
104
+
105
+ Test dataset: CUSTODIAN, STEWARD, STEWARD SUPPORT
106
+
107
+ Reference dataset: CUSTODIAN, STEWARD
108
+
109
+ Design dataset: CUSTODIAN, STEWARD, EDITOR WRITE
110
+
111
+ EU dataset: CUSTODIAN, STEWARD"""
112
+ params = {"dataflowId": dataflow_id, "providerId": provider_id}
113
+ params = {k: v for k, v in params.items() if v is not None}
114
+ url = f"/dataschema/v1/getTableSchemasIds/{dataset_id}"
115
+ response = self._client.request("GET", url, params=params)
116
+ return [generated.TableSchemaIdNameVO.model_validate(item) for item in response.json()]
117
+
118
+ def import_field_schemas(
119
+ self,
120
+ dataset_schema_id: str,
121
+ file: str | os.PathLike[str],
122
+ dataset_id: int | None = None,
123
+ replace: bool | None = None,
124
+ table_schema_id: str | None = None,
125
+ ) -> None:
126
+ """Allowed roles: CUSTODIAN, STEWARD, EDITOR WRITE"""
127
+ params = {"datasetId": dataset_id, "replace": replace, "tableSchemaId": table_schema_id}
128
+ params = {k: v for k, v in params.items() if v is not None}
129
+ url = f"/dataschema/v1/{dataset_schema_id}/importFieldSchemas"
130
+ with stream_upload_file("file", file) as files:
131
+ self._client.request("POST", url, params=params, files=files)
132
+ return None
133
+
134
+ def update_manually_editable_by_dataset_id(
135
+ self,
136
+ dataset_id: int,
137
+ manually_editable: bool,
138
+ ) -> None:
139
+ """updateManuallyEditableByDatasetId"""
140
+ params = {"manuallyEditable": manually_editable}
141
+ params = {k: v for k, v in params.items() if v is not None}
142
+ url = f"/dataschema/updateManuallyEditable/{dataset_id}"
143
+ self._client.request("PUT", url, params=params)
144
+ return None
145
+
146
+
147
+ class AsyncDatasetSchemaResource:
148
+ def __init__(self, client: AsyncReportnetClient) -> None:
149
+ self._client = client
150
+
151
+ async def export_field_schemas(
152
+ self,
153
+ dataset_schema_id: str,
154
+ dataset_id: int | None = None,
155
+ table_schema_id: str | None = None,
156
+ ) -> str:
157
+ """Allowed roles: CUSTODIAN, STEWARD, EDITOR WRITE"""
158
+ params = {"datasetId": dataset_id, "tableSchemaId": table_schema_id}
159
+ params = {k: v for k, v in params.items() if v is not None}
160
+ url = f"/dataschema/v1/{dataset_schema_id}/exportFieldSchemas"
161
+ response = await self._client.request(
162
+ "GET", url, params=params, headers={"Accept": "application/octet-stream, */*;q=0.1"}
163
+ )
164
+ return response.text
165
+
166
+ async def export_field_schemas_from_dataset(
167
+ self,
168
+ dataset_id: int,
169
+ ) -> str:
170
+ """Allowed roles: CUSTODIAN, STEWARD, EDITOR WRITE"""
171
+ params = None
172
+ url = f"/dataschema/v1/dataset/{dataset_id}/exportFieldSchemas"
173
+ response = await self._client.request(
174
+ "GET", url, params=params, headers={"Accept": "application/octet-stream, */*;q=0.1"}
175
+ )
176
+ return response.text
177
+
178
+ async def find_data_schema_by_dataset_id(
179
+ self,
180
+ dataset_id: int,
181
+ ) -> generated.DataSetSchemaVO:
182
+ """Allowed roles:
183
+
184
+ Reporting dataset: STEWARD, LEAD REPORTER, CUSTODIAN, OBSERVER, REPORTER WRITE, REPORTER READ, NATIONAL COORDINATOR, STEWARD SUPPORT
185
+
186
+ Data collection: CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT
187
+
188
+ Test dataset: CUSTODIAN, STEWARD ,OBSERVER, STEWARD SUPPORT
189
+
190
+ Reference dataset: CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT
191
+
192
+ Design dataset: CUSTODIAN, STEWARD, EDITOR READ, EDITOR WRITE
193
+
194
+ EU dataset: CUSTODIAN, STEWARD, OBSERVER, STEWARD SUPPORT"""
195
+ params = None
196
+ url = f"/dataschema/v1/datasetId/{dataset_id}"
197
+ response = await self._client.request("GET", url, params=params)
198
+ return generated.DataSetSchemaVO.model_validate(response.json())
199
+
200
+ async def get_simple_schema(
201
+ self,
202
+ dataset_id: int,
203
+ dataflow_id: int | None = None,
204
+ provider_id: int | None = None,
205
+ ) -> generated.SimpleDatasetSchemaVO:
206
+ """Allowed roles:
207
+
208
+ Reporting dataset: STEWARD, LEAD REPORTER, CUSTODIAN, REPORTER WRITE, REPORTER READ, NATIONAL COORDINATOR
209
+
210
+ Data collection: CUSTODIAN, STEWARD
211
+
212
+ Test dataset: CUSTODIAN, STEWARD, STEWARD SUPPORT
213
+
214
+ Design dataset: CUSTODIAN, STEWARD, EDITOR WRITE
215
+
216
+ EU dataset: CUSTODIAN, STEWARD"""
217
+ params = {"dataflowId": dataflow_id, "providerId": provider_id}
218
+ params = {k: v for k, v in params.items() if v is not None}
219
+ url = f"/dataschema/v1/getSimpleSchema/dataset/{dataset_id}"
220
+ response = await self._client.request("GET", url, params=params)
221
+ return generated.SimpleDatasetSchemaVO.model_validate(response.json())
222
+
223
+ async def get_table_schemas_ids(
224
+ self,
225
+ dataset_id: int,
226
+ dataflow_id: int | None = None,
227
+ provider_id: int | None = None,
228
+ ) -> list[generated.TableSchemaIdNameVO]:
229
+ """Allowed roles:
230
+
231
+ Reporting dataset: STEWARD, LEAD REPORTER, CUSTODIAN, REPORTER WRITE, REPORTER READ, NATIONAL COORDINATOR
232
+
233
+ Data collection: CUSTODIAN, STEWARD
234
+
235
+ Test dataset: CUSTODIAN, STEWARD, STEWARD SUPPORT
236
+
237
+ Reference dataset: CUSTODIAN, STEWARD
238
+
239
+ Design dataset: CUSTODIAN, STEWARD, EDITOR WRITE
240
+
241
+ EU dataset: CUSTODIAN, STEWARD"""
242
+ params = {"dataflowId": dataflow_id, "providerId": provider_id}
243
+ params = {k: v for k, v in params.items() if v is not None}
244
+ url = f"/dataschema/v1/getTableSchemasIds/{dataset_id}"
245
+ response = await self._client.request("GET", url, params=params)
246
+ return [generated.TableSchemaIdNameVO.model_validate(item) for item in response.json()]
247
+
248
+ async def import_field_schemas(
249
+ self,
250
+ dataset_schema_id: str,
251
+ file: str | os.PathLike[str],
252
+ dataset_id: int | None = None,
253
+ replace: bool | None = None,
254
+ table_schema_id: str | None = None,
255
+ ) -> None:
256
+ """Allowed roles: CUSTODIAN, STEWARD, EDITOR WRITE"""
257
+ params = {"datasetId": dataset_id, "replace": replace, "tableSchemaId": table_schema_id}
258
+ params = {k: v for k, v in params.items() if v is not None}
259
+ url = f"/dataschema/v1/{dataset_schema_id}/importFieldSchemas"
260
+ with stream_upload_file("file", file) as files:
261
+ await self._client.request("POST", url, params=params, files=files)
262
+ return None
263
+
264
+ async def update_manually_editable_by_dataset_id(
265
+ self,
266
+ dataset_id: int,
267
+ manually_editable: bool,
268
+ ) -> None:
269
+ """updateManuallyEditableByDatasetId"""
270
+ params = {"manuallyEditable": manually_editable}
271
+ params = {k: v for k, v in params.items() if v is not None}
272
+ url = f"/dataschema/updateManuallyEditable/{dataset_id}"
273
+ await self._client.request("PUT", url, params=params)
274
+ return None