File Formats

XML

class file_formats.gnucash_xml.XMLFileFormat

Class containing the logic for loading and saving XML files.

class file_formats.gnucash_xml.GZipXMLFileFormat

Class containing the logic for loading and saving XML files with GZip compression.

classmethod get_xml_root(source_path: Path) → Element

Retrieves the XML root element from a GZipped XML file.

Parameters:

source_path (str) – Path to GZipped XML File.

Returns:

XML root element

Return type:

ElementTree.Element

classmethod write_file_contents(target_file: str, file_contents: bytes) → None

Writes the specified contents to the target file, with a level 9 GZip compression.

Parameters:

• target_file (str) – Target GZip file to write to.

• file_contents (bytes) – Contents to write to the GZip file

class file_formats.gnucash_xml.GnuCashXMLReader

Class containing the logic for loading XML files.

LOGGER = <RootLogger root (WARNING)>

classmethod create_account_from_xml(account_node: Element, account_objects: list[Account]) → Account

Creates an Account object from the GnuCash XML.

Parameters:

• account_node (ElementTree.Element) – XML node for the account

• account_objects (list[Account]) – Account objects already created from XML (used for assigning parent account)

Returns:

Account object from XML

Return type:

Account

classmethod create_book_from_xml(book_node: Element, sort_transactions: bool = True, sort_method: SortingMethod | None = None) → Book

Creates a Book object from the GnuCash XML.

Parameters:

• book_node (ElementTree.Element) – XML node for the book

• 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:

Book object from XML

Return type:

Book

classmethod create_budget_from_xml(budget_node: Element) → Budget

Creates a Budget object from the GnuCash XML.

Parameters:

budget_node (ElementTree.Element) – XML node for the budget

Returns:

Budget object from XML

Return type:

Budget

classmethod create_commodity_from_xml(commodity_node: Element) → Commodity

Creates a Commodity object from the GnuCash XML.

Parameters:

commodity_node (ElementTree.Element) – XML node for the commodity

Returns:

Commodity object from XML

Return type:

Commodity

classmethod create_scheduled_transaction_from_xml(xml_obj: Element, template_account_root: Account | None) → ScheduledTransaction

Creates a ScheduledTransaction object from the GnuCash XML.

Parameters:

• xml_obj (ElementTree.Element) – XML node for the scheduled transaction

• template_account_root (Account) – Root template account

Returns:

ScheduledTransaction object from XML

Return type:

ScheduledTransaction

classmethod create_slot_from_xml(slot_node: Element) → Slot

Creates a Slot object from the GnuCash XML.

Parameters:

slot_node (ElementTree.Element) – XML node for the slot

Returns:

Slot object from XML

Return type:

Slot

classmethod create_split_from_xml(split_node: Element, account_objects: list[Account]) → Split

Creates an Split object from the GnuCash XML.

Parameters:

• split_node (ElementTree.Element) – XML node for the split

• account_objects (list[Account]) – Account objects already created from XML (used for assigning parent account)

Returns:

Split object from XML

Return type:

Split

classmethod create_transaction_from_xml(transaction_node: Element, account_objects: list[Account]) → Transaction

Creates a Transaction object from the GnuCash XML.

Parameters:

• transaction_node (ElementTree.Element) – XML node for the transaction

• account_objects (list[Account]) – Account objects already created from XML (used for assigning accounts)

Returns:

Transaction object from XML

Return type:

Transaction

classmethod get_xml_root(source_path: Path) → Element

Retrieves the root element from a given XML document.

Parameters:

source_path (pathlib.Path) – Path to XML document

Returns:

Root element

Return type:

ElementTree.Element

classmethod load(*args: Any, source_file: Path | None = None, sort_transactions: bool = True, sort_method: SortingMethod | None = None, **kwargs: Any) → GnuCashFile

Loads a GnuCash XML file from disk to memory.

Parameters:

• source_file (str) – File to load from disk

• sort_transactions (bool) – Should transactions be sorted by date posted

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

Returns:

GnuCashFile object

Return type:

GnuCashFile

classmethod read_xml_child_boolean(xml_object: Element, tag_name: str, namespaces: dict[str, str]) → bool | None

Reads the text from a specific child XML element and returns a Boolean if the text is “Y” or “y”.

Parameters:

• xml_object (ElementTree.Element) – Current XML object

• tag_name (str) – Child tag name

• namespaces (dict[str, str]) – GnuCash namespaces

Returns:

True if child node’s text is “Y” or “Y”, otherwise False.

Return type:

bool

classmethod read_xml_child_date(xml_object: Element, tag_name: str, namespaces: dict[str, str]) → datetime | None

Reads the text from a specific child XML element and returns its inner gdate text as a datetime.

Parameters:

• xml_object (ElementTree.Element) – Current XML object

• tag_name (str) – Child tag name

• namespaces (dict[str, str]) – GnuCash namespaces

Returns:

Child’s gdate’s text as datetime

Return type:

datetime.datetime

classmethod read_xml_child_int(xml_object: Element, tag_name: str, namespaces: dict[str, str]) → int | None

Reads the text from a specific child XML element and returns its text as an integer value.

Parameters:

• xml_object (ElementTree.Element) – Current XML object

• tag_name (str) – Child tag name

• namespaces (dict[str, str]) – GnuCash namespaces

Returns:

Child’s text as an integer value

Return type:

int

classmethod read_xml_child_text(xml_object: Element, tag_name: str, namespaces: dict[str, str]) → str | None

Reads the text from a specific child XML element.

Parameters:

• xml_object (ElementTree.Element) – Current XML object

• tag_name (str) – Child tag name

• namespaces (dict[str, str]) – GnuCash namespaces

Returns:

Child node’s text

Return type:

str

class file_formats.gnucash_xml.GnuCashXMLWriter

Class containing the logic for saving XML files.

LOGGER = <RootLogger root (WARNING)>

classmethod cast_account_as_xml(account: Account) → list[Element]

Returns the current account configuration (and all of its child accounts) as GnuCash-compatible XML.

Returns:

Current account and children as XML

Return type:

list[xml.etree.ElementTree.Element]

Raises:

ValueError if no commodity found.

classmethod cast_book_as_xml(book: Book) → Element

Returns the current book as GnuCash-compatible XML.

Returns:

ElementTree.Element object

Return type:

xml.etree.ElementTree.Element

classmethod cast_budget_as_xml(budget: Budget) → Element

Returns the current budget as GnuCash-compatible XML.

Returns:

Current budget as XML

Return type:

xml.etree.ElementTree.Element

classmethod cast_commodity_as_short_xml(commodity: Commodity, node_tag: str) → Element

Returns the current commodity as GnuCash-compatible XML (short version used for accounts).

Parameters:

• commodity (Commodity) – Commodity being cast to short XML

• node_tag (str) – XML element tag name for the commodity

Returns:

Current commodity as short XML

Return type:

xml.etree.ElementTree.Element

classmethod cast_commodity_as_xml(commodity: Commodity) → Element

Returns the current commodity as GnuCash-compatible XML.

Returns:

Current commodity as XML

Return type:

xml.etree.ElementTree.Element

classmethod cast_scheduled_transaction_as_xml(scheduled_transaction: ScheduledTransaction) → Element

Returns the current scheduled transaction as GnuCash-compatible XML.

Returns:

Current scheduled transaction as XML

Return type:

xml.etree.ElementTree.Element

classmethod cast_slot_as_xml(slot: Slot) → Element

Returns the current slot as GnuCash-compatible XML.

Returns:

Current slot as XML

Return type:

xml.etree.ElementTree.Element

classmethod cast_split_as_xml(split: Split) → Element

Returns the current split as GnuCash-compatible XML.

Returns:

Current split as XML

Return type:

xml.etree.ElementTree.Element

classmethod cast_transaction_as_xml(transaction: Transaction) → Element

Returns the current transaction as GnuCash-compatible XML.

Returns:

Current transaction as XML

Return type:

xml.etree.ElementTree.Element

classmethod dump(gnucash_file: GnuCashFile, *args: Any, target_file: str = '', prettify_xml: bool = False, **kwargs: Any) → None

Writes GnuCash XML file from memory to disk.

Parameters:

• gnucash_file (GnuCashFile) – File to write to disk

• target_file (str) – Destination file to write to.

• prettify_xml (bool) – Should the XML be prettified? (default false)

Returns:

classmethod write_file_contents(target_file: str, file_contents: bytes) → None

Writes the file contents to the target file.

Parameters:

• target_file (str) – File that contents will be written to.

• file_contents (bytes) – Contents to be written to the file.

SQLite

class file_formats.gnucash_sqlite.SqliteFileFormat

Class containing the logic for loading and saving SQlite files.

class file_formats.gnucash_sqlite.GnuCashSQLiteReader

Class containing the logic for loading SQlite files.

classmethod create_account_from_sqlite(sqlite_cursor: Cursor, account_id: str) → Account

Creates an Account object from the GnuCash SQLite database.

Parameters:

• sqlite_cursor (sqlite3.Cursor) – Open cursor to the GnuCash SQLite database.

• account_id (str) – ID of the account to load from the SQLite database

Returns:

Account object from SQLite

Return type:

Account

classmethod create_books_from_sqlite(sqlite_cursor: Cursor, sort_transactions: bool, sort_method: SortingMethod | None = None) → list[Book]

Creates Book objects from the GnuCash SQLite database.

Parameters:

• sqlite_cursor (sqlite3.Cursor) – Open cursor to the SQLite database

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

• sort_method (SortingMethod) – SortingMethod instance indicating which method in which we should sort the transactions.

Returns:

Book objects from SQLite

Return type:

list[Book]

classmethod create_budget_from_sqlite(sqlite_cursor: Cursor) → list[Budget]

Creates Budget objects from the GnuCash SQLite database.

Parameters:

sqlite_cursor (sqlite3.Cursor) – Open cursor to the SQLite database

Returns:

Budget objects from SQLite

Return type:

list[Budget]

classmethod create_commodities_from_sqlite(sqlite_cursor: Cursor) → list[Commodity]

Creates Commodity objects for all commodities in the SQLite database.

Parameters:

sqlite_cursor (sqlite3.Cursor) – Open cursor to the SQLite database

Returns:

Commodity object(s) from SQLite

Return type:

list[Commodity]

classmethod create_commodity_from_sqlite(sqlite_cursor: Cursor, commodity_guid: str) → Commodity

Creates a Commodity object from the GnuCash SQLite database.

Parameters:

• sqlite_cursor (sqlite3.Cursor) – Open cursor to the SQLite database

• commodity_guid (str) – Commodity to pull from the database. None pulls all commodities.

Returns:

Commodity object(s) from SQLite

Return type:

Commodity or list[Commodity]

classmethod create_scheduled_transactions_from_sqlite(sqlite_cursor: Cursor, template_root_account: Account | None) → list[ScheduledTransaction]

Creates ScheduledTransaction objects from the GnuCash SQLite database.

Parameters:

• sqlite_cursor (sqlite3.Cursor) – Open cursor to the SQLite database

• template_root_account (Account) – Root template account

Returns:

ScheduledTransaction objects from SQLite

Return type:

list[ScheduledTransaction]

classmethod create_slots_from_sqlite(sqlite_cursor: Cursor, object_id: str) → list[Slot]

Creates Slot objects from the GnuCash SQLite database.

Parameters:

• sqlite_cursor (sqlite3.Cursor) – Open cursor to the SQLite database

• object_id (str) – ID of the object that the slot belongs to

Returns:

Slot objects from SQLite

Return type:

list[Slot]

classmethod create_splits_from_sqlite(sqlite_cursor: Cursor, transaction_guid: str, root_account: Account | None, template_root_account: Account | None) → list[Split]

Creates Split objects from the GnuCash SQLite database.

Parameters:

• sqlite_cursor (sqlite3.Cursor) – Open cursor to the SQLite database.

• transaction_guid (str) – GUID of the transaction to load the splits of

• root_account (Account) – Root account from the SQLite database

• template_root_account (Account) – Template root account from the SQLite database

Returns:

Split objects from XML

Return type:

list[Split]

classmethod create_transactions_from_sqlite(sqlite_cursor: Cursor, root_account: Account | None, template_root_account: Account | None) → list[Transaction]

Creates Transaction objects from the GnuCash SQLite database.

Parameters:

• sqlite_cursor (sqlite3.Cursor) – Open cursor to the SQLite database.

• root_account (Account) – Root account from the SQLite database

• template_root_account (Account) – Template root account from the SQLite database

Returns:

Transaction objects from SQLite

Return type:

list[Transaction]

classmethod get_sqlite_table_data(sqlite_cursor: Cursor, table_name: str, where_condition: str | None = None, where_parameters: tuple[Any] | None = None) → list[dict[str, Any]]

Helper method for retrieving data from a SQLite table.

Parameters:

• sqlite_cursor (sqlite3.Cursor) – Open cursor to a SQLite database.

• table_name (str) – SQLite table name

• where_condition (str) – SQL WHERE condition for the query (if any)

• where_parameters (tuple) – SQL WHERE parameters for the query (if any)

Returns:

List of dictionaries (keys being the column names) for each row in the SQLite table

Return type:

list[dict[str, Any]]

classmethod load(*args: Any, source_file: Path | None = None, sort_transactions: bool = True, sort_method: SortingMethod | None = None, **kwargs: Any) → GnuCashFile

Loads a GnuCash SQLite file from disk to memory.

Parameters:

• source_file (str) – File to load from disk

• sort_transactions (bool) – Should transactions be sorted

• sort_method (SortingMethod) – SortMethod class instance that determines which sort method to use

Returns:

GnuCashFile object

Return type:

GnuCashFile

class file_formats.gnucash_sqlite.GnuCashSQLiteWriter

Class containing the logic for saving SQlite files.

classmethod create_sqlite_schema(sqlite_cursor: Cursor) → None

Creates the SQLite schema using the provided SQLite cursor.

Parameters:

sqlite_cursor (sqlite3.Cursor) – Open cursor to a SQLite database.

classmethod delete_transaction_from_sqlite(deleted_transaction_guid: str, sqlite_cursor: Cursor) → None

Removes a transaction from the SQLite database, as well as all dependent objects.

classmethod dump(gnucash_file: GnuCashFile, *args: Any, target_file: str = '', **kwargs: Any) → None

Updates GnuCash SQLite file on disk from memory.

Parameters:

• gnucash_file (GnuCashFile) – File to write to disk

• target_file (str) – Destination file to write to.

Returns:

classmethod write_account_to_sqlite(account: Account, sqlite_cursor: Cursor) → None

Writes an Account object to the SQLite database.

Parameters:

• account (Account) – Account object

• sqlite_cursor (sqlite3.Cursor) – Handle to SQLite file

classmethod write_book_to_sqlite(book: Book, sqlite_cursor: Cursor) → None

Writes a Book object to the SQLite database.

Parameters:

• book (Book) – Book object

• sqlite_cursor (sqlite3.Cursor) – Handle to SQLite file

classmethod write_budget_to_sqlite(budget: Budget, sqlite_cursor: Cursor) → None

Writes a Budget object to the SQLite database.

Parameters:

• budget (Budget) – Budget object

• sqlite_cursor (sqlite3.Cursor) – Handle to SQLite database

classmethod write_commodity_to_sqlite(commodity: Commodity, sqlite_cursor: Cursor) → None

Writes a Commodity object to the SQLite database.

Parameters:

• commodity (Commodity) – Commodity object

• sqlite_cursor (sqlite3.Cursor) – Handle to SQLite file

classmethod write_recurrence_to_sqlite(obj: Budget, sqlite_cursor: Cursor) → None

Writes recurrence information from a Budget object to the SQLite database.

Parameters:

• obj (Budget) – Budget object

• sqlite_cursor (sqlite3.Cursor) – Handle to SQLite database

classmethod write_scheduled_transaction_to_sqlite(scheduled_transaction: ScheduledTransaction, sqlite_cursor: Cursor) → None

Writes a ScheduledTransaction object to the SQLite database.

Parameters:

• scheduled_transaction (ScheduledTransaction) – ScheduledTransaction object

• sqlite_cursor (sqlite3.Cursor) – Handle to SQLite file

classmethod write_slot_to_sqlite(slot: Slot, sqlite_cursor: Cursor, object_guid: str) → None

Writes a Slot object to the SQLite database.

Parameters:

• slot (Slot) – Slot object

• sqlite_cursor (sqlite3.Cursor) – Handle to SQLite file

classmethod write_split_to_sqlite(split: Split, sqlite_cursor: Cursor, transaction_guid: str) → None

Writes a Split object to the SQLite database.

Parameters:

• split (Commodity) – Split object

• sqlite_cursor (sqlite3.Cursor) – Handle to SQLite file

classmethod write_transaction_to_sqlite(transaction: Transaction, sqlite_cursor: Cursor) → None

Writes a Transaction object to the SQLite database.

Parameters:

• transaction (Transaction) – Transaction object

• sqlite_cursor (sqlite3.Cursor) – Handle to SQLite file

class file_formats.gnucash_sqlite.DBAction(value)

Enumeration class for record operations in databases.

static get_db_action(sqlite_cursor: Cursor, table_name: str, column_name: str, row_identifier: Any) → DBAction

Helper method for determining the appropriate operation on a SQL table.

Parameters:

• sqlite_cursor (sqlite3.Cursor) – Open cursor to a SQLite database.

• table_name (str) – SQLite table name

• column_name (str) – Column to be used for existence check

• row_identifier (Any) – Unique identifier for the row

Returns:

Appropriate action based on record existence

Return type:

DBAction