Helpers
Use these helpers to build a complete replacement tag list, inspect skipped
transaction groups, format amounts, or find matching candidates. match()
compares only date and absolute amount; inspect other fields before treating
matches as duplicates.
match(tx: SimplifiedTx, records: Iterable[SimplifiedItem]) -> list[SimplifiedItem]
Find candidates with the same date and absolute amount.
This uses SimplifiedItem equality. IDs, currency, description, tags,
and external IDs are not checked. Review candidates before deduplication.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tx
|
SimplifiedTx
|
Firefly III transaction to compare. |
required |
records
|
Iterable[SimplifiedItem]
|
Candidate items to scan once. |
required |
Returns:
| Type | Description |
|---|---|
list[SimplifiedItem]
|
Every matching item, preserving the input order. |
build_add_tag_payload(tx: SimplifiedTx, tag: str) -> list[str]
Build a replacement tag list with one tag added if missing.
The returned list is independent of tx.tags and preserves its order.
Pass it as TransactionUpdate(tags=...) to avoid replacing all existing
tags with just the new one.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tx
|
SimplifiedTx
|
Transaction whose current tags should be retained. |
required |
tag
|
str
|
Tag name to add. |
required |
Returns:
| Type | Description |
|---|---|
list[str]
|
A new list containing the original tags and, if needed, |
fetch_transactions_with_stats(client: FireflyClient, *, tx_type: str = 'withdrawal', page_size: int = 1000, max_pages: int | None = None, start_date: date | None = None, end_date: date | None = None) -> tuple[list[SimplifiedTx], FetchTransactionsStats]
async
Fetch transactions while counting skipped groups.
Accepts the same filters as FireflyClient.fetch_transactions(). The
returned list contains only successfully mapped single-split groups.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client
|
FireflyClient
|
Open Firefly III client. |
required |
tx_type
|
str
|
Firefly III transaction type filter. |
'withdrawal'
|
page_size
|
int
|
Requested groups per API page. |
1000
|
max_pages
|
int | None
|
Maximum pages, or |
None
|
start_date
|
date | None
|
Inclusive start date, if supplied. |
None
|
end_date
|
date | None
|
Inclusive end date, if supplied. |
None
|
Returns:
| Type | Description |
|---|---|
tuple[list[SimplifiedTx], FetchTransactionsStats]
|
A pair of mapped transactions and mapping statistics. |
Raises:
| Type | Description |
|---|---|
FireflyAPIError
|
A request fails or an API page has an invalid schema. |
FetchTransactionsStats
dataclass
Mapping counts and elapsed time for a transaction fetch.
Attributes:
| Name | Type | Description |
|---|---|---|
total |
int
|
Successfully mapped transaction groups. |
multipart |
int
|
Groups skipped because they contain multiple splits. |
invalid |
int
|
Groups skipped because mapping failed. |
duration_ms |
int
|
Elapsed time in whole milliseconds. |
format_amount(amount: Decimal, decimals: int) -> str
Round an amount for display using decimal half-up rounding.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
amount
|
Decimal
|
Decimal amount to format. |
required |
decimals
|
int
|
Number of digits after the decimal point. |
required |
Returns:
| Type | Description |
|---|---|
str
|
Rounded decimal string without a currency symbol. |