From 5d3e09324ed1da80867eb66daab1da16fc6b7075 Mon Sep 17 00:00:00 2001 From: Nikolaos Paximadakis Date: Fri, 20 Nov 2026 11:45:31 +0100 Subject: [PATCH 1/2] validate_and_wait: poll the validation job; stop on failure notifications The backend's current line (MasterOneVersion) answers addValidationJob with the new job's id (the bare `44570` seen live). start_validation now returns it (None for an empty body) and takes optional dataflow_id/provider_id, which enable the route's ApiKey check there. validate_and_wait polls the job via pollForJobStatus, so a FAILED/REFUSED/CANCELED run raises JobError with the job's status and info at once instead of timing out; a FINISHED job with an info text warns. Without a job id, or when polling is refused (ApiKey-only on MasterDataLakes), it falls back to the notification wait, which now also ends on VALIDATION_REFUSED/CANCELED/FAILED_* notifications. Dataset.validate passes the handle's provider_id. Read from the backend source; not yet run live. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 12 ++ docs/reference/easy.md | 39 +++-- docs/reference/handles.md | 1 + docs/reference/validation.md | 27 ++-- reportnet_api/easy.py | 165 ++++++++++++++++++---- reportnet_api/handles.py | 2 + reportnet_api/resources/validation_ext.py | 69 ++++++--- tests/test_easy.py | 91 ++++++++++++ tests/test_handles.py | 2 +- tests/test_validation.py | 21 ++- 10 files changed, 360 insertions(+), 69 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3796cc5..65adcc6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,18 @@ All notable changes are listed here. The project follows [Semantic Versioning](h while the major version is `0`, a **minor** release (0.x.0) may change the API, and a patch release (0.x.y) only fixes bugs. Breaking changes are called out below. +## Unreleased + +- `validate_and_wait` (and `Dataset.validate`) now polls the validation job: the + current backend answers `validation.start_validation` with the job's id, which + that method now returns (`None` on backends that answer an empty body). A job that + ends FAILED, REFUSED or CANCELED raises `JobError` with the job's status and + `info` right away, instead of waiting for the timeout; a finished job with a note + warns with it. Without a job id, or when polling is refused, it waits for the + user notification as before, and now also stops on a refused, canceled or failed + notification. New keyword `provider_id` (the handle passes its own); + `start_validation` also takes `dataflow_id` and `provider_id`. + ## 0.1.3 (2026-11-19) - Downloads (`client.download()` and everything built on it, such as `export_to_file`) diff --git a/docs/reference/easy.md b/docs/reference/easy.md index 3a8a5b7..1ed12d6 100644 --- a/docs/reference/easy.md +++ b/docs/reference/easy.md @@ -604,6 +604,7 @@ Start a validation, wait until it finishes, return `validation_errors()`. | `dataset_id` | `int` | yes | | | | `dataflow_id` | `int` | yes | | | | `released` | `bool` | no | `False` | | +| `provider_id` | `int \| None` | no | `None` | | | `timeout` | `float` | no | `600.0` | | | `poll_interval` | `float` | no | `3.0` | | | `data_lake` | `bool \| None` | no | `None` | | @@ -611,17 +612,33 @@ Start a validation, wait until it finishes, return `validation_errors()`. **Returns:** `pd.DataFrame` `data_lake` is passed to `validation_errors()` (None: detect from `bigData`). - -WRITES: replaces the dataset's validation results and takes a dataset lock. -The completion signal is the user notification the backend creates when a run -ends (`VALIDATION_FINISHED_EVENT`, or `VALIDATION_RELEASE_FINISHED_EVENT` with -`released=True`), read from `/notification/findUserNotifications`: the dataset -has no status field to poll (live, the sandbox). A run took -about 35-55 s there. Only the calling user's notifications are visible, and a -failed run has no event of its own here, so it ends as a `JobError` timeout. -Notification times are server-side, so a newer one than any seen before the -start counts; a run started by someone else at the same moment could be -mistaken for this one. Raises `JobError` after `timeout` seconds. +`provider_id` goes to the start and the poll; a provider-scoped (reporter) +ApiKey needs it there. + +WRITES: replaces the dataset's validation results and takes a dataset lock (a +second start while one runs gets `LockedError`, 423). Runs took about 35-100 s +on the sandbox. + +How the end is detected: the current backend answers the start with the +validation job's id, so the job is polled (`pollForJobStatus`, as for imports +and exports). A job that ends FAILED, REFUSED or CANCELED raises `JobError` +with the job's `status` and `info`; a FINISHED job with an `info` text (for +example "There are canceled validation tasks") warns with it. Read from the +backend source (`MasterOneVersion` branch); the job polling is not yet tested +live for validations. + +Without a job id (older backends), or when the poll route is refused, the +signal is the user notification the backend creates when a run ends +(`VALIDATION_FINISHED_EVENT`, or `VALIDATION_RELEASE_FINISHED_EVENT` with +`released=True`), read from `/notification/findUserNotifications` (live, the +sandbox). A newer refused, canceled or `VALIDATION_FAILED_*` notification +raises `JobError` instead. Only the calling user's notifications are visible, +and their times are server-side, so a newer one than any seen before the start +counts; a run started by someone else at the same moment could be mistaken +for this one. + +Raises `JobError` after `timeout` seconds: some backend failures leave the job +running and create no notification. ### validation_errors diff --git a/docs/reference/handles.md b/docs/reference/handles.md index 317f021..563e4c1 100644 --- a/docs/reference/handles.md +++ b/docs/reference/handles.md @@ -166,6 +166,7 @@ Start a validation, wait for it, return the failures (`easy.validate_and_wait`). **Returns:** `pd.DataFrame` Replaces the dataset's validation results and locks the dataset while it runs. +The handle's `provider_id` is passed unless you give one. ### Dataset.validation_errors diff --git a/docs/reference/validation.md b/docs/reference/validation.md index 1458412..375722d 100644 --- a/docs/reference/validation.md +++ b/docs/reference/validation.md @@ -204,24 +204,29 @@ queue a validation. |---|---|---|---|---| | `dataset_id` | `int` | yes | | | | `released` | `bool` | no | `False` | | +| `dataflow_id` | `int \| None` | no | `None` | | +| `provider_id` | `int \| None` | no | `None` | | -**Returns:** `None` +**Returns:** `int | None` **Allowed roles:** Not stated in the API spec. The route the Reportnet UI's "Validate" button calls. It only queues an -Orchestrator job and returns None (live, 2026-11-06: the body was a bare -number, `44570`, not understood and not used here). No status is exposed on -a data-lake dataset's listing entry; completion shows as a -`VALIDATION_FINISHED_EVENT` user notification -(`GET /notification/findUserNotifications`), which `easy.validate_and_wait()` -polls. Read the results with `list_group_validations()` (or `_dl()`). This WRITES: it replaces the dataset's -existing validation results and takes a dataset lock (a second start while -one runs may get `423`). Roles: stewards, custodians, lead reporter, -reporter write and similar (see `JobControllerImpl`), or ADMIN. `released` -is for validating a dataset that is being released. +Orchestrator job and returns the job's id (the backend's +`MasterOneVersion` branch answers it as a bare number; live, 2026-11-06, +`44570`), or None when the body is empty (older backends). Poll the id +with `pollForJobStatus` (`easy.validate_and_wait()` does). Completion +also shows as a `VALIDATION_FINISHED_EVENT` user notification +(`GET /notification/findUserNotifications`). Read the results with +`list_group_validations()` (or `_dl()`). This WRITES: it replaces the +dataset's existing validation results and takes a dataset lock (a second +start while one runs gets `423`). Roles: stewards, custodians, lead +reporter, reporter write and similar (see `JobControllerImpl`), or ADMIN. +`dataflow_id` and `provider_id` are optional; on `MasterOneVersion` they +enable the route's ApiKey check (backend source, not tested live). +`released` is for validating a dataset that is being released. ### start_validations_export diff --git a/reportnet_api/easy.py b/reportnet_api/easy.py index b782f03..fc0abe7 100644 --- a/reportnet_api/easy.py +++ b/reportnet_api/easy.py @@ -26,14 +26,20 @@ from http import HTTPStatus from pathlib import Path from typing import TYPE_CHECKING, Any, Literal +from urllib.parse import urlencode import httpx from ._core import RetryPolicy, atomic_destination, caller_stacklevel -from ._exceptions import ForbiddenError, ReportnetAPIError, _is_rejected_credential_500 +from ._exceptions import ( + ForbiddenError, + NotFoundError, + ReportnetAPIError, + _is_rejected_credential_500, +) from .client import ReportnetClient from .demo import demo_client as _demo_client -from .jobs import JobError, Progress, progress_event, progress_scope +from .jobs import JobError, Progress, progress_event, progress_scope, wait_for_job from .resources.dataflow_ext import DataflowKind if TYPE_CHECKING: @@ -372,22 +378,76 @@ def validation_summary(client: ReportnetClient, dataset_id: int, dataflow_id: in return grouped[cols] -def _latest_notification_ms(client: ReportnetClient, dataset_id: int, event_type: str) -> int: - """`insertDate` (ms) of the newest `event_type` user notification for the dataset, or 0. +# Notification event types that end a validation run without results. The +# backend's `MasterDataLakes` and `MasterOneVersion` branches persist these as user +# notifications (`EventType`, `persist=true`); `develop` has none. +_VALIDATION_FAILURE_EVENTS = { + "VALIDATION_REFUSED_EVENT": "REFUSED", + "VALIDATE_AS_PROVIDER_REFUSED_EVENT": "REFUSED", + "VALIDATION_CANCELED_EVENT": "CANCELED", +} + + +def _validation_failure_status(event_type: str) -> str | None: + """The job status a failure notification stands for, or None if it is not one.""" + if event_type in _VALIDATION_FAILURE_EVENTS: + return _VALIDATION_FAILURE_EVENTS[event_type] + if event_type.startswith("VALIDATION_FAILED_") and event_type.endswith("_EVENT"): + return "FAILED" # e.g. VALIDATION_FAILED_SYSTEM_ERROR_EVENT + return None + + +def _newest_validation_event( + client: ReportnetClient, dataset_id: int, finished_event: str +) -> tuple[int, str, dict[str, Any]]: + """Newest `finished_event` or failure notification for the dataset: (ms, type, content). Reads `GET /notification/findUserNotifications` (hidden route; the list the - Reportnet UI shows, newest first, for the calling user only). + Reportnet UI shows, newest first, for the calling user only). `(0, "", {})` when + there is none. """ answer = client.request( "GET", "/notification/findUserNotifications", params={"pageNum": 0, "pageSize": 50} ).json() - times = [ - int(n.get("insertDate") or 0) - for n in (answer or {}).get("userNotifications") or [] - if n.get("eventType") == event_type - and (n.get("content") or {}).get("datasetId") == dataset_id - ] - return max(times, default=0) + newest: tuple[int, str, dict[str, Any]] = (0, "", {}) + for note in (answer or {}).get("userNotifications") or []: + content = note.get("content") or {} + kind = str(note.get("eventType") or "") + if content.get("datasetId") != dataset_id: + continue + if kind != finished_event and _validation_failure_status(kind) is None: + continue + ms = int(note.get("insertDate") or 0) + if ms > newest[0]: + newest = (ms, kind, content) + return newest + + +def _wait_validation_job( + client: ReportnetClient, + job_id: int, + dataset_id: int, + dataflow_id: int, + provider_id: int | None, + *, + deadline: float, + poll_interval: float, +) -> dict[str, Any] | None: + """Poll the validation job until it ends; None when the poll route is refused.""" + params: dict[str, int] = {"datasetId": dataset_id, "dataflowId": dataflow_id} + if provider_id is not None: + params["providerId"] = provider_id + url = f"/orchestrator/jobs/pollForJobStatus/{job_id}?{urlencode(params)}" + try: + return wait_for_job( + client, + url, + poll_interval=poll_interval, + timeout=max(0.0, deadline - time.monotonic()), + ) + except (ForbiddenError, NotFoundError): + # `MasterDataLakes` guards this route with an ApiKey check only. + return None def validate_and_wait( @@ -396,6 +456,7 @@ def validate_and_wait( dataflow_id: int, *, released: bool = False, + provider_id: int | None = None, timeout: float = 600.0, poll_interval: float = 3.0, data_lake: bool | None = None, @@ -403,32 +464,80 @@ def validate_and_wait( """Start a validation, wait until it finishes, return `validation_errors()`. `data_lake` is passed to `validation_errors()` (None: detect from `bigData`). - - WRITES: replaces the dataset's validation results and takes a dataset lock. - The completion signal is the user notification the backend creates when a run - ends (`VALIDATION_FINISHED_EVENT`, or `VALIDATION_RELEASE_FINISHED_EVENT` with - `released=True`), read from `/notification/findUserNotifications`: the dataset - has no status field to poll (live, the sandbox). A run took - about 35-55 s there. Only the calling user's notifications are visible, and a - failed run has no event of its own here, so it ends as a `JobError` timeout. - Notification times are server-side, so a newer one than any seen before the - start counts; a run started by someone else at the same moment could be - mistaken for this one. Raises `JobError` after `timeout` seconds. + `provider_id` goes to the start and the poll; a provider-scoped (reporter) + ApiKey needs it there. + + WRITES: replaces the dataset's validation results and takes a dataset lock (a + second start while one runs gets `LockedError`, 423). Runs took about 35-100 s + on the sandbox. + + How the end is detected: the current backend answers the start with the + validation job's id, so the job is polled (`pollForJobStatus`, as for imports + and exports). A job that ends FAILED, REFUSED or CANCELED raises `JobError` + with the job's `status` and `info`; a FINISHED job with an `info` text (for + example "There are canceled validation tasks") warns with it. Read from the + backend source (`MasterOneVersion` branch); the job polling is not yet tested + live for validations. + + Without a job id (older backends), or when the poll route is refused, the + signal is the user notification the backend creates when a run ends + (`VALIDATION_FINISHED_EVENT`, or `VALIDATION_RELEASE_FINISHED_EVENT` with + `released=True`), read from `/notification/findUserNotifications` (live, the + sandbox). A newer refused, canceled or `VALIDATION_FAILED_*` notification + raises `JobError` instead. Only the calling user's notifications are visible, + and their times are server-side, so a newer one than any seen before the start + counts; a run started by someone else at the same moment could be mistaken + for this one. + + Raises `JobError` after `timeout` seconds: some backend failures leave the job + running and create no notification. """ _require_id(dataset_id, "dataset_id", _DATASET_HINT) event = "VALIDATION_RELEASE_FINISHED_EVENT" if released else "VALIDATION_FINISHED_EVENT" - baseline = _latest_notification_ms(client, dataset_id, event) + baseline = _newest_validation_event(client, dataset_id, event)[0] try: - client.validation.start_validation(dataset_id, released=released) + job_id = client.validation.start_validation( + dataset_id, released=released, dataflow_id=dataflow_id, provider_id=provider_id + ) except ForbiddenError as err: raise _hinted(err, _FORBIDDEN_HINT) from err deadline = time.monotonic() + timeout - while _latest_notification_ms(client, dataset_id, event) <= baseline: + if job_id is not None: + answer = _wait_validation_job( + client, + job_id, + dataset_id, + dataflow_id, + provider_id, + deadline=deadline, + poll_interval=poll_interval, + ) + if answer is not None: + if answer.get("info"): + warnings.warn( + f"Validation job {job_id} finished with a note: {answer['info']}", + RuntimeWarning, + stacklevel=caller_stacklevel(), + ) + return validation_errors(client, dataset_id, dataflow_id, data_lake=data_lake) + while True: + ms, kind, content = _newest_validation_event(client, dataset_id, event) + if ms > baseline: + status = _validation_failure_status(kind) + if status is None: + break + error = content.get("error") + raise JobError( + f"Validation of dataset {dataset_id} ended with {kind}" + + (f": {error}" if error else ""), + status=status, + info=str(error) if error else None, + ) if time.monotonic() >= deadline: raise JobError( f"No {event} notification for dataset {dataset_id} within {timeout:g} " - "seconds (the validation may still be running, or it failed: a failed " - "run has no event of its own)" + "seconds (the validation may still be running, or it failed without " + "leaving a notification)" ) time.sleep(poll_interval) return validation_errors(client, dataset_id, dataflow_id, data_lake=data_lake) diff --git a/reportnet_api/handles.py b/reportnet_api/handles.py index bcccce0..74cce87 100644 --- a/reportnet_api/handles.py +++ b/reportnet_api/handles.py @@ -136,7 +136,9 @@ def validate(self, **kwargs: Any) -> pd.DataFrame: """Start a validation, wait for it, return the failures (`easy.validate_and_wait`). WRITES. Replaces the dataset's validation results and locks the dataset while it runs. + The handle's `provider_id` is passed unless you give one. """ + kwargs.setdefault("provider_id", self.provider_id) return easy.validate_and_wait(self.client, self.id, self.dataflow_id, **kwargs) def export_validations(self, dest: str | os.PathLike[str], **kwargs: Any) -> Path: diff --git a/reportnet_api/resources/validation_ext.py b/reportnet_api/resources/validation_ext.py index f539b71..daf6747 100644 --- a/reportnet_api/resources/validation_ext.py +++ b/reportnet_api/resources/validation_ext.py @@ -48,6 +48,24 @@ def _check(values: list[str] | None, allowed: tuple[str, ...], what: str) -> lis return list(values) +def _start_params( + released: bool, dataflow_id: int | None, provider_id: int | None +) -> dict[str, str] | None: + params = {"released": "true"} if released else {} + if dataflow_id is not None: + params["dataflowId"] = str(dataflow_id) + if provider_id is not None: + params["providerId"] = str(provider_id) + return params or None + + +def _job_id_of_body(text: str) -> int | None: + # `MasterOneVersion`'s JobControllerImpl#addValidationJob returns `Long jobId`; + # `develop` and `MasterDataLakes` return void (an empty body). + body = text.strip() + return int(body) if body.isdigit() else None + + def _list_params( page_num: int, page_size: int, @@ -77,26 +95,37 @@ class ValidationResource: def __init__(self, client: ReportnetClient) -> None: self._client = client - def start_validation(self, dataset_id: int, *, released: bool = False) -> None: + def start_validation( + self, + dataset_id: int, + *, + released: bool = False, + dataflow_id: int | None = None, + provider_id: int | None = None, + ) -> int | None: """PUT /orchestrator/jobs/addValidationJob/{datasetId}: queue a validation. The route the Reportnet UI's "Validate" button calls. It only queues an - Orchestrator job and returns None (live, 2026-11-06: the body was a bare - number, `44570`, not understood and not used here). No status is exposed on - a data-lake dataset's listing entry; completion shows as a - `VALIDATION_FINISHED_EVENT` user notification - (`GET /notification/findUserNotifications`), which `easy.validate_and_wait()` - polls. Read the results with `list_group_validations()` (or `_dl()`). This WRITES: it replaces the dataset's - existing validation results and takes a dataset lock (a second start while - one runs may get `423`). Roles: stewards, custodians, lead reporter, - reporter write and similar (see `JobControllerImpl`), or ADMIN. `released` - is for validating a dataset that is being released. + Orchestrator job and returns the job's id (the backend's + `MasterOneVersion` branch answers it as a bare number; live, 2026-11-06, + `44570`), or None when the body is empty (older backends). Poll the id + with `pollForJobStatus` (`easy.validate_and_wait()` does). Completion + also shows as a `VALIDATION_FINISHED_EVENT` user notification + (`GET /notification/findUserNotifications`). Read the results with + `list_group_validations()` (or `_dl()`). This WRITES: it replaces the + dataset's existing validation results and takes a dataset lock (a second + start while one runs gets `423`). Roles: stewards, custodians, lead + reporter, reporter write and similar (see `JobControllerImpl`), or ADMIN. + `dataflow_id` and `provider_id` are optional; on `MasterOneVersion` they + enable the route's ApiKey check (backend source, not tested live). + `released` is for validating a dataset that is being released. """ - self._client.request( + response = self._client.request( "PUT", f"/orchestrator/jobs/addValidationJob/{dataset_id}", - params={"released": "true"} if released else None, + params=_start_params(released, dataflow_id, provider_id), ) + return _job_id_of_body(response.text) def list_validations( self, @@ -306,13 +335,21 @@ class AsyncValidationResource: def __init__(self, client: AsyncReportnetClient) -> None: self._client = client - async def start_validation(self, dataset_id: int, *, released: bool = False) -> None: + async def start_validation( + self, + dataset_id: int, + *, + released: bool = False, + dataflow_id: int | None = None, + provider_id: int | None = None, + ) -> int | None: """Async counterpart of ValidationResource.start_validation.""" - await self._client.request( + response = await self._client.request( "PUT", f"/orchestrator/jobs/addValidationJob/{dataset_id}", - params={"released": "true"} if released else None, + params=_start_params(released, dataflow_id, provider_id), ) + return _job_id_of_body(response.text) async def list_validations( self, diff --git a/tests/test_easy.py b/tests/test_easy.py index a7b3118..1ff0e6d 100644 --- a/tests/test_easy.py +++ b/tests/test_easy.py @@ -273,6 +273,97 @@ def test_validate_and_wait_times_out(monkeypatch: pytest.MonkeyPatch) -> None: easy.validate_and_wait(easy.connect("k"), 9, 5, timeout=0) +def _job_backend(job_answers: list[httpx.Response]) -> dict[str, respx.Route]: + """Mocks for a backend whose addValidationJob answers a job id (`44570`).""" + return { + "notes": respx.get(f"{BASE}/notification/findUserNotifications").respond( + json={"userNotifications": []} + ), + "start": respx.put(f"{BASE}/orchestrator/jobs/addValidationJob/9").respond( + 200, text="44570" + ), + "poll": respx.get(f"{BASE}/orchestrator/jobs/pollForJobStatus/44570").mock( + side_effect=job_answers + ), + "flow": respx.get(f"{BASE}/dataflow/v1/5").respond(json={"bigData": False}), + "errors": respx.get(url__regex=rf"{BASE}/validation/listGroupValidations/.*").respond( + json={"errors": [_vrow("A", "r1")], "totalRecords": 1} + ), + } + + +@respx.mock +def test_validate_and_wait_polls_the_job(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setattr("reportnet_api.jobs.time.sleep", lambda s: None) + routes = _job_backend( + [ + httpx.Response(200, json={"status": "IN_PROGRESS"}), + httpx.Response(200, json={"status": "FINISHED"}), + ] + ) + df = easy.validate_and_wait(easy.connect("k"), 9, 5, provider_id=11) + assert df["short_code"].tolist() == ["A"] + assert routes["poll"].call_count == 2 + poll = routes["poll"].calls[-1].request.url.params + assert (poll["datasetId"], poll["dataflowId"], poll["providerId"]) == ("9", "5", "11") + start = routes["start"].calls[-1].request.url.params + assert (start["dataflowId"], start["providerId"]) == ("5", "11") + assert routes["notes"].call_count == 1 # baseline only: the job is the signal + + +@respx.mock +def test_validate_and_wait_raises_when_the_job_fails(monkeypatch: pytest.MonkeyPatch) -> None: + monkeypatch.setattr("reportnet_api.jobs.time.sleep", lambda s: None) + info = "Validation failed due to system error. Please contact the Service Desk for support." + _job_backend([httpx.Response(200, json={"status": "FAILED", "info": info})]) + with pytest.raises(JobError, match="system error") as caught: + easy.validate_and_wait(easy.connect("k"), 9, 5) + assert caught.value.status == "FAILED" and caught.value.info == info + + +@respx.mock +def test_validate_and_wait_warns_on_finished_with_info(monkeypatch: pytest.MonkeyPatch) -> None: + note = "There are canceled validation tasks. Please review and address the issues." + _job_backend([httpx.Response(200, json={"status": "FINISHED", "info": note})]) + with pytest.warns(RuntimeWarning, match="canceled validation tasks"): + df = easy.validate_and_wait(easy.connect("k"), 9, 5) + assert df["short_code"].tolist() == ["A"] + + +@respx.mock +def test_validate_and_wait_falls_back_to_notifications_when_poll_is_refused( + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setattr("reportnet_api.easy.time.sleep", lambda s: None) + routes = _job_backend([httpx.Response(403)]) + new = {"eventType": "VALIDATION_FINISHED_EVENT", "insertDate": 200, "content": {"datasetId": 9}} + answers = iter([[], [new]]) + routes["notes"].mock( + side_effect=lambda r: httpx.Response(200, json={"userNotifications": next(answers)}) + ) + df = easy.validate_and_wait(easy.connect("k"), 9, 5) + assert df["short_code"].tolist() == ["A"] and routes["poll"].call_count == 1 + + +@respx.mock +def test_validate_and_wait_raises_on_failure_notification(monkeypatch: pytest.MonkeyPatch) -> None: + # No job id (older backend): a failure event newer than the baseline ends the wait. + monkeypatch.setattr("reportnet_api.easy.time.sleep", lambda s: None) + old = {"eventType": "VALIDATION_FINISHED_EVENT", "insertDate": 100, "content": {"datasetId": 9}} + failed = { + "eventType": "VALIDATION_FAILED_SYSTEM_ERROR_EVENT", + "insertDate": 200, + "content": {"datasetId": 9, "error": "promotion failed"}, + } + answers = iter([[old], [old], [failed, old]]) + respx.get(f"{BASE}/notification/findUserNotifications").mock( + side_effect=lambda r: httpx.Response(200, json={"userNotifications": next(answers)}) + ) + respx.put(f"{BASE}/orchestrator/jobs/addValidationJob/9").respond(200) + with pytest.raises(JobError, match=r"VALIDATION_FAILED_SYSTEM_ERROR_EVENT.*promotion failed"): + easy.validate_and_wait(easy.connect("k"), 9, 5) + + JWT = "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ4In0.c2ln-_x" diff --git a/tests/test_handles.py b/tests/test_handles.py index 61eba2d..056e9a7 100644 --- a/tests/test_handles.py +++ b/tests/test_handles.py @@ -310,7 +310,7 @@ def validate_and_wait(c: object, d: int, f: int, **k: object) -> None: assert calls == [ ("x", 4, 5, {"file_format": "parquet"}), ("u", 4, 5, {"replace": True, "provider_id": 11}), - ("v", 4, 5, {"released": True}), + ("v", 4, 5, {"released": True, "provider_id": 11}), ] diff --git a/tests/test_validation.py b/tests/test_validation.py index b926524..f48b994 100644 --- a/tests/test_validation.py +++ b/tests/test_validation.py @@ -26,6 +26,21 @@ def test_start_validation_sends_released_only_when_true() -> None: assert route.calls[-1].request.url.params["released"] == "true" +def test_start_validation_returns_job_id_and_sends_ids() -> None: + # The current backend answers the new job's id as a bare number (live: `44570`); + # older branches answer an empty body. + with respx.mock(base_url=BASE_URL) as mock: + route = mock.put("/orchestrator/jobs/addValidationJob/7").mock( + side_effect=[httpx.Response(200, text="44570"), httpx.Response(200)] + ) + with ReportnetClient(BASE_URL, "t") as c: + assert c.validation.start_validation(7, dataflow_id=5, provider_id=11) == 44570 + params = route.calls[-1].request.url.params + assert (params["dataflowId"], params["providerId"]) == ("5", "11") + assert c.validation.start_validation(7) is None + assert "dataflowId" not in route.calls[-1].request.url.params + + def test_list_group_validations_params_and_validation() -> None: with respx.mock(base_url=BASE_URL) as mock: route = mock.get("/validation/listGroupValidations/7").mock( @@ -105,7 +120,9 @@ def test_export_times_out(tmp_path: Path) -> None: def test_async_routes(tmp_path: Path) -> None: async def run() -> None: with respx.mock(base_url=BASE_URL) as mock: - mock.put("/orchestrator/jobs/addValidationJob/7").mock(return_value=httpx.Response(200)) + mock.put("/orchestrator/jobs/addValidationJob/7").mock( + return_value=httpx.Response(200, text="12") + ) mock.get("/validation/listGroupValidations/7").mock( return_value=httpx.Response(200, json=LISTING) ) @@ -114,7 +131,7 @@ async def run() -> None: side_effect=[httpx.Response(404), httpx.Response(200, content=b"x\n")] ) async with AsyncReportnetClient(BASE_URL, "t") as c: - await c.validation.start_validation(7) + assert await c.validation.start_validation(7, dataflow_id=5) == 12 assert await c.validation.list_group_validations(7) == LISTING await c.validation.export_validations_to_file( 7, tmp_path / "v.csv", poll_interval=0.01 From d3c830446916d4eeb850f8ad61c7e0f5fbd9cb56 Mon Sep 17 00:00:00 2001 From: Nikolaos Paximadakis Date: Fri, 20 Nov 2026 11:52:29 +0100 Subject: [PATCH 2/2] validate_and_wait: review fixes Fall back to notifications also when the job poll answers 401 or a rejected-credential 500; a poll timeout names the job, dataset and the caller's timeout; a FINISHED-with-note result carries the note in attrs['validation_note']; the job id parser accepts only ASCII digits (also JSON-quoted). Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 2 +- docs/reference/easy.md | 3 ++- reportnet_api/easy.py | 24 +++++++++++++++--- reportnet_api/resources/validation_ext.py | 5 ++-- tests/test_easy.py | 30 +++++++++++++++++++++++ tests/test_validation.py | 9 ++++++- 6 files changed, 65 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 65adcc6..ce5a3af 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,7 +11,7 @@ release (0.x.y) only fixes bugs. Breaking changes are called out below. that method now returns (`None` on backends that answer an empty body). A job that ends FAILED, REFUSED or CANCELED raises `JobError` with the job's status and `info` right away, instead of waiting for the timeout; a finished job with a note - warns with it. Without a job id, or when polling is refused, it waits for the + warns with it and stores it in the result's `attrs["validation_note"]`. Without a job id, or when polling is refused, it waits for the user notification as before, and now also stops on a refused, canceled or failed notification. New keyword `provider_id` (the handle passes its own); `start_validation` also takes `dataflow_id` and `provider_id`. diff --git a/docs/reference/easy.md b/docs/reference/easy.md index 1ed12d6..5bcfce4 100644 --- a/docs/reference/easy.md +++ b/docs/reference/easy.md @@ -623,7 +623,8 @@ How the end is detected: the current backend answers the start with the validation job's id, so the job is polled (`pollForJobStatus`, as for imports and exports). A job that ends FAILED, REFUSED or CANCELED raises `JobError` with the job's `status` and `info`; a FINISHED job with an `info` text (for -example "There are canceled validation tasks") warns with it. Read from the +example "There are canceled validation tasks", so the results may be partial) +warns with it and puts it in the result's `attrs["validation_note"]`. Read from the backend source (`MasterOneVersion` branch); the job polling is not yet tested live for validations. diff --git a/reportnet_api/easy.py b/reportnet_api/easy.py index fc0abe7..0cd22bc 100644 --- a/reportnet_api/easy.py +++ b/reportnet_api/easy.py @@ -32,9 +32,11 @@ from ._core import RetryPolicy, atomic_destination, caller_stacklevel from ._exceptions import ( + AuthenticationError, ForbiddenError, NotFoundError, ReportnetAPIError, + ServerError, _is_rejected_credential_500, ) from .client import ReportnetClient @@ -431,6 +433,7 @@ def _wait_validation_job( provider_id: int | None, *, deadline: float, + timeout: float, poll_interval: float, ) -> dict[str, Any] | None: """Poll the validation job until it ends; None when the poll route is refused.""" @@ -445,9 +448,20 @@ def _wait_validation_job( poll_interval=poll_interval, timeout=max(0.0, deadline - time.monotonic()), ) - except (ForbiddenError, NotFoundError): + except (AuthenticationError, ForbiddenError, NotFoundError): # `MasterDataLakes` guards this route with an ApiKey check only. return None + except ServerError as err: + if _is_rejected_credential_500(err.response_body): + return None # a refused credential, answered as 500 (see `explain`) + raise + except JobError as err: + if err.status is None and "did not finish" in str(err): + raise JobError( + f"Validation job {job_id} for dataset {dataset_id} did not finish within " + f"{timeout:g} seconds (it may still be running on the server)" + ) from err + raise def validate_and_wait( @@ -475,7 +489,8 @@ def validate_and_wait( validation job's id, so the job is polled (`pollForJobStatus`, as for imports and exports). A job that ends FAILED, REFUSED or CANCELED raises `JobError` with the job's `status` and `info`; a FINISHED job with an `info` text (for - example "There are canceled validation tasks") warns with it. Read from the + example "There are canceled validation tasks", so the results may be partial) + warns with it and puts it in the result's `attrs["validation_note"]`. Read from the backend source (`MasterOneVersion` branch); the job polling is not yet tested live for validations. @@ -510,16 +525,19 @@ def validate_and_wait( dataflow_id, provider_id, deadline=deadline, + timeout=timeout, poll_interval=poll_interval, ) if answer is not None: + errors = validation_errors(client, dataset_id, dataflow_id, data_lake=data_lake) if answer.get("info"): + errors.attrs["validation_note"] = str(answer["info"]) warnings.warn( f"Validation job {job_id} finished with a note: {answer['info']}", RuntimeWarning, stacklevel=caller_stacklevel(), ) - return validation_errors(client, dataset_id, dataflow_id, data_lake=data_lake) + return errors while True: ms, kind, content = _newest_validation_event(client, dataset_id, event) if ms > baseline: diff --git a/reportnet_api/resources/validation_ext.py b/reportnet_api/resources/validation_ext.py index daf6747..c73df42 100644 --- a/reportnet_api/resources/validation_ext.py +++ b/reportnet_api/resources/validation_ext.py @@ -17,6 +17,7 @@ import asyncio import os +import re import time import uuid from pathlib import Path @@ -62,8 +63,8 @@ def _start_params( def _job_id_of_body(text: str) -> int | None: # `MasterOneVersion`'s JobControllerImpl#addValidationJob returns `Long jobId`; # `develop` and `MasterDataLakes` return void (an empty body). - body = text.strip() - return int(body) if body.isdigit() else None + body = text.strip().strip('"') + return int(body) if re.fullmatch(r"[0-9]+", body) else None def _list_params( diff --git a/tests/test_easy.py b/tests/test_easy.py index 1ff0e6d..8ac5423 100644 --- a/tests/test_easy.py +++ b/tests/test_easy.py @@ -328,6 +328,36 @@ def test_validate_and_wait_warns_on_finished_with_info(monkeypatch: pytest.Monke with pytest.warns(RuntimeWarning, match="canceled validation tasks"): df = easy.validate_and_wait(easy.connect("k"), 9, 5) assert df["short_code"].tolist() == ["A"] + assert df.attrs["validation_note"] == note + + +@pytest.mark.parametrize( + "refusal", + [ + httpx.Response(401), + httpx.Response(500, json={"message": "401 UNAUTHORIZED"}), + ], +) +@respx.mock +def test_validate_and_wait_falls_back_on_refused_credential( + monkeypatch: pytest.MonkeyPatch, refusal: httpx.Response +) -> None: + monkeypatch.setattr("reportnet_api.easy.time.sleep", lambda s: None) + routes = _job_backend([refusal]) + new = {"eventType": "VALIDATION_FINISHED_EVENT", "insertDate": 200, "content": {"datasetId": 9}} + answers = iter([[], [new]]) + routes["notes"].mock( + side_effect=lambda r: httpx.Response(200, json={"userNotifications": next(answers)}) + ) + df = easy.validate_and_wait(easy.connect("k"), 9, 5) + assert df["short_code"].tolist() == ["A"] + + +@respx.mock +def test_validate_and_wait_job_timeout_names_dataset_and_timeout() -> None: + _job_backend([httpx.Response(200, json={"status": "IN_PROGRESS"})]) + with pytest.raises(JobError, match=r"job 44570 for dataset 9 .* within 0 seconds"): + easy.validate_and_wait(easy.connect("k"), 9, 5, timeout=0) @respx.mock diff --git a/tests/test_validation.py b/tests/test_validation.py index f48b994..8c9c9bf 100644 --- a/tests/test_validation.py +++ b/tests/test_validation.py @@ -31,7 +31,12 @@ def test_start_validation_returns_job_id_and_sends_ids() -> None: # older branches answer an empty body. with respx.mock(base_url=BASE_URL) as mock: route = mock.put("/orchestrator/jobs/addValidationJob/7").mock( - side_effect=[httpx.Response(200, text="44570"), httpx.Response(200)] + side_effect=[ + httpx.Response(200, text="44570"), + httpx.Response(200), + httpx.Response(200, text='"17"'), + httpx.Response(200, text="\u00b2"), + ] ) with ReportnetClient(BASE_URL, "t") as c: assert c.validation.start_validation(7, dataflow_id=5, provider_id=11) == 44570 @@ -39,6 +44,8 @@ def test_start_validation_returns_job_id_and_sends_ids() -> None: assert (params["dataflowId"], params["providerId"]) == ("5", "11") assert c.validation.start_validation(7) is None assert "dataflowId" not in route.calls[-1].request.url.params + assert c.validation.start_validation(7) == 17 # JSON-quoted + assert c.validation.start_validation(7) is None # not an ASCII number def test_list_group_validations_params_and_validation() -> None: