cadrumo.adapters.outbound.aeat.sede.iva_compensation_wallet_parsing module

Pure HTML-parsing and URL-audit layer for the AEAT IVA compensation wallet.

This module is the side-effect-free half of the wallet reader: it takes captured AEAT cartera HTML (or URLs) and returns parsed observations, structural shape diagnostics, and host/path audit decisions. It has no Playwright, browser-session, or navigation dependency, so the navigation/state-machine half (_iva_compensation_wallet) imports from here rather than the reverse.

The wallet URL/host constants live here too because both halves consume them; the navigation module re-imports them so there is a single definition.

parse_iva_compensation_wallet_html(html, *, taxpayer_nif, authenticated_identity, target_year, target_period, source_url, captured_at, allow_empty_wallet_shell=False)[source]

Parse wallet rows and the total from a captured AEAT cartera HTML page.

Returns a IvaCompensationWalletObservation with the aggregate and per-period detail rows.

The own-name “Cartera de cuotas de IVA a compensar” results view carries an authoritative aggregate — the “Cuotas a compensar pendientes de períodos anteriores” line — plus a detail table (Ejercicio / Período / Cuota Disponible) itemising the still-available balance per generation period. The aggregate is the contract value surfaced as total_pending; the detail rows are cross-checked against it so a parse drift cannot silently under-declare. A genuinely empty wallet renders the same aggregate line at 0,00 with no detail rows.

Return type:

IvaCompensationWalletObservation

Parameters:

  • html (str)

  • taxpayer_nif (str)

  • authenticated_identity (str)

  • target_year (int)

  • target_period (Period)

  • source_url (str)

  • captured_at (datetime)

  • allow_empty_wallet_shell (bool)

discover_iva_compensation_wallet_entrypoint(html, *, base_url)[source]

Return AEAT’s Pre303-provided wallet URL when the authenticated page exposes one.

Return type:

str | None

Parameters:
assert_own_name_representation_form_html(html, *, landing_url, expected_path)[source]

Validate the captured representation form before own-name continuation.

Return type:

None

Parameters:

  • html (str)

  • landing_url (str)

  • expected_path (str)

wallet_execute_gate_status(html, *, expected_path)[source]

Classify whether the wallet HTML exposes the expected execute form.

Return type:

str

Parameters:

  • html (str)

  • expected_path (str)

wallet_execute_form_method(html)[source]

Return the wallet execute form’s HTTP method, defaulting to GET.

Return type:

str

Parameters:

html (str)

has_wallet_table(html)[source]

Return whether HTML contains a table with the wallet headers.

Return type:

bool

Parameters:

html (str)

wallet_page_shape_context(html, *, landing_url)[source]

Build bounded structural diagnostics for one wallet page.

Return type:

_WalletPageShape

Parameters:

  • html (str)

  • landing_url (str)

is_aeat_wallet_read_url(url)[source]

Return whether url is a policy-approved authenticated wallet GET.

Return type:

bool

Parameters:

url (str)

looks_like_executed_empty_wallet_page(soup)[source]

Return whether a parsed page is the executed-empty wallet response.

Return type:

bool

Parameters:

soup (BeautifulSoup)