aeat.domain.calculations.registry._renta_web_open_oracle module

Renta WEB Open parity oracle contract for Modelo 100.

class RentaWebOpenModel(**data)[source]

Bases: BaseModel

Strict frozen base for Renta WEB Open parity records.

class RentaWebOpenSyntheticProfile(**data)[source]

Bases: RentaWebOpenModel

Synthetic identifying data accepted by Renta WEB Open.

Parameters:

  • nif (str)

  • name (str)

  • civil_status (str)

  • birth_date (str)

  • sex (Literal['Hombre', 'Mujer'])

  • autonomous_community (str)

nif: str
name: str
civil_status: str
birth_date: str
sex: Literal['Hombre', 'Mujer']
autonomous_community: str
class RentaWebOpenDisplayOverride(**data)[source]

Bases: RentaWebOpenModel

One browser-coordinate override keyed externally by canonical casilla id.

Parameters:

  • display_number (str)

  • value (str)

display_number: str
value: str
class RentaWebOpenLivePayload(**data)[source]

Bases: RentaWebOpenModel

Payload for a Renta WEB Open parity run.

Browser-visible labels and display numbers are external UI coordinates. They are never output keys. summary_labels_by_casilla_id maps the canonical registry casilla id to the Renta WEB summary label to scrape. scrape_display_numbers_by_casilla_id maps the canonical registry casilla id to a browser-visible display number that the driver should navigate to and read. display_overrides_by_casilla_id is also keyed by canonical casilla id; the nested display number is only the external browser coordinate used to reach AEAT’s input widget.

Parameters:
profile: RentaWebOpenSyntheticProfile
app_url: AnyUrl
timeout_ms: int
display_overrides_by_casilla_id: dict[CasillaId, RentaWebOpenDisplayOverride]
summary_labels_by_casilla_id: dict[CasillaId, str]
scrape_display_numbers_by_casilla_id: dict[CasillaId, str]
class RentaWebOpenObservation(**data)[source]

Bases: RentaWebOpenModel

Observed Renta WEB Open outputs returned by a concrete adapter.

Parameters:

  • values (dict[CasillaId, str])

  • raw_evidence_locator (str | None)

values: dict[CasillaId, str]
raw_evidence_locator: str | None
class RentaWebOpenDriver(*args, **kwargs)[source]

Bases: Protocol

Execution boundary for live or replay Renta WEB Open adapters.

property mode: Literal['live', 'replay']

Identify whether this driver talks to a real surface or replays a capture.

Returns:

Either "live" (the driver scrapes the public Renta WEB Open simulator, AEAT’s online estimator for the IRPF income-tax declaration filed on Modelo 100, a tax form) or "replay" (the driver decodes a previously captured JSON payload). The oracle uses the value only to phrase its result narrative.

planned_operations(payload, *, expected)[source]

Describe the remote work this driver would perform, without performing it.

The remote-state guard inspects the returned operations before any are executed, so a driver must declare its full plan up front.

Parameters:

  • payload (bytes) – Raw request bytes; for the live driver this carries the optional JSON capture configuration, for the replay driver the captured observation document.

  • expected (Mapping[TypeAliasType, object]) – Mapping of expected canonical casilla ids to their expected values.

Return type:

tuple[RemoteOperation, ...]

Returns:

The ordered RemoteOperation tuple the driver intends to run.

collect_observation(payload, *, expected)[source]

Execute the driver and return the observed Modelo 100 outputs.

Parameters:

  • payload (bytes) – Raw request bytes carrying the live capture configuration or the replay document.

  • expected (Mapping[TypeAliasType, object]) – Mapping of expected canonical casilla ids to their expected values, available to scope scraping.

Return type:

RentaWebOpenObservation

Returns:

A RentaWebOpenObservation whose values maps canonical casilla ids to their observed string renderings, plus an optional evidence locator pointing at the captured source.

class RentaWebOpenReplayDriver[source]

Bases: object

Deterministic local replay driver for captured Renta WEB Open outputs.

property mode: Literal['replay']

Report this driver as a replay surface.

Returns:

this driver decodes a captured JSON document rather than scraping the live Renta WEB Open simulator, so the oracle can run deterministically offline.

Return type:

Always "replay"

planned_operations(payload, *, expected)[source]

Declare the single local-parse operation this replay driver performs.

Replay never touches the network: it parses a captured workbook-style JSON document, so the plan is one local_workbook operation regardless of the request.

