piecash.core.book module — Python interface to GnuCash documents 0.15.0 documentation

# piecash.core.book module

class `piecash.core.book.` `Book`(root_account=None, root_template=None)

  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`

    `piecash.core.account.Account` – the root account of the book

  `root_template`

    `piecash.core.account.Account` – the root template of the book (usage not yet clear…)

  `uri`

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

  `session`

    `sqlalchemy.orm.session.Session` – the sqlalchemy session encapsulating the book

  `use_trading_accounts`

    bool – true if option “Use trading accounts” is enabled

  `use_split_action_field`

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

  `RO_threshold_day`

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

  `control_mode`

    list(str) – list of allowed non-standard operations like : “allow-root-subaccounts”

  `counter_customer`

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

  `counter_vendor`

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

  `counter_employee`

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

  `counter_invoice`

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

  `counter_job`

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

  `counter_bill`

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

  `counter_exp_voucher`

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

  `counter_order`

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

  `book`

    Return the gnc book holding the object

  `validate`()

    This must be reimplemented for object requiring validation

  static `track_dirty`(flush_context, instances)

    Record in session._all_changes the objects that have been modified before each flush

  `trading_account`(cdty)

    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)

    Add an object to the book (to be used if object not linked in any way to the book)

  `delete`(obj)

    Delete an object from the book (to remove permanently an object)

  `save`()

    Save the changes to the file/DB (=commit transaction)

  `flush`()

    Flush the book

  `cancel`()

    Cancel all the changes that have not been saved (=rollback transaction)

  `is_saved`

    Save the changes to the file/DB (=commit transaction)

  `close`()

    Close a session. Any changes not yet saved are rolled back. Any lock on the file/DB is released.

  `get`(cls, **kwargs)

    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

  `transactions`

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

  `splits`

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

  `accounts`

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

  `commodities`

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

  `invoices`

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

  `currencies`

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

  `prices`

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

  `customers`

    gives easy access to all commodities in the book through a `piecash.model_common.CallableList` of `piecash.business.people.Customer`

  `vendors`

    gives easy access to all commodities in the book through a `piecash.model_common.CallableList` of `piecash.business.people.Vendor`

  `employees`

    gives easy access to all commodities in the book through a `piecash.model_common.CallableList` of `piecash.business.people.Employee`

  `taxtables`

    gives easy access to all commodities in the book through a `piecash.model_common.CallableList` of `piecash.business.tax.Taxtable`

  `query`

    proxy for the query function of the underlying sqlalchemy session

  `splits_df`(additional_fields=None)

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

    Parameters: | `list`
    Returns: | `pandas.DataFrame`

  `prices_df`()

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

    Returns: | `pandas.DataFrame`