python.gnucash_core.Session Class Reference

Inheritance diagram for python.gnucash_core.Session:

Public Member Functions
def	__init__ (self, book_uri=None, mode=None, instance=None, book=None)
	A convenient constructor that allows you to specify a book URI, begin the session, and load the book. More...
def	__enter__ (self)
def	__exit__ (self, exc_type, exc_value, traceback)
def	raise_backend_errors (self, called_function="qof_session function")
def	generate_errors (self)
def	pop_all_errors (self)
Public Member Functions inherited from python.gnucash_core.GnuCashCoreClass
def	do_lookup_create_oo_instance (self, lookup_function, cls, args)

Static Public Member Functions
def	raise_backend_errors_after_call (function, args, kwargs)

Detailed Description

A GnuCash book editing session

To commit changes to the session you may need to call save,
(this is always the case with the file backend).

When you're down with a session you may need to call end()

Every Session has a Book in the book attribute, which you'll definitely
be interested in, as every GnuCash entity (Transaction, Split, Vendor,
Invoice..) is associated with a particular book where it is stored.

Definition at line 149 of file gnucash_core.py.

Constructor & Destructor Documentation

__init__()

def python.gnucash_core.Session.__init__	(		self,
			book_uri = None,
			mode = None,
			instance = None,
			book = None
	)

A convenient constructor that allows you to specify a book URI, begin the session, and load the book.

This can give you the power of calling qof_session_new, qof_session_begin, and qof_session_load all in one!

qof_session_load is only called if url scheme is "xml" and mode is SESSION_NEW_STORE or SESSION_NEW_OVERWRITE

Parameters

book_uri	must be a string in the form of a URI/URL. The access method specified depends on the loaded backends. Paths may be relative or absolute. If the path is relative, that is if the argument is "file://somefile.xml", then the current working directory is assumed. Customized backends can choose to search other application-specific directories or URI schemes as well. It be None to skip the calls to qof_session_begin and qof_session_load.
instance	argument can be passed if new Session is used as a wrapper for an existing session instance
mode	The SessionOpenMode.

Note

SessionOpenMode replaces deprecated ignore_lock, is_new and force_new.

SessionOpenMode

SESSION_NORMAL_OPEN: Find an existing file or database at the provided uri and open it if it is unlocked. If it is locked post a QOF_BACKEND_LOCKED error.

SESSION_NEW_STORE: Check for an existing file or database at the provided uri and if none is found, create it. If the file or database exists post a QOF_BACKED_STORE_EXISTS and return.

SESSION_NEW_OVERWRITE: Create a new file or database at the provided uri, deleting any existing file or database.

SESSION_READ_ONLY: Find an existing file or database and open it without disturbing the lock if it exists or setting one if not. This will also set a flag on the book that will prevent many elements from being edited and will prevent the backend from saving any edits.

SESSION_BREAK_LOCK: Find an existing file or database, lock it, and open it. If there is already a lock replace it with a new one for this session.

Errors

qof_session_begin() signals failure by queuing errors. After it completes use qof_session_get_error() and test that the value is ERROR_BACKEND_NONE to determine that the session began successfully.

Exceptions

as	begin() and load() are wrapped with raise_backend_errors_after_call() this function can raise a GnuCashBackendException. If it does, you don't need to cleanup and call end() and destroy(), that is handled for you, and the exception is raised.

