piecash.core.book module¶

class piecash.core.book.Book(root_account=None, root_template=None)[source]¶

Bases: piecash._declbase.DeclarativeBaseGuid

A Book represents a GnuCash document. It is created through one of the two factory functions create_book() and open_book().

Canonical use is as a context manager like (the book is automatically closed at the end of the with block):

with create_book() as book:
    ...

Note

If you do not use the context manager, do not forget to close the session explicitly (book.close()) to release any lock on the file/DB.

The book puts at disposal several attributes to access the main objects of the GnuCash document:

# to get the book and the root_account
ra = book.root_account

# to get the list of accounts, commodities or transactions
for acc in book.accounts:  # or book.commodities or book.transactions
    # do something with acc

# to get a specific element of these lists
EUR = book.commodities(namespace="CURRENCY", mnemonic="EUR")

# to get a list of all objects of some class (even non core classes)
budgets = book.get(Budget)
# or a specific object
budget = book.get(Budget, name="my first budget")

You can check a session has changes (new, deleted, changed objects) by getting the book.is_saved property. To save or cancel changes, use book.save() or book.cancel():

# save a session if it is no saved (saving a unchanged session is a no-op)
if not book.is_saved:
    book.save()

root_account¶

the root account of the book

Type: piecash.core.account.Account

root_template¶

the root template of the book (usage not yet clear…)

Type: piecash.core.account.Account

default_currency¶

the currency of the root account (=default currency of the book)

Type: piecash.core.commodity.Commodity

uri¶

connection string of the book (set by the GncSession when accessing the book)

Type: str

session¶

the sqlalchemy session encapsulating the book

Type: sqlalchemy.orm.session.Session

use_trading_accounts¶

true if option “Use trading accounts” is enabled

Type: bool

use_split_action_field¶

true if option “Use Split Action Field for Number” is enabled

Type: bool

RO_threshold_day¶

value of Day Threshold for Read-Only Transactions (red line)

Type: int

control_mode¶

list of allowed non-standard operations like : “allow-root-subaccounts”

Type: list(str)

counter_customer¶

counter for piecash.business.person.Customer id (link to slot “counters/gncCustomer”)

Type: int

counter_vendor¶

counter for piecash.business.person.Vendor id (link to slot “counters/gncVendor”)

Type: int

counter_employee¶

counter for piecash.business.person.Employee id (link to slot “counters/gncEmployee”)

Type: int

counter_invoice¶

counter for piecash.business.invoice.Invoice id (link to slot “counters/gncInvoice”)

Type: int

counter_job¶

counter for piecash.business.invoice.Job id (link to slot “counters/gncJob”)

Type: int

counter_bill¶

counter for piecash.business.invoice.Bill id (link to slot “counters/gncBill”)

Type: int

counter_exp_voucher¶

counter for piecash.business.invoice.Invoice id (link to slot “counters/gncExpVoucher”)

Type: int

counter_order¶

counter for piecash.business.invoice.Order id (link to slot “counters/gncOrder”)

Type: int

business_company_phone¶

phone number of book company (link to slit “options/Business/Company Phone Number”)

Type: str

business_company_email¶

email of book company (link to slit “options/Business/Company Email Address”)

Type: str

business_company_contact¶

contact person of book company (link to slit “options/Business/Company Contact Person”)

Type: str

business_company_ID¶

ID of book company (link to slit “options/Business/Company ID”)

Type: str

business_company_name¶

name of book company (link to slit “options/Business/Company Name”)

Type: str

business_company_address¶

address of book company (link to slit “options/Business/Company Address”)

Type: str

business_company_website¶

website URL of book company (link to slit “options/Business/Company Website URL”)

Type: str

validate()[source]¶: This must be reimplemented for object requiring validation

static track_dirty(session, flush_context, instances)[source]¶: Record in session._all_changes the objects that have been modified before each flush

trading_account(cdty)[source]¶: Return the trading account related to the commodity. If it does not exist and the option “Use Trading Accounts” is enabled, create it on the fly

add(obj)[source]¶: Add an object to the book (to be used if object not linked in any way to the book)

delete(obj)[source]¶: Delete an object from the book (to remove permanently an object)

save()[source]¶: Save the changes to the file/DB (=commit transaction)

flush()[source]¶: Flush the book

cancel()[source]¶: Cancel all the changes that have not been saved (=rollback transaction)

property is_saved¶

Are all the changes saved to the file/DB?

You can check a session has changes (new, deleted, changed objects) by getting the book.is_saved property.

close()[source]¶: Close a session. Any changes not yet saved are rolled back. Any lock on the file/DB is released.

get(cls, **kwargs)[source]¶

Generic getter for a GnuCash object in the GncSession. If no kwargs is given, it returns the list of all objects of type cls (uses the sqlalchemy session.query(cls).all()). Otherwise, it gets the unique object which attributes match the kwargs (uses the sqlalchemy session.query(cls).filter_by(**kwargs).one() underneath):

# to get the first account with name="Income"
inc_account = session.get(Account, name="Income")

# to get all accounts
accs = session.get(Account)

Parameters

cls (class) – the class of the object to retrieve (Account, Price, Budget,…)
kwargs (dict) – the attributes to filter on

Returns

the unique object if it exists, raises exceptions otherwise

Return type

object

property transactions¶: gives easy access to all transactions in the book through a piecash.model_common.CallableList of piecash.core.transaction.Transaction

property splits¶: gives easy access to all splits in the book through a piecash.model_common.CallableList of piecash.core.transaction.Split

property accounts¶: gives easy access to all accounts in the book through a piecash.model_common.CallableList of piecash.core.account.Account

property commodities¶: gives easy access to all commodities in the book through a piecash.model_common.CallableList of piecash.core.commodity.Commodity

property invoices¶: gives easy access to all commodities in the book through a piecash.model_common.CallableList of piecash.core.commodity.Commodity

property currencies¶: gives easy access to all currencies in the book through a piecash.model_common.CallableList of piecash.core.commodity.Commodity

property prices¶: gives easy access to all prices in the book through a piecash.model_common.CallableList of piecash.core.commodity.Price

property customers¶: gives easy access to all commodities in the book through a piecash.model_common.CallableList of piecash.business.people.Customer

property vendors¶: gives easy access to all commodities in the book through a piecash.model_common.CallableList of piecash.business.people.Vendor

property employees¶: gives easy access to all commodities in the book through a piecash.model_common.CallableList of piecash.business.people.Employee

property taxtables¶: gives easy access to all commodities in the book through a piecash.model_common.CallableList of piecash.business.tax.Taxtable

property query¶: proxy for the query function of the underlying sqlalchemy session

splits_df(additional_fields=None)[source]¶

Return a pandas DataFrame with all splits (piecash.core.commodity.Split) from the book

Parameters: list
Returns: pandas.DataFrame

prices_df()[source]¶

Return a pandas DataFrame with all prices (piecash.core.commodity.Price) from the book

Returns: pandas.DataFrame