Parameters:

  • payload (bytes) – Raw request bytes (the captured document is read in collect_observation; this method ignores its contents).

  • expected (Mapping[TypeAliasType, object]) – Mapping of expected canonical casilla ids to expected values; unused, present to satisfy the RentaWebOpenDriver protocol.

Return type:

tuple[RemoteOperation, ...]

Returns:

A one-element tuple holding the local-parse RemoteOperation.

collect_observation(payload, *, expected)[source]

Decode the captured replay payload into observed Modelo 100 outputs.

Parameters:

  • payload (bytes) – UTF-8 JSON bytes holding a previously captured Renta WEB Open observation document.

  • expected (Mapping[TypeAliasType, object]) – Mapping of expected canonical casilla ids to expected values; unused, present to satisfy the RentaWebOpenDriver protocol.

Return type:

RentaWebOpenObservation

Returns:

A RentaWebOpenObservation carrying the decoded casilla values and the document’s raw evidence locator.

Raises:

RegistryValidationError – If the payload is not decodable as the expected replay JSON document.

class RentaWebOpenOracle(*, driver=None)[source]

Bases: object

Open-simulator parity oracle for Modelo 100 Renta WEB Open.

Parameters:

driver (RentaWebOpenDriver | None)

property oracle_id: OracleId

Return the stable identifier for this parity oracle.

Returns:

The constant "modelo-100-renta-web-open", stamped onto every ParityResult so a verdict can be traced back to the oracle that produced it.

property surface_kind: Literal['file_validator', 'open_simulator', 'iva_id_check', 'pre_filing_validator', 'integration_test_service']

Classify the external surface this oracle compares against.

Returns:

Renta WEB Open is AEAT’s public, unauthenticated estimator for the Modelo 100 income declaration, distinct from authenticated filing surfaces. The remote-state guard reads this to scope which operations are allowed.

Return type:

The OracleSurfaceKind "open_simulator"

planned_operations(payload, *, expected)[source]

Describe the remote operations a parity run would perform, without running them.

When a driver is configured the call delegates to it. Otherwise the oracle returns a placeholder plan (an HTTP GET against the simulator URL plus a browser action marked as requiring a driver) so the guard can still preflight an unconfigured oracle.

Parameters:

  • payload (bytes) – Raw request bytes forwarded to the driver when present.

  • expected (Mapping[str, object]) – Mapping of expected canonical casilla ids to their expected values. Must be non-empty.

Return type:

tuple[RemoteOperation, ...]

Returns:

The ordered RemoteOperation tuple the run intends to perform.

Raises:

RegistryValidationError – If expected is empty, since a parity run with no expected casilla has nothing to verify.

verify_payload(policy, payload, *, expected)[source]

Run a Renta WEB Open parity check and return a typed verdict.

The remote-state guard first authorizes the planned operations. A blocked plan yields a "blocked" result; an unconfigured driver yields an "unverifiable" result after a passing preflight. With a driver, each expected canonical casilla id is compared against its observed value, and the per-field verdicts are combined into one overall verdict.

Parameters:

  • policy (RemoteStateGuardPolicy) – The remote-state guard policy authorizing the run; its id is recorded as the result’s cross-reference.

  • payload (bytes) – Raw request bytes passed to the driver.

  • expected (Mapping[str, object]) – Mapping of expected canonical casilla ids to expected values to compare against the observation.

Return type:

ParityResult

Returns:

A ParityResult carrying the verdict ("match", "mismatch", "unverifiable", or "blocked"), a human-readable narrative, the per-casilla comparisons, and any raw evidence locator.

parse_renta_web_open_live_payload(payload)[source]

Parse the optional JSON payload and return a RentaWebOpenLivePayload.

Return type:

RentaWebOpenLivePayload

Parameters:

payload (bytes)

validate_renta_web_open_expected_casilla_ids(expected)[source]

Return expected keys validated as canonical casilla.id values.

Renta WEB Open browser labels and display numbers are UI coordinates only. They must be carried by the live payload’s explicit casilla-id-keyed maps, never by the oracle expected comparison surface.

Return type:

frozenset[TypeAliasType]

Parameters:

expected (Mapping[ExpectedKey, object])

validate_renta_web_open_expected_casilla_values(expected)[source]

Return expected values re-keyed by validated canonical casilla.id.

Return type:

dict[TypeAliasType, object]

Parameters:

expected (Mapping[ExpectedKey, object])

equivalent_renta_web_open_value(expected, observed)[source]

Return true when dot or comma decimal renderings represent the same number.

Return type:

bool

Parameters:

  • expected (str)

  • observed (str)