aeat.adapters.outbound.aeat.sede._adapter_utils module

Shared private helpers for AEAT sede browser drivers.

Hosts the small text-normalisation, error-formatting, and selector-probe helpers consumed by every sede driver. Drivers (_groi_check, _nif_iva_check, future siblings) inject their own surface label and shape-change suggestion so the helper output remains diagnostic without re-implementing the same logic per driver.

make_locate_helper() and assert_query_browser_action_for() factor out the two private helper shapes that each checker driver used to duplicate.

assert_query_browser_action_for(policy, action)[source]

Assert that action is permitted under policy.

Raises RegistryValidationError via assert_remote_operation_allowed() if the action pattern is not allowed. Both the GROI and NIF-IVA drivers close over their own RemoteStateGuardPolicy objects; this shared helper removes the duplicate _assert_query_browser_action bodies they used to carry.

Parameters:

  • policy (RemoteStateGuardPolicy) – The guard policy the driver was initialised with.

  • action (str) – Browser action label to validate (e.g. "open-groi-form").

Return type:

None

require_playwright_page(raw_page)[source]

Return raw_page as a Playwright Page or raise a typed adapter error.

Return type:

Page

Parameters:

raw_page (object)

make_locate_helper(surface_label, shape_suggestion)[source]

Return a _locate coroutine pre-bound to surface_label and shape_suggestion.

Both the GROI and NIF-IVA drivers wrap first_visible_locator() with the same body, differing only in the surface_label and shape_suggestion strings they inject. This factory eliminates that duplicate; each driver calls:

_locate = make_locate_helper("GROI", _groi_shape_suggestion())

and then uses _locate(page, selectors, stage=..., description=..., timeout_ms=...) directly.

Parameters:

  • surface_label (str) – Sede surface name for log and error messages.

  • shape_suggestion (str) – Localised guidance string appended to SedeParseError when all selectors fail.

Return type:

Callable[[Page, tuple[str, ...], str, str, int], Coroutine[Any, Any, Locator]]

Returns:

An async callable with the same signature as the internal _locate helpers the drivers previously defined individually.

normalize_response_text(text)[source]

Casefold + strip diacritics + collapse whitespace for marker matching.

Return type:

str

Parameters:

text (str)

registry_failure_message(exc)[source]

Build a registry-facing error string enriched with the failure_mode context field.

Sede driver exceptions carry a context mapping; this helper extracts failure_mode (falling back to a site_health:<state> label when only a state key is present) and appends it to the base str(exc) so callers wrapping the exception into a RegistryValidationError preserve the diagnostic context. Returns str(exc) unchanged when no failure_mode is derivable.

Return type:

str

Parameters:

exc (BaseException)

async first_visible_locator(page, selectors, *, stage, description, timeout_ms, probe_timeout_ms, surface_label, shape_suggestion)[source]

Return the first selector in selectors that resolves to a visible element.

Probes each selector in order using a short probe_timeout_ms deadline. If a selector is not visible within that window, PlaywrightError / PlaywrightTimeoutError is caught and the next selector is tried. When no selector resolves, SedeParseError is raised with SedeFailureMode.EXTERNAL_SHAPE_CHANGED so callers can distinguish “AEAT changed the page layout” from transient network timeouts.

Parameters:

  • page (Page) – Playwright Page on which to probe the selectors.

  • selectors (tuple[str, ...]) – CSS selector strings tried in declaration order.

  • stage (str) – Opaque label for the current driver stage, included in the error context.

  • description (str) – Human-readable description of the expected element, used in the error message.

  • timeout_ms (int) – Overall operation timeout (ms); probe_timeout_ms is capped to this value.

  • probe_timeout_ms (int) – Per-selector visibility probe budget (ms).

  • surface_label (str) – Sede surface name included in log and error messages (e.g. "GROI").

  • shape_suggestion (str) – Localised guidance string appended to SedeParseError when all selectors fail.

Return type:

Locator

Returns:

The first Locator from selectors whose element was visible within probe_timeout_ms.

Raises:

SedeParseError – When every selector probe timed out or failed.