aeat.application.transactions._diagnostics module

Typed diagnostic records for the ledger-import use case.

The CLI uses a closed catalogue of import diagnostic kinds emitted by aeat app ledger import PATH --provider PROVIDER --verify:

  • original-file — records the caller-supplied original source file path when it is available, so import reports can distinguish the parsed input path from the source artefact the operator intended to verify.

  • gap — detects calendar gaps in the imported transaction stream so the operator notices a missing month / week / day without rerunning analytics.

  • duplicate — flags an imported transaction whose stable id matches one already in the ledger so re-importing the same bank statement does not double-count.

  • parser — reports a parser-level problem (malformed cell, unknown column, encoding hint mismatch) without aborting the import outright.

The CLI consumes LedgerImportDiagnostic records via build_ledger_import_diagnostic() and renders them grouped by severity and kind.

See also

LedgerImportDiagnosticKind, LedgerImportDiagnostic, and build_ledger_import_diagnostic().

class LedgerImportDiagnosticKind(*values)[source]

Bases: StrEnum

Closed catalogue of ledger-import diagnostic categories.

ORIGINAL_FILE
GAP
DUPLICATE
PARSER
class LedgerImportDiagnostic(**data)[source]

Bases: BaseModel

One typed diagnostic emitted by the ledger import use-case.

Variables:

  • kind – Closed LedgerImportDiagnosticKind.

  • severity – BaseSeverity.

  • message – A strictly-typed Translatable key.

  • source_path – Optional pointer at the source artefact the diagnostic refers to (input file, provider name, etc.).

  • source_locator – Optional sub-path inside source_path (row index, column name, period range) the diagnostic scopes to.

  • affected_transaction_ids – Tuple of stable transaction identifiers the diagnostic refers to. Empty for file-wide diagnostics (e.g., a malformed header).

Parameters:
kind: LedgerImportDiagnosticKind
severity: BaseSeverity
message: tr
source_path: Path | None
source_locator: str | None
affected_transaction_ids: tuple[str, ...]
build_ledger_import_diagnostic(*, kind, severity, message, source_path=None, source_locator=None, affected_transaction_ids=())[source]

Construct a diagnostic with the canonical field order.

Centralised factory so adding new optional metadata later means extending this helper rather than every emit site. The returned LedgerImportDiagnostic preserves the closed LedgerImportDiagnosticKind and BaseSeverity values the CLI groups by.

Return type:

LedgerImportDiagnostic

Parameters: