GnuCash File

class gnucash_file.GnuCashFile(books: list[Book] | None = None)[source]

Class representing a GnuCash file on disk.

build_file(target_file: str, file_format: Any, prettify_xml: bool = False) → None[source]

Writes the contents of the GnuCashFile object out to a .gnucash file on disk.

Parameters:

  • target_file (str) – Full or relative path to the target file

  • file_format (Any) – Class handling the writing of the GnuCash file. See ‘file_formats’ for more info.

  • prettify_xml (bool) – Prettifies XML before writing to disk. Default False.

classmethod read_file(source_file: str | PathLike, file_format: Any, sort_transactions: bool = True, sort_method: SortingMethod | None = None) → GnuCashFile[source]

Reads the specified .gnucash file and loads it into memory.

Parameters:

  • source_file (Union[str, PathLike]) – Full or relative path to the .gnucash file.

  • file_format (BaseFileFormat subclass) – File format of the file being uploaded.

  • sort_transactions (bool) – Flag for if transactions should be sorted by date_posted when reading from XML

  • sort_method (SortingMethod) – SortingMethod class instance that determines the sort order for the transactions.

Returns:

New GnuCashFile object

Return type:

GnuCashFile

simplify_transactions() → None[source]

Converts every transaction to a SimpleTransaction.

strip_transaction_timezones() → None[source]

Removes timezone information from the date_posted and date_entered properties in every transaction.

class gnucash_file.Book(root_account: Account | None = None, transactions: TransactionManager | None = None, commodities: list[Commodity] | None = None, slots: list[Slot] | None = None, template_root_account: Account | None = None, template_transactions: list[Transaction] | None = None, scheduled_transactions: list[ScheduledTransaction] | None = None, budgets: list[Budget] | None = None, guid: str | None = None, sort_method: SortingMethod | None = None)[source]

Represents a Book in GnuCash.

accounts_query() → Query[source]

Get a new Query object to query accounts.

Returns:

New Query object

Return type:

Query

get_account(*paths_to_account: str, **kwargs: Any) → Account | None[source]

Retrieves an account based on a path of account names.

Parameters:

  • paths_to_account – Names of accounts that indicate the path

  • kwargs (dict) – Keyword arguments.

Returns:

Account object if found, otherwise None

Return type:

NoneType|Account

Example: get_account('Assets', 'Current Assets', 'Checking Account')

Keyword Arguments:

  • current_level = Account to start searching from. If no account is provided, root account is assumed.

get_account_balance(account: Account) → Decimal[source]

Retrieves the balance for a specified account based on the transactions in the Book.

Parameters:

account (Account) – Account object to retrieve the balance of.

Returns:

Account balance if applicable transactions found, otherwise 0.

Return type:

decimal.Decimal or int

get_all_accounts() → Generator[Account | None, None, None][source]

Returns a generator that retrieves all accounts, starting with the root account and going depth-first.

Returns:

A generator to a depth-first list of all accounts.

Return type:

collections.Iterable[Account]

class gnucash_file.Budget(guid: str | None = None, slots: list[Slot] | None = None, name: str | None = None, description: str | None = None, period_count: int | None = None, recurrence_multiplier: int | None = None, recurrence_period_type: RecurrencePeriodType | None = None, recurrence_start: datetime | None = None)[source]

Class object representing a Budget in GnuCash.

all_periods(account: Account, amount: Decimal, action: AllPeriodsActionType) → None[source]

Applies an amount to a given account over all budget periods using the indicated action.

Parameters:

  • account (Account) – Account that the amount should be applied for.

  • amount (Decimal) – Amount for that account in a given period.

  • action (AllPeriodsActionType) – Action to take on each period (replace, add, or multiply).

clear(account: Account | None = None, index: int | None = None) → None[source]

Clear specific amounts or all slots in the budget.

This method allows clearing data from the internal slots based on the given account and/or index parameters. If neither account nor index is provided, it will clear all slots. Otherwise, it will selectively remove entries matching the specified criteria.

Parameters:

  • account (Optional[Account]) – The account instance to clear slots from. If None, the operation is performed for all accounts.

  • index (Optional[int]) – The specific index in the slots of the account to clear. If None, all indices in the account are cleared.

Returns:

None

estimate(account: Account, transactions: TransactionManager, start_date: datetime, average: bool = False) → None[source]

Estimates the cost for each recurrence period, using the average if specified.

Parameters:

  • account (Account) – Account that the amount should be applied for.

  • transactions (TransactionManager) – TransactionManager of transactions to analyze.

  • start_date (datetime) – Date to start estimating from.

  • average (bool) – Should the average value across all periods be used? (default false)

get_budget_accounts(accounts: list[Account] | Generator[Account, None, None]) → Generator[Account, None, None][source]

Filters the given accounts to identify those that are associated with the budget.

The method iterates through the provided list of accounts and determines if their GUIDs match with the keys of the existing slots. If a match is found, the account is added to the resulting list.

Parameters:

accounts (Union[list[Account], Generator[Account, None, None]]) – A list or generator of Account objects to be filtered.

Returns:

A list of Account objects that match against the budget accounts.

Return type:

list[Account]

get_period_amount(account: Account, index: int) → Decimal | None[source]

Get the period amount of a specific account and index.

This method iterates through the slots to find a match for the specified account’s unique identifier (GUID) and the provided index. Upon locating a match, it converts the fraction amount of the matched subslot into a decimal and returns it.

Parameters:

  • account (Account) – The account whose period amount is being retrieved.

  • index (int) – The index for which the period amount is being looked up.

Returns:

The period amount as a Decimal if the account and index match is found, otherwise None.

Return type:

Optional[Decimal]

get_period_index(date: datetime) → int | None[source]

Determines the index of the recurrence period that contains the specified date.

This method iterates through generated recurrence periods and checks if the provided date falls between the start and end date of any period. If a match is found, the index of that period is returned. If no matching period is found, the method returns None.

Parameters:

date (datetime) – The date to evaluate against the recurrence periods.

Returns:

The index of the period containing the given date, or None if no matching period is found.

Return type:

Optional[int]

set_period_amount(account: Account, index: int, amount: Decimal) → None[source]

Sets the amount for a specific period in a specific account.

The amount is stored as a fraction in string representation. If the period or account does not already exist, it gets created.

Parameters:

  • account (Account) – The account object where the period amount should be set.

  • index (int) – The index identifying the target period.

  • amount (Decimal) – The amount to be set for the specific period, as a Decimal.

Returns:

None

Return type:

None

Raises:

ValueError – If the “period_count” attribute is not set.