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,307 @@
1
+ Metadata-Version: 2.5
2
+ Name: reportnet-api
3
+ Version: 0.1.0
4
+ Summary: Python library for the EEA Reportnet 3 REST API
5
+ Project-URL: Homepage, https://github.com/eeadata/reportnet-api-python
6
+ Project-URL: Repository, https://github.com/eeadata/reportnet-api-python
7
+ Project-URL: Issues, https://github.com/eeadata/reportnet-api-python/issues
8
+ Author-email: Nikos Paximadakis <nikos.paximadakis@gmail.com>
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: api-client,jupyter,pandas,reportnet,rest-api
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Intended Audience :: Science/Research
15
+ Classifier: Operating System :: OS Independent
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Programming Language :: Python :: 3.14
21
+ Classifier: Topic :: Software Development :: Libraries
22
+ Classifier: Typing :: Typed
23
+ Requires-Python: >=3.11
24
+ Requires-Dist: httpx>=0.27
25
+ Requires-Dist: pydantic>=2
26
+ Provides-Extra: pandas
27
+ Requires-Dist: pandas>=2; extra == 'pandas'
28
+ Description-Content-Type: text/markdown
29
+
30
+ <p align="center">
31
+ <picture>
32
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/eeadata/reportnet-api-python/main/docs/assets/logo-dark.svg">
33
+ <img src="https://raw.githubusercontent.com/eeadata/reportnet-api-python/main/docs/assets/logo.svg" alt="reportnet-api for Python" width="420">
34
+ </picture>
35
+ </p>
36
+
37
+ # reportnet-api-python
38
+
39
+ Python library for the [EEA Reportnet 3](https://reportnet.europa.eu/)
40
+ REST API. Typed, resource-namespaced, sync and async, built on `httpx` and
41
+ Pydantic v2. The function reference is in `docs/reference/`.
42
+
43
+ > **Not an official EEA product.** An independent set of utilities for accessing the
44
+ > Reportnet 3 API, not developed or supported by the Reportnet team. For help with
45
+ > Reportnet itself, use the Reportnet helpdesk.
46
+
47
+ [![CI](https://github.com/eeadata/reportnet-api-python/actions/workflows/ci.yml/badge.svg)](https://github.com/eeadata/reportnet-api-python/actions/workflows/ci.yml)
48
+ [![Open the demo in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/eeadata/reportnet-api-python/blob/main/examples/try_it_demo.ipynb)
49
+
50
+ **Who it is for:** programmers (the typed clients), scientists in notebooks
51
+ (`reportnet_api.easy`, pandas), and FME users (plain Python, see
52
+ [docs/fme.md](https://github.com/eeadata/reportnet-api-python/blob/main/docs/fme.md)). **No credential yet?** `easy.demo_client()` answers from
53
+ fictional built-in data; start with the
54
+ [demo notebook](https://github.com/eeadata/reportnet-api-python/blob/main/examples/try_it_demo.ipynb). **Not sure which credential you need?**
55
+ [docs/credentials.md](https://github.com/eeadata/reportnet-api-python/blob/main/docs/credentials.md).
56
+
57
+ ## Install
58
+
59
+ ```
60
+ pip install reportnet-api # or: uv add reportnet-api
61
+ pip install "reportnet-api[pandas]" # with the pandas notebook helpers
62
+ ```
63
+
64
+ Python 3.11 or newer. The latest unreleased code: `pip install git+https://github.com/eeadata/reportnet-api-python`.
65
+
66
+ ## Notebooks and non-developers
67
+
68
+ `reportnet_api.easy` wraps the client for notebook use: credentials from
69
+ `REPORTNET_API_KEY`, and listings/tables returned as pandas DataFrames.
70
+
71
+ ```python
72
+ %pip install "reportnet-api[pandas]"
73
+
74
+ from reportnet_api.easy import connect, list_dataflows, list_datasets, read_table
75
+ client = connect() # or connect("<api key>"); a Bearer token: connect(tok, scheme="Bearer")
76
+ list_dataflows(client)
77
+ read_table(client, dataset_id=123, dataflow_id=1, table_name="MyTable")
78
+ ```
79
+
80
+ `connect_interactive()` asks for the key with a hidden prompt, `connect(token_provider=fn,
81
+ retry=True)` takes a refreshing token and retries transient errors (recipe in its
82
+ docstring), and `check_access(client, dataflow_id)` makes a few read-only calls to show
83
+ the credential kind, whether it is alive and whether the dataflow is reachable.
84
+
85
+ The waiting helpers (`import_file`, `export_to_file`, `export_table`, `read_tables`,
86
+ `wait_for_job`) take `progress=True` to show one updating status line (status, elapsed
87
+ seconds, page number), or `progress=fn` to receive an event dict per step; it is off by
88
+ default, and on a log or pipe it prints a line only when the status changes. A started
89
+ job can be kept as `Job.from_polling_url(client, answer)` (from `reportnet_api.jobs`): its
90
+ `.status` polls once and `.wait(progress=True)` waits. Ctrl-C while waiting stops only the
91
+ waiting and prints the job id; the job keeps running on the server and cannot be cancelled
92
+ from here.
93
+
94
+ Not sure which function you need? `reportnet_api.find("export")` searches every
95
+ method and helper by keyword, and `easy.guide()` prints a one-page cheat sheet.
96
+ Terms (dataflow, dataset, provider, job, ...) are in [docs/glossary.md](https://github.com/eeadata/reportnet-api-python/blob/main/docs/glossary.md).
97
+
98
+ Notebooks: [quickstart](https://github.com/eeadata/reportnet-api-python/blob/main/examples/quickstart.ipynb),
99
+ [export and upload](https://github.com/eeadata/reportnet-api-python/blob/main/examples/export_and_upload.ipynb),
100
+ [validation](https://github.com/eeadata/reportnet-api-python/blob/main/examples/validation.ipynb). `read_table` uses the
101
+ synchronous ETL export, whose access is credential-dependent (see `docs/live_testing_notes.md`).
102
+
103
+ ## Command line
104
+
105
+ `pip install` also adds a read-only `reportnet` command for schedulers and FME's system
106
+ caller: `reportnet dataflows`, `reportnet datasets <dataflow>`, `reportnet read <dataset>
107
+ <dataflow> --out table.csv`, `reportnet export <dataset> <dataflow> out.zip`,
108
+ `reportnet find <words>`. The credential comes from `REPORTNET_API_KEY`, never from an
109
+ argument; `--demo` uses fictional data. There is deliberately no command that writes or
110
+ deletes data. Without pandas, use `easy.read_records()` (plain dicts) instead of
111
+ `read_table()`.
112
+
113
+ ## Reference
114
+
115
+ Per-function reference (arguments, required ReportNet rights, live-tested caveats):
116
+ [docs/reference/index.md](https://github.com/eeadata/reportnet-api-python/blob/main/docs/reference/index.md), also built as a searchable site by
117
+ `mkdocs` (see `mkdocs.yml`). Changes are listed in [CHANGELOG.md](https://github.com/eeadata/reportnet-api-python/blob/main/CHANGELOG.md).
118
+
119
+ ## Auth
120
+
121
+ There's no login/token-acquisition flow — the caller supplies a valid credential:
122
+ a Bearer JWT or a dataflow-scoped ApiKey, either as a static string or as a zero-arg
123
+ callable for custom refresh logic:
124
+
125
+ ```python
126
+ client = ReportnetClient(base_url="https://api.reportnet.europa.eu", token="<jwt>")
127
+
128
+ # or, for a token that can refresh itself:
129
+ client = ReportnetClient(base_url="https://api.reportnet.europa.eu", token=my_token_provider)
130
+ ```
131
+
132
+ Every request attaches `Authorization: <scheme> <token>`. The scheme defaults to
133
+ `Bearer`; pass `token_scheme="ApiKey"` for an API key (`easy.connect` detects which
134
+ one you gave it). The credential is only ever sent to the host of `base_url`: a
135
+ request or job URL pointing at another origin raises `ValueError` instead of being sent.
136
+
137
+ ## Calls that write or delete
138
+
139
+ Many methods change data: imports, deletes, `import_field_schemas`, validations, and
140
+ the generated `POST`/`PUT`/`DELETE` methods. Point the client at a dataflow you own.
141
+ `easy.import_file(..., replace=True)` deletes existing data first (it emptied the
142
+ dataset's other tables too when live-tested) and therefore needs `confirm=True`;
143
+ `easy.import_file` also checks a `.csv`'s name and header against the dataset schema
144
+ before uploading. The generated delete methods have no such guard. Reportnet answers can
145
+ contain personal data (for example lead reporters' emails): handle them accordingly.
146
+
147
+ ## Quickstart — sync
148
+
149
+ ```python
150
+ from reportnet_api import ReportnetClient
151
+
152
+ with ReportnetClient(base_url="https://api.reportnet.europa.eu", token="<jwt>") as client:
153
+ schema = client.dataset_schema.find_data_schema_by_dataset_id(dataset_id=123)
154
+ client.datasets.import_file_data(dataset_id=123, file="local/path.csv") # WRITES data
155
+ ```
156
+
157
+ ## Quickstart — async
158
+
159
+ ```python
160
+ import asyncio
161
+ from reportnet_api import AsyncReportnetClient
162
+
163
+ async def main() -> None:
164
+ async with AsyncReportnetClient(
165
+ base_url="https://api.reportnet.europa.eu", token="<jwt>"
166
+ ) as client:
167
+ schema = await client.dataset_schema.find_data_schema_by_dataset_id(dataset_id=123)
168
+ await client.datasets.import_file_data(dataset_id=123, file="local/path.csv") # WRITES data
169
+
170
+ asyncio.run(main())
171
+ ```
172
+
173
+ ## File upload/download
174
+
175
+ Upload and download are path-based and streaming, not in-memory bytes:
176
+
177
+ ```python
178
+ client.datasets.import_file_data(dataset_id=123, file="local/path.csv") # WRITES data
179
+ client.dataset_snapshot.download_historic_releases_csv(
180
+ dataflow_id=1, dataset_id=123, file_name="releases.csv", dest="local/out.csv",
181
+ )
182
+
183
+ # Full dataflow schema export ZIP (.schema/.qcrules/.unique/.integrity/
184
+ # .extintegrations per dataset, plus datasetSchemaNames.names/
185
+ # datasetSchemaIds.ids) — same format the Reportnet UI's schema export
186
+ # produces. Requires DATAFLOW_CUSTODIAN or DATAFLOW_STEWARD on the dataflow.
187
+ client.dataset_schema.export_dataflow_schemas_zip(
188
+ dataflow_id=4321, dest="local/dataflow_4321_schemas.zip",
189
+ )
190
+ ```
191
+
192
+ ## Errors
193
+
194
+ HTTP errors raise a typed exception (`AuthenticationError`, `ForbiddenError`,
195
+ `NotFoundError`, `ValidationError`, `LockedError` (423: another operation holds
196
+ a lock), `TooManyRequestsError` (429, with a `retry_after` property),
197
+ `ServerError`, or the base `ReportnetAPIError` for unmapped status codes).
198
+ Every exception carries
199
+ `status_code`, `response_body`, and the originating `request`/`response`:
200
+
201
+ ```python
202
+ from reportnet_api import NotFoundError
203
+
204
+ try:
205
+ client.datasets.check_import_process(dataset_id=999)
206
+ except NotFoundError as e:
207
+ print(e.status_code, e.response_body)
208
+ print(e) # includes the server's JSON `message` (first 200 chars)
209
+ print(e.explain()) # plain-language cause and what to try
210
+ ```
211
+
212
+ `str(e)` ends with the server's `message` when the body is JSON (or a short
213
+ text snippet otherwise); the full body stays on `response_body`. `explain()`
214
+ adds a likely cause for patterns seen live (revoked ApiKey surfacing as a 500,
215
+ 423 import lock, ETL 403 for Bearer, ApiKey on a Custodian-only route). In
216
+ `easy`, `list_datasets` raises `LookupError` on an empty 200 (the backend's
217
+ answer for an unknown dataflow or no access) instead of returning no rows.
218
+
219
+ ## Retries (opt-in)
220
+
221
+ By default nothing is retried. Pass a `RetryPolicy` to either client to retry
222
+ transient failures with exponential backoff:
223
+
224
+ ```python
225
+ from reportnet_api import ReportnetClient, RetryPolicy
226
+
227
+ client = ReportnetClient(base_url=..., token=..., retry=RetryPolicy(retries=3))
228
+ ```
229
+
230
+ It retries 429/502/503/504 for GET requests only (honouring `Retry-After`, as
231
+ seconds or an HTTP date, capped by `max_delay`), connection failures and pool
232
+ timeouts for any method (the request was never sent), and other transient
233
+ transport errors for GET only. It never retries 500 (those were deterministic in
234
+ live testing), 423 (wait for the other job, e.g. with `wait_for_job`),
235
+ permanent errors such as a malformed `base_url`, or requests whose body can't be
236
+ replayed (file uploads, streamed bodies). Downloads (`download()`) aren't retried.
237
+
238
+ ## Third-party material
239
+
240
+ `spec/api-docs.json` is a snapshot of the Reportnet 3 API's own Swagger description, used
241
+ to generate the models and method stubs. Its metadata declares "Apache 2.0" (and
242
+ `urn:tos`), which are Springfox's defaults rather than a statement about this repository;
243
+ the code here is MIT-licensed (see `LICENSE`).
244
+
245
+ ## Development
246
+
247
+ ```
248
+ uv sync --all-groups # install deps + dev tools
249
+ uv run ruff check . # lint
250
+ uv run mypy reportnet_api
251
+ uv run pytest
252
+ ```
253
+
254
+ Resources (`reportnet_api/resources/*.py`) and models
255
+ (`reportnet_api/models/generated.py`) are generated, not hand-written — see
256
+ [CONTRIBUTING.md](https://github.com/eeadata/reportnet-api-python/blob/main/CONTRIBUTING.md) before touching either, and [SECURITY.md](https://github.com/eeadata/reportnet-api-python/blob/main/SECURITY.md)
257
+ to report a security problem.
258
+
259
+ ## Testing against a live API
260
+
261
+ `uv run pytest` (above) covers everything with mocked HTTP — no network
262
+ calls, safe to run anytime. To check a real token/environment actually
263
+ works end to end, use `scripts/smoke_test.py`:
264
+
265
+ ```
266
+ uv run python3 scripts/smoke_test.py --token "<your-jwt>" \
267
+ --dataset-id <real_id> [--dataflow-id <real_id>]
268
+ ```
269
+
270
+ It runs a handful of read-only calls across every resource
271
+ (`check_import_process`, `find_data_schema_by_dataset_id`,
272
+ plus 3 more if `--dataflow-id` is given) and
273
+ prints one line per check:
274
+
275
+ - `PASS` — call succeeded, response parsed into the expected model
276
+ - `WARN` — got a 404 (endpoint reached, but nothing matches that id —
277
+ check `--dataset-id`/`--dataflow-id`)
278
+ - `FAIL` — a real problem: auth/validation/server error, or an unexpected
279
+ exception (e.g. a response the client mis-parses)
280
+
281
+ It's read-only by design (nothing here writes, uploads, or deletes) and
282
+ isn't run in CI — it's a manual tool for sanity-checking a deployment.
283
+
284
+ A few things worth knowing before poking the real API:
285
+
286
+ - Start with `GET`-only calls before anything that writes or deletes data.
287
+ - For upload (`import_file_data`, etc.) or download endpoints, test
288
+ against a dataset you don't mind touching — uploads genuinely write
289
+ data.
290
+ - `get_attachment` and `download_imported_file` take a `dest=` and stream
291
+ to it like the other download endpoints.
292
+ - `/private/*` operations in the spec are not exposed (the gateway 404s
293
+ them); see `docs/removed_private_endpoints.md`.
294
+
295
+ For interactively exploring any of the 48 generated endpoints against a real API
296
+ instead of writing one-off scripts, there's a local-only Streamlit UI —
297
+ `tools/streamlit_app.py`. It introspects the resource classes at runtime
298
+ (no per-method hardcoding) to build a resource/method picker with an
299
+ auto-generated parameter form. It is **not** part of the published package
300
+ (the wheel only ever contains `reportnet_api/`, per
301
+ `[tool.hatch.build.targets.wheel]` in `pyproject.toml`) and `streamlit`
302
+ lives in its own `uv` dependency group, not `[project.dependencies]`, so
303
+ `pip install reportnet-api` never pulls it in:
304
+
305
+ ```
306
+ uv run --group ui streamlit run tools/streamlit_app.py
307
+ ```
@@ -0,0 +1,33 @@
1
+ reportnet_api/__init__.py,sha256=zeMvJnYwLSapyCAOm4WvwA-nAWd6FcMa5aqz4xhpTuY,906
2
+ reportnet_api/_auth.py,sha256=-HWmj5JpUV0WrRbG8fYRMXa47Ea2eBSE20sl0A3wHtE,877
3
+ reportnet_api/_core.py,sha256=emeLSxTBylA87L7fVm_o1pLXIiHoUbtYyfbCY6akz88,8493
4
+ reportnet_api/_exceptions.py,sha256=TCPJqVijFcxe8444IgSUEIt03znNbLVblmnnCjVKsdU,9065
5
+ reportnet_api/async_client.py,sha256=BzF8zjMh1A4_BoJyMq8Y8QbhzElfhcaHbXbIoaOWzpY,4655
6
+ reportnet_api/cli.py,sha256=Wbs0_8gQzKqBnsKK268EEyCGfx9brgs0tNOaD396MuA,8597
7
+ reportnet_api/client.py,sha256=upU9iua-NjVViGecF4icK7ywnlODbPeDSj427nyFI6w,4439
8
+ reportnet_api/demo.py,sha256=Yv0qtnvc9p_oRxcQ2gNU9XAz215iB4zhr8eKCsU1yNM,5750
9
+ reportnet_api/discover.py,sha256=7Kspoj91iiJrHYg4vvJ9Qc9V0W19IrsB0xjWcV11LrQ,3769
10
+ reportnet_api/easy.py,sha256=AAqTercz5RhM6ZQi_lPp9uL89VN5SdovlDXkIWYgW5M,56337
11
+ reportnet_api/handles.py,sha256=R1LeKr-sdEIMhA9iif1x5qHTBfv0eYy0QxxlS80c2Rk,14162
12
+ reportnet_api/jobs.py,sha256=O8DnmqqZTX7sGD0BRZhazXikLr-o3U_gW3OtB3QjKoU,14656
13
+ reportnet_api/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
14
+ reportnet_api/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
15
+ reportnet_api/models/generated.py,sha256=fEtKUtjtcMqgvlj2peGFT38laU2vQqDO4rQ2A2Y2uAU,14765
16
+ reportnet_api/resources/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
17
+ reportnet_api/resources/dataflow_ext.py,sha256=nKCnhcDc_BrBxkgdCC4vum_8-_CVK_9AE1d0dBHH3m8,9637
18
+ reportnet_api/resources/dataset_schema.py,sha256=rv1s6D9dVmaoKjY7754UipJbdP3c3j34AwBz1hRIE8s,10508
19
+ reportnet_api/resources/dataset_schema_ext.py,sha256=C2oIaEMPVtTsuzlu9RGYHHb9X-SOXkudJ9qHjGOlpcU,25337
20
+ reportnet_api/resources/dataset_snapshot.py,sha256=dVprcwEvcfnsKkZd9UXyJp2zYYn7EcxurbuYYA4rjz0,6147
21
+ reportnet_api/resources/datasets.py,sha256=M8-XpFmFaFLNHxMdm5A9FN9SYpg3MLxb2cPWIcbt4s0,67965
22
+ reportnet_api/resources/datasets_ext.py,sha256=C3lu5ZGe1CcGUdSAJF5kg2Zw5kiXSBjxD98uhgpzLyY,39086
23
+ reportnet_api/resources/eu_datasets.py,sha256=WJKogxiTy-nPe4NNQrgCk4AC5iumz4WMv0FHaWpTvuM,1387
24
+ reportnet_api/resources/reference_dataset_ext.py,sha256=_t43WFhydYg52CMNNyRTT_OKeyg8BWRSjDksjkGTByI,3438
25
+ reportnet_api/resources/release_receipts.py,sha256=SxTsQ4LpcCONMs7NDvA6JgY_5-mn9g0cLKuY7bjQziU,3995
26
+ reportnet_api/resources/representative_ext.py,sha256=A5_m_f1PMe1Q20JSdVcNnLeME5pz9e1XpScVc4uh5b0,18581
27
+ reportnet_api/resources/user_ext.py,sha256=MoifRNTo_yO0U5RK_16SnGSfCNdy3OpYFDI8YAGeXrQ,1959
28
+ reportnet_api/resources/validation_ext.py,sha256=BYs0LwSrb8-WICu7a9CecbIN4QX9qG-Ve-f0HntOO98,18056
29
+ reportnet_api-0.1.0.dist-info/METADATA,sha256=G96bXiLEJ4CpjCngOhSm9eF4yM1MfnDcjbRVRSYrbQ8,14434
30
+ reportnet_api-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
31
+ reportnet_api-0.1.0.dist-info/entry_points.txt,sha256=hkeYKbpzy2wQeYovDBO1hagQpqPf6LNZfMZYnhe5Rtc,53
32
+ reportnet_api-0.1.0.dist-info/licenses/LICENSE,sha256=sRvidOq8mMiltggy7GBLH3yhblKC7fpQsH92Jg6wQL4,1090
33
+ reportnet_api-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ reportnet = reportnet_api.cli:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 European Environment Agency (EEA)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.