debt_optimizer.core.balance_updater module

Balance updater for syncing Quicken database balances with Excel workbook.

Reads account balances from Quicken SQLite database and updates corresponding entries in the Excel template using fuzzy matching.

exception debt_optimizer.core.balance_updater.BalanceUpdaterError[source]

Bases: Exception

Base exception for balance updater errors.

class debt_optimizer.core.balance_updater.BalanceUpdater(db_path, fuzzy_threshold=80, bank_account_name='PECU Checking', auto_backup=True)[source]

Bases: object

Updates Excel workbook balances from Quicken database.

Parameters:

  • db_path (Path)

  • fuzzy_threshold (int)

  • bank_account_name (str)

  • auto_backup (bool)

__init__(db_path, fuzzy_threshold=80, bank_account_name='PECU Checking', auto_backup=True)[source]

Initialize balance updater.

Parameters:

  • db_path (Path) – Path to Quicken SQLite database

  • fuzzy_threshold (int) – Minimum score for fuzzy matches (0-100)

  • bank_account_name (str) – Name of checking account to use for bank balance

  • auto_backup (bool) – Whether to create backup before updating

backup_excel(xlsx_path)[source]

Create timestamped backup of Excel file.

Parameters:

xlsx_path (Path) – Path to Excel file

Return type:

Path

Returns:

Path to backup file

connect_db()[source]

Connect to Quicken database in read-only mode.

Return type:

Connection

Returns:

SQLite connection

load_quicken_balances()[source]

Load account balances from Quicken database.

Calculates balance as Quicken register shows it: - Prioritizes register balance (sum of all transactions dated today or earlier) - Falls back to ZONLINEBANKINGLEDGERBALANCEAMOUNT if no transactions exist - Includes ALL transactions (reconciled, cleared, and uncleared) dated today or earlier - Excludes only future-dated transactions

This matches Quicken’s register balance which includes all transaction statuses dated on or before today. Uses Apple Cocoa timestamp format (seconds since 2001-01-01).

Returns:

E501

Return type:

Tuple of (accounts_by_name, credit_card_names, checking_names, savings_names) # noqa

update_debts_sheet(ws, accounts_by_name, credit_card_names)[source]

Update debt balances in Debts sheet.

Parameters:

  • ws – openpyxl worksheet

  • accounts_by_name (Dict[str, Dict]) – Dictionary of account data by name

  • credit_card_names (List[str]) – List of credit card account names

Return type:

List[Dict]

Returns:

List of update records

update_settings_sheet(ws, accounts_by_name, checking_names)[source]

Update current bank balance in Settings sheet.

Parameters:

  • ws – openpyxl worksheet

  • accounts_by_name (Dict[str, Dict]) – Dictionary of account data by name

  • checking_names (List[str]) – List of checking account names

Return type:

Optional[Dict]

Returns:

Update record or None if not updated

update_workbook(xlsx_path, interactive=True)[source]

Update Excel workbook with balances from Quicken database.

Parameters:

  • xlsx_path (Path) – Path to Excel workbook

  • interactive (bool) – Whether to prompt for fuzzy matches

Return type:

Dict[str, Any]

Returns:

Dictionary with update summary

Raises: