aeat.application.review._filter module

Typed --filter KEY=VALUE parser for review commands.

The CLI routes every record-list command through --filter KEY=VALUE flags. Representative invocations:

  • aeat app ledger review --filter status=pending --filter period=1T --filter year=2026

  • aeat app ledger review --filter issue=gap --filter period=1T --filter year=2026

  • aeat app ledger review --filter issue=duplicate --filter period=1T --filter year=2026

  • aeat app ledger review --filter import=import_003 --filter period=1T --filter year=2026

  • invoice evidence and modelo work-unit queue filters

  • modelo status filters by period and modelo code

The CLI parses the raw argv strings; this module provides the typed substrate that turns them into FilterClause records and binds them to per-scope LedgerReviewFilterSpec / InvoiceReviewFilterSpec / DeclaracionReviewFilterSpec records. Each spec validates its own closed key catalogue, validates each value against per-key rules (calendar period parsing, closed enum values, identifier-shape checks), and exposes typed accessors the orchestration layer reads instead of re-parsing strings at every ReviewQueue / aggregator call site.

The specs are parsing surfaces; the actual filtering logic lives in aeat.application.review.ReviewQueue and the per-scope adapters.

class FilterClause(**data)[source]

Bases: BaseModel

One typed KEY=VALUE clause from a --filter flag.

Variables:
Parameters:
key: str
value: str
parse_filter_clause(raw)[source]

Parse one raw KEY=VALUE string into a FilterClause.

Parameters:

raw (str) – The raw KEY=VALUE token supplied by the operator.

Return type:

FilterClause

Returns:

A validated FilterClause with the parsed key and value.

Raises:

FilterParseError – When the token is missing =, has an empty key, or has an empty value. The error carries the offending raw token verbatim.

parse_filter_clauses(raw)[source]

Parse a sequence of KEY=VALUE strings into typed FilterClause instances.

The order of input strings is preserved in the output tuple so the CLI can render a deterministic diagnostic.

Return type:

tuple[FilterClause, ...]

Parameters:

raw (Iterable[str])

class LedgerReviewFilterKey(*values)[source]

Bases: StrEnum

Closed catalogue of aeat app ledger review --filter keys.

Variables:

  • STATUS – Lifecycle state of the row (pending / reviewed / skipped).

  • PERIOD – Filing period the row falls into, as a bare AEAT token: 1T..``4T`` (quarters), 0A (annual), or 01..``12`` (months). The filing year travels as a separate year= clause — there is no year-qualified combined token.

  • YEAR – Filing year (YYYY) supplying the year context the bare period= token needs; required whenever period= is present.

  • ISSUE – Filters to rows that carry an import-time diagnostic (gap / duplicate / original-file / parser).

  • IMPORT – Filters to rows from a specific import-batch id.

  • CLASSIFICATION – Filters to rows with a given business classification (business / personal / mixed / not_yet_processed …).

  • DIRECTION – Filters to rows by money-flow direction — incoming (ingreso), outgoing (gasto), or internal_transfer.

STATUS
PERIOD
YEAR
ISSUE
IMPORT
CLASSIFICATION
TEXT
DIRECTION
class LedgerReviewStatus(*values)[source]

Bases: StrEnum

Closed catalogue of ledger status= filter values.

PENDING
REVIEWED
SKIPPED
EXCLUDED
class InvoiceReviewFilterKey(*values)[source]

Bases: StrEnum

Closed catalogue of invoice-evidence review filter keys.

Variables:

  • STATUS – Lifecycle state of the invoice (pending / reviewed / matched).

  • KIND – Issued-vs-received discriminator. Values come from aeat.domain.invoices.InvoiceKind.

STATUS
KIND
class InvoiceReviewStatus(*values)[source]

Bases: StrEnum

Closed catalogue of invoice status= filter values.

PENDING
REVIEWED
MATCHED
PAID
class DeclaracionReviewFilterKey(*values)[source]

Bases: StrEnum

Closed catalogue of modelo status filter keys.

Variables:

STATUS – Lifecycle state of the draft (pending / approved / stale / submitted / acknowledged).

STATUS
class DeclaracionReviewStatus(*values)[source]

Bases: StrEnum

Closed catalogue of declaration status= filter values.

PENDING
APPROVED
STALE
SUBMITTED
ACKNOWLEDGED
class LedgerReviewFilterSpec(**data)[source]

Bases: BaseModel

Typed aeat app ledger review --filter spec.

Variables:

  • clauses – The raw clauses, in input order. Empty when the command is invoked without --filter.

  • status – Resolved LedgerReviewStatus if status= was provided.

  • period – Resolved filing period when period= and year= were provided. The raw clauses remain available on clauses; consumers receive the core value object directly.

  • issue – Resolved LedgerImportDiagnosticKind if issue= was provided.

  • import_id – Raw import-batch id if import= was provided. Identifier-shape validation lives on the aeat.application.transactions import surface.

Parameters:
clauses: tuple[FilterClause, ...]
status: LedgerReviewStatus | None
period: Period | None
issue: LedgerImportDiagnosticKind | None
import_id: str | None
classification: BusinessClassification | None
text: str | None
direction: TransactionDirection | None
classmethod from_strings(raw)[source]

Parse --filter arguments into a typed LedgerReviewFilterSpec.

Return type:

LedgerReviewFilterSpec

Parameters:

raw (Iterable[str])

class InvoiceReviewFilterSpec(**data)[source]

Bases: BaseModel

Typed invoice-evidence review filter spec.

Variables:
Parameters:
clauses: tuple[FilterClause, ...]
status: InvoiceReviewStatus | None
kind: InvoiceKind | None
classmethod from_strings(raw)[source]

Parse --filter arguments into a typed invoice spec.

Returns an InvoiceReviewFilterSpec with filter fields populated from the parsed key=value clause strings.

Return type:

InvoiceReviewFilterSpec

Parameters:

raw (Iterable[str])

class DeclaracionReviewFilterSpec(**data)[source]

Bases: BaseModel

Typed modelo status filter spec.

Variables:
Parameters:
clauses: tuple[FilterClause, ...]
status: DeclaracionReviewStatus | None
classmethod from_strings(raw)[source]

Parse --filter arguments into a typed DeclaracionReviewFilterSpec.

Return type:

DeclaracionReviewFilterSpec

Parameters:

raw (Iterable[str])