Definition at line 163 of file gnucash_core.py.

    def __init__(self, book_uri=None, mode=None, instance=None, book=None):
        """!
        A convenient constructor that allows you to specify a book URI,
        begin the session, and load the book.

        This can give you the power of calling
        qof_session_new, qof_session_begin, and qof_session_load all in one!

        qof_session_load is only called if url scheme is "xml" and
        mode is SESSION_NEW_STORE or SESSION_NEW_OVERWRITE

        @param book_uri must be a string in the form of a URI/URL. The access
        method specified depends on the loaded backends. Paths may be relative
        or absolute.  If the path is relative, that is if the argument is
        "file://somefile.xml", then the current working directory is
        assumed. Customized backends can choose to search other
        application-specific directories or URI schemes as well.
        It be None to skip the calls to qof_session_begin and
        qof_session_load.

        @param instance argument can be passed if new Session is used as a
        wrapper for an existing session instance

        @param mode The SessionOpenMode.
        @note SessionOpenMode replaces deprecated ignore_lock, is_new and force_new.

        @par SessionOpenMode
        `SESSION_NORMAL_OPEN`: Find an existing file or database at the provided uri and
        open it if it is unlocked. If it is locked post a QOF_BACKEND_LOCKED error.
        @par
        `SESSION_NEW_STORE`: Check for an existing file or database at the provided
        uri and if none is found, create it. If the file or database exists post a
        QOF_BACKED_STORE_EXISTS and return.
        @par
        `SESSION_NEW_OVERWRITE`: Create a new file or database at the provided uri,
        deleting any existing file or database.
        @par
        `SESSION_READ_ONLY`: Find an existing file or database and open it without
        disturbing the lock if it exists or setting one if not. This will also set a
        flag on the book that will prevent many elements from being edited and will
        prevent the backend from saving any edits.
        @par
        `SESSION_BREAK_LOCK`: Find an existing file or database, lock it, and open
        it. If there is already a lock replace it with a new one for this session.

        @par Errors
        qof_session_begin() signals failure by queuing errors. After it completes use
        qof_session_get_error() and test that the value is `ERROR_BACKEND_NONE` to
        determine that the session began successfully.

        @exception as begin() and load() are wrapped with raise_backend_errors_after_call()
        this function can raise a GnuCashBackendException. If it does,
        you don't need to cleanup and call end() and destroy(), that is handled
        for you, and the exception is raised.
        """
        if instance is not None:
            GnuCashCoreClass.__init__(self, instance=instance)
        else:
            if book is None:
                book = Book()
            GnuCashCoreClass.__init__(self, book)

        if book_uri is not None:
            try:
                if mode is None:
                    mode = SessionOpenMode.SESSION_NORMAL_OPEN
                self.begin(book_uri, mode)
                # Take care of backend inconsistency
                # New xml file can't be loaded, new sql store
                # has to be loaded before it can be altered
                # Any existing store obviously has to be loaded
                # More background: https://bugs.gnucash.org/show_bug.cgi?id=726891
                is_new = mode in (SessionOpenMode.SESSION_NEW_STORE, SessionOpenMode.SESSION_NEW_OVERWRITE)
                scheme = urlparse(book_uri).scheme
                if not (is_new and scheme == 'xml'):
                    self.load()
            except GnuCashBackendException as backend_exception:
                self.end()
                self.destroy()
                raise

Member Function Documentation

generate_errors()

def python.gnucash_core.Session.generate_errors

(

self

)

A generator that yields any outstanding QofBackend errors

Definition at line 266 of file gnucash_core.py.

    def generate_errors(self):
        """A generator that yields any outstanding QofBackend errors
        """
        while self.get_error() is not ERR_BACKEND_NO_ERR:
            error = self.pop_error()
            yield error

pop_all_errors()

def python.gnucash_core.Session.pop_all_errors

(

self

)

Returns any accumulated qof backend errors as a tuple

Definition at line 273 of file gnucash_core.py.

    def pop_all_errors(self):
        """Returns any accumulated qof backend errors as a tuple
        """
        return tuple( self.generate_errors() )

raise_backend_errors()

def python.gnucash_core.Session.raise_backend_errors	(		self,
			called_function = "qof_session function"
	)

Raises a GnuCashBackendException if there are outstanding
QOF_BACKEND errors.

set called_function to name the function that was last called

Definition at line 253 of file gnucash_core.py.

    def raise_backend_errors(self, called_function="qof_session function"):
        """Raises a GnuCashBackendException if there are outstanding
        QOF_BACKEND errors.

        set called_function to name the function that was last called
        """
        errors = self.pop_all_errors()
        if errors != ():
            raise GnuCashBackendException(
                "call to %s resulted in the "
                "following errors, %s" % (called_function, backend_error_dict[errors[0]]),
                errors )

raise_backend_errors_after_call()

def python.gnucash_core.Session.raise_backend_errors_after_call (   function,   args,   kwargs  )

static

A function decorator that results in a call to
raise_backend_errors after execution.

Definition at line 280 of file gnucash_core.py.

    def raise_backend_errors_after_call(function, *args, **kwargs):
        """A function decorator that results in a call to
        raise_backend_errors after execution.
        """
        def new_function(self, *args, **kwargs):
            return_value = function(self, *args, **kwargs)
            self.raise_backend_errors(function.__name__)
            return return_value
        return new_function

---

The documentation for this class was generated from the following file:

• gnucash_core.py