File Formats¶

XML¶

class file_formats.xml.XMLFileFormat[source]¶: Class containing the logic for loading and saving XML files.

class file_formats.xml.GZipXMLFileFormat[source]¶

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

classmethod get_xml_root(source_path: pathlib.Path) → xml.etree.ElementTree.Element[source]¶

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[source]¶

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.xml.GnuCashXMLReader[source]¶

Class containing the logic for loading XML files.

LOGGER = <RootLogger root (WARNING)>¶

classmethod create_account_from_xml(account_node: xml.etree.ElementTree.Element, account_objects: List[gnewcash.account.Account]) → gnewcash.account.Account[source]¶

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: xml.etree.ElementTree.Element, sort_transactions: bool = True) → gnewcash.gnucash_file.Book[source]¶

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
Returns:	Book object from XML
Return type:	Book

classmethod create_budget_from_xml(budget_node: xml.etree.ElementTree.Element) → gnewcash.gnucash_file.Budget[source]¶

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: xml.etree.ElementTree.Element) → gnewcash.commodity.Commodity[source]¶

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: xml.etree.ElementTree.Element, template_account_root: Optional[gnewcash.account.Account]) → gnewcash.transaction.ScheduledTransaction[source]¶

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: xml.etree.ElementTree.Element) → gnewcash.slot.Slot[source]¶

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: xml.etree.ElementTree.Element, account_objects: List[gnewcash.account.Account]) → gnewcash.transaction.Split[source]¶

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: xml.etree.ElementTree.Element, account_objects: List[gnewcash.account.Account]) → gnewcash.transaction.Transaction[source]¶

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: pathlib.Path) → xml.etree.ElementTree.Element[source]¶

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, source_file: str = '', sort_transactions: bool = True, **kwargs) → gnewcash.gnucash_file.GnuCashFile[source]¶

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
Returns:	GnuCashFile object
Return type:	GnuCashFile

classmethod read_xml_child_boolean(xml_object: xml.etree.ElementTree.Element, tag_name: str, namespaces: Dict[str, str]) → Optional[bool][source]¶

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: xml.etree.ElementTree.Element, tag_name: str, namespaces: Dict[str, str]) → Optional[datetime.datetime][source]¶

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: xml.etree.ElementTree.Element, tag_name: str, namespaces: Dict[str, str]) → Optional[int][source]¶

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: xml.etree.ElementTree.Element, tag_name: str, namespaces: Dict[str, str]) → Optional[str][source]¶

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.xml.GnuCashXMLWriter[source]¶

Class containing the logic for saving XML files.

LOGGER = <RootLogger root (WARNING)>¶

classmethod cast_account_as_xml(account: gnewcash.account.Account) → List[xml.etree.ElementTree.Element][source]¶

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: gnewcash.gnucash_file.Book) → xml.etree.ElementTree.Element[source]¶

Returns the current book as GnuCash-compatible XML.

Returns:	ElementTree.Element object
Return type:	xml.etree.ElementTree.Element

classmethod cast_budget_as_xml(budget: gnewcash.gnucash_file.Budget) → xml.etree.ElementTree.Element[source]¶

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: gnewcash.commodity.Commodity, node_tag: str) → xml.etree.ElementTree.Element[source]¶

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: gnewcash.commodity.Commodity) → xml.etree.ElementTree.Element[source]¶

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: gnewcash.transaction.ScheduledTransaction) → xml.etree.ElementTree.Element[source]¶

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: gnewcash.slot.Slot) → xml.etree.ElementTree.Element[source]¶

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: gnewcash.transaction.Split) → xml.etree.ElementTree.Element[source]¶

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: gnewcash.transaction.Transaction) → xml.etree.ElementTree.Element[source]¶

Returns the current transaction as GnuCash-compatible XML.

Returns:	Current transaction as XML
Return type:	xml.etree.ElementTree.Element

classmethod dump(gnucash_file: gnewcash.gnucash_file.GnuCashFile, *args, target_file: str = '', prettify_xml: bool = False, **kwargs) → None[source]¶

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[source]¶

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.sqlite.SqliteFileFormat[source]¶: Class containing the logic for loading and saving SQlite files.

class file_formats.sqlite.GnuCashSQLiteReader[source]¶

Class containing the logic for loading SQlite files.

classmethod create_account_from_sqlite(sqlite_cursor: sqlite3.Cursor, account_id: str) → gnewcash.account.Account[source]¶

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: sqlite3.Cursor, sort_transactions: bool) → List[gnewcash.gnucash_file.Book][source]¶

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
Returns:	Book objects from SQLite
Return type:	list[Book]

classmethod create_budget_from_sqlite(sqlite_cursor: sqlite3.Cursor) → List[gnewcash.gnucash_file.Budget][source]¶

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: sqlite3.Cursor) → List[gnewcash.commodity.Commodity][source]¶

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: sqlite3.Cursor, commodity_guid: str) → gnewcash.commodity.Commodity[source]¶

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: sqlite3.Cursor, template_root_account: gnewcash.account.Account) → List[gnewcash.transaction.ScheduledTransaction][source]¶

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: sqlite3.Cursor, object_id: str) → List[gnewcash.slot.Slot][source]¶

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: sqlite3.Cursor, transaction_guid: str, root_account: gnewcash.account.Account, template_root_account: gnewcash.account.Account) → List[gnewcash.transaction.Split][source]¶

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: sqlite3.Cursor, root_account: gnewcash.account.Account, template_root_account: gnewcash.account.Account) → List[gnewcash.transaction.Transaction][source]¶

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: sqlite3.Cursor, table_name: str, where_condition: Optional[str] = None, where_parameters: Optional[Tuple[Any]] = None) → List[Dict[str, Any]][source]¶

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, source_file: str = '', sort_transactions: bool = True, **kwargs) → gnewcash.gnucash_file.GnuCashFile[source]¶

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 by date posted
Returns:	GnuCashFile object
Return type:	GnuCashFile

class file_formats.sqlite.GnuCashSQLiteWriter[source]¶

Class containing the logic for saving SQlite files.

classmethod create_sqlite_schema(sqlite_cursor: sqlite3.Cursor) → None[source]¶

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: sqlite3.Cursor) → None[source]¶: Removes a transaction from the SQLite database, as well as all dependent objects.

classmethod dump(gnucash_file: gnewcash.gnucash_file.GnuCashFile, *args, target_file: str = '', **kwargs) → None[source]¶

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: gnewcash.account.Account, sqlite_cursor: sqlite3.Cursor) → None[source]¶

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: gnewcash.gnucash_file.Book, sqlite_cursor: sqlite3.Cursor) → None[source]¶

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: gnewcash.gnucash_file.Budget, sqlite_cursor: sqlite3.Cursor) → None[source]¶

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: gnewcash.commodity.Commodity, sqlite_cursor: sqlite3.Cursor) → None[source]¶

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: gnewcash.gnucash_file.Budget, sqlite_cursor: sqlite3.Cursor) → None[source]¶

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: gnewcash.transaction.ScheduledTransaction, sqlite_cursor: sqlite3.Cursor) → None[source]¶

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: gnewcash.slot.Slot, sqlite_cursor: sqlite3.Cursor, object_guid: str) → None[source]¶

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: gnewcash.transaction.Split, sqlite_cursor: sqlite3.Cursor, transaction_guid: str) → None[source]¶

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: gnewcash.transaction.Transaction, sqlite_cursor: sqlite3.Cursor) → None[source]¶

Writes a Transaction object to the SQLite database.

Parameters:	transaction (Transaction) – Transaction object sqlite_cursor (sqlite3.Cursor) – Handle to SQLite file

class file_formats.sqlite.DBAction[source]¶: Enumeration class for record operations in databases.