cadrumo.entrypoints.tui.ledger.controller module¶

Pure controller and common interaction shell for Ledger destinations.

ledger_copy(key, **values)[source]¶

Resolve all operator copy through the canonical catalogue boundary.

Return type:

str

Parameters:

key (str)
values (object)

area_label(area)[source]¶

Return an operator label without displaying an internal enum token.

Return type:: str
Parameters:: area (LedgerWorkspaceArea)

availability_label(availability)[source]¶

Render availability with a textual cue independent of colour.

Return type:: str
Parameters:: availability (LedgerWorkspaceAvailability)

review_status_label(status)[source]¶

Translate a source status without leaking its transport spelling.

Return type:: str
Parameters:: status (str)

status_label(status)[source]¶

Render source status through its authored catalogue key.

Return type:: str
Parameters:: status (LedgerWorkspaceStatus)

item_count_label(state)[source]¶

Keep an unmeasured denominator distinct from a measured numeric zero.

Return type:: str
Parameters:: state (LedgerWorkspaceAreaStateV1)

class LedgerWorkspaceController(context, projection, injection)[source]¶

Bases: object

Read-only custody of one injected application projection and shell context.

Parameters:

context (TuiScreenContextV1)
projection (LedgerWorkspaceProjectionV1)
injection (LedgerWorkspaceInjection)

classification_target_coordinate()[source]¶

Return a safe position and redacted identifier from the visible projection.

Return type:: tuple[int, int, str]

entry_label(transaction_id)[source]¶

Name one entry the way the operator recorded it: its date and description.

An entry the projection does not carry falls back to its short identifier rather than to a blank cell.

Return type:: str
Parameters:: transaction_id (TransactionId)

state_for(area)[source]¶

Return the application-owned area state.

Return type:: LedgerWorkspaceAreaStateV1
Parameters:: area (LedgerWorkspaceArea)

route_target(area)[source]¶

Build an internal semantic target without invoking it.

The destination comes from the canonical pairing rather than a copy held here, so this cannot name a screen the route catalogue does not have. The lookup needs no cast: the pairing is typed as the destination alias, so a misspelling is a type error at the declaration instead of an assertion the checker believes.

Return type:: LedgerRouteTargetV1
Parameters:: area (LedgerWorkspaceArea)

refusal_for(area)[source]¶

Preserve application refusal separately from deferred screen availability.

Return type:: LedgerRouteRefusalV1 | None
Parameters:: area (LedgerWorkspaceArea)

entry_rows()[source]¶

Narrow safe application entry references without recovering payloads.

Return type:: tuple[LedgerEntryRowV1, ...]

with_transaction_focus(transaction_id)[source]¶

Re-address this workspace at one visible entry, carrying nothing else.

Selection travels in context.focus — the channel restored_transaction_id() already reads for cursor restore — so there is one answer to “which entry is the operator on”. A separate mutable attribute beside it would let the restored cursor and the classification target disagree about the same question.

Returns a NEW controller rather than mutating, because the context is frozen. An internal area move resolves its next screen synchronously against whatever controller the outgoing screen holds, so rebinding there is what carries the selection across a body swap — with no extra screen push, and therefore no result callback left registered against a pump that is about to stop.

The context is constructed explicitly rather than by model_copy: model_copy skips validation, and the focus/destination agreement check is the thing stopping a focus from naming another workspace.

Raises:: ValueError – When the entry is not in the visible projection. An entry the operator cannot see is one they cannot have chosen.
Return type:: LedgerWorkspaceController
Parameters:: transaction_id (TransactionId)

property classification_target: TransactionId | None¶: The entry the operator selected, read from the one focus channel.

restored_transaction_id()[source]¶

Resolve a transaction focus by semantic identity, never by row position.

Return type:: TypeAliasType | None

review_rows()[source]¶

Join review identities to safe entry references, refusing contradictions.

Return type:: tuple[LedgerReviewRowV1, ...]

async submit_classification(patch)[source]¶

Submit an explicit patch through the injected authorized door.

Return type:: ManualLedgerTransactionResult
Parameters:: patch (ManualLedgerTransactionPatch)

async preview_import(request)[source]¶

Ask the injected import door what applying request would do.

Return type:: LedgerImportOutcomeV1
Parameters:: request (LedgerImportRequestV1)

async apply_import(request)[source]¶

Write a previewed import through the injected door.

Return type:: LedgerImportOutcomeV1
Parameters:: request (LedgerImportRequestV1)

can_exclude()[source]¶

Report whether excluding an entry is admitted: the classify authority and its writer.

Return type:: bool

async submit_exclusion(transaction_id)[source]¶

Exclude one entry the operator can see in the review list.

Return type:: ManualLedgerTransactionResult
Parameters:: transaction_id (TransactionId)

can_add_invoices()[source]¶

Report whether the invoice writer door is admitted in this session.

Return type:: bool

async add_invoice(entry)[source]¶

Record one typed invoice through the injected catalogue writer.

Return type:: LedgerInvoiceAddResultV1
Parameters:: entry (LedgerInvoiceEntryV1)

evidence_records()[source]¶

Read the local evidence records, or None when no door reads them.

Return type:: tuple[LedgerEvidenceRecordRowV1, ...] | None

async add_evidence(source_path)[source]¶

Return type:: LedgerEvidenceRecordRowV1
Parameters:: source_path (str)

async extract_evidence(evidence_id)[source]¶

Read one registered document through the injected evidence door.

Return type:: LedgerEvidenceDraftV1
Parameters:: evidence_id (str)

async confirm_evidence(confirmation)[source]¶

Record one read document as an invoice through the injected evidence door.

Return type:: LedgerEvidenceConfirmedV1
Parameters:: confirmation (LedgerEvidenceConfirmationV1)

reader_readiness()[source]¶

Measure the local reader, or None when no door can measure it.

Return type:: LedgerReaderReadinessV1 | None

can_refresh()[source]¶

Report whether this workspace can re-read its state after a write.

Return type:: bool

refreshed()[source]¶

Return this workspace re-read from the current profile state.

The focus is kept only while the entry it names is still visible; a focus on a row the write removed would otherwise address nothing.

Return type:: LedgerWorkspaceController

evidence_rows()[source]¶

Project only canonical review-safe metadata from the injected result.

Return type:: tuple[LedgerEvidenceRowV1, ...]

restored_evidence_id()[source]¶

Restore evidence focus by semantic application identity.

Return type:: str | None

can_submit_links()[source]¶

Report whether the optional local link-mutation door is admitted.

Return type:: bool

async submit_link(transaction_id, invoice_id)[source]¶

Admit a visible suggestion and submit it through the authorized door.

Return type:

LedgerLinkResultV1

Parameters:

transaction_id (TransactionId)
invoice_id (InvoiceId)

class LedgerRouteRequested(target)[source]¶

Bases: Message

Host-facing request to replace the active Ledger destination body.

Parameters:: target (LedgerRouteTargetV1)

time¶

bubble: ClassVar[bool]¶

handler_name: ClassVar[str]¶: Name of the default message handler.

no_dispatch: ClassVar[bool]¶

verbose: ClassVar[bool]¶

class LedgerReviewRequested(*, transaction_id, action)[source]¶

Bases: Message

Host-facing request naming a real application query and transaction focus.

Parameters:

transaction_id (TransactionId)
action (ActionReference)

time¶

bubble: ClassVar[bool]¶

handler_name: ClassVar[str]¶: Name of the default message handler.

no_dispatch: ClassVar[bool]¶

verbose: ClassVar[bool]¶

class LedgerEvidenceReviewRequested(*, attachment_id, action)[source]¶

Bases: Message

Host-facing request carrying the canonical evidence-review query.

Parameters:

attachment_id (str)
action (ActionReference)

time¶

bubble: ClassVar[bool]¶

handler_name: ClassVar[str]¶: Name of the default message handler.

no_dispatch: ClassVar[bool]¶

verbose: ClassVar[bool]¶

class LedgerEntrySelected(transaction_id)[source]¶

Bases: Message

Host-facing semantic selection of one safe Ledger entry reference.

Parameters:: transaction_id (TransactionId)

time¶

bubble: ClassVar[bool]¶

handler_name: ClassVar[str]¶: Name of the default message handler.

no_dispatch: ClassVar[bool]¶

verbose: ClassVar[bool]¶

class LedgerBackRequested[source]¶

Bases: Message

Request that the owning host return to the parent destination.

time¶

bubble: ClassVar[bool]¶

handler_name: ClassVar[str]¶: Name of the default message handler.

no_dispatch: ClassVar[bool]¶

verbose: ClassVar[bool]¶

class LedgerInvoiceEntryRequested[source]¶

Bases: Message

Request the invoice entry form as the workspace body.

time¶

bubble: ClassVar[bool]¶

handler_name: ClassVar[str]¶: Name of the default message handler.

no_dispatch: ClassVar[bool]¶

verbose: ClassVar[bool]¶

class LedgerWorkspaceScreen(controller, *, id=None)[source]¶

Bases: AccountChromeScreen

Shared one-scroll shell and semantic navigation behavior.

Parameters:

controller (LedgerWorkspaceController)
id (str | None)

BINDINGS: ClassVar¶: A list of key bindings.

IS_WORKSPACE_OVERVIEW: ClassVar[bool]¶: Whether Back from this body leaves the workspace rather than returning to its overview.

CSS: ClassVar[str]¶: Inline CSS, useful for quick scripts. Rules here take priority over CSS_PATH.

Note

This CSS applies to the whole app.

refreshing¶: Whether a re-read of the workspace is running off the event loop.

refresh_seconds: list[float]¶: How long each completed re-read took, newest last.

refresh_then(then)[source]¶

Re-read the workspace off the event loop, then continue with then.

A capture reads every catalogue the workspace projects, which takes seconds on a real ledger; on the loop that froze every key. A request made while one is already running does not start a second read: it replaces what happens when the running one lands, so the operator’s last intent wins and the store is read once.

Return type:: None
Parameters:: then (Callable[[], object])

populate_navigation()[source]¶

Populate the complete seven-area catalogue in canonical order.

Return type:: None

handle_navigation_selection(event)[source]¶

Handle the common navigation table and expose refusals as visible copy.

Return type:: bool
Parameters:: event (RowSelected)

action_back()[source]¶

Ask the host to return; never terminate the application.

Return type:: None

on_ledger_entry_selected(event)[source]¶

Re-address the workspace at the chosen entry and repaint navigation.

Lives on the shared base rather than on the entries screen because the controller is shared: review and reconciliation restore their cursor from the same focus, so a selection made anywhere is the selection everywhere.

The controller is REBOUND, not mutated — with_transaction_focus returns a new one — so the next area move, which resolves its screen against self.controller, carries the selection across the body swap without any extra push. The navigation table is rebuilt because classification’s reachability has just changed, and a stale row would keep offering the old refusal.

Return type:: None
Parameters:: event (LedgerEntrySelected)

on_ledger_route_requested(event)[source]¶

Resolve the requested area here and hand the finished body to the host.

Textual delivers a screen’s own posted message to it before bubbling, so the workspace answers its own navigation: it owns the controller and the route catalogue, and the host owns only the screen stack.

Return type:: None
Parameters:: event (LedgerRouteRequested)

on_ledger_invoice_entry_requested(_)[source]¶

Open the invoice entry form, or say why it cannot open in this session.

Return type:: None
Parameters:: _ (LedgerInvoiceEntryRequested)

on_ledger_back_requested(_)[source]¶

Return an area to the Ledger overview; leave the workspace only from the overview.

Return type:: None
Parameters:: _ (LedgerBackRequested)

can_focus: bool¶: Widget may receive focus.

can_focus_children: bool¶: Widget’s children may receive focus.

on_ledger_review_requested(_)[source]¶

Say that the selection led nowhere, rather than appearing to work.

Selecting a review row names a real query action, but no production consumer executes one yet. Answering with the pending-area copy is the honest state: an unhandled message is indistinguishable from a dead keypress, and that silence is precisely how the workspace navigation defect stayed invisible through the whole surface’s construction.

Return type:: None
Parameters:: _ (LedgerReviewRequested)

on_ledger_evidence_review_requested(_)[source]¶

Report the same pending state for an evidence-row selection.

Return type:: None
Parameters:: _ (LedgerEvidenceReviewRequested)