Inheritance diagram for python.gnucash_core.Session:

Public Member Functions
	__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.

	__enter__ (self)

	__exit__ (self, exc_type, exc_value, traceback)

	raise_backend_errors (self, called_function="qof_session function")

	generate_errors (self)

	pop_all_errors (self)

Public Member Functions inherited from python.gnucash_core.GnuCashCoreClass
	do_lookup_create_oo_instance (self, lookup_function, cls, *args)

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

Additional Inherited Members
Static Protected Attributes inherited from python.gnucash_core.GnuCashCoreClass
	_module = gnucash_core_c

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 297 of file gnucash_core.py.

Constructor & Destructor Documentation

◆ init()

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 311 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)
                is_new = mode in (SessionOpenMode.SESSION_NEW_STORE, SessionOpenMode.SESSION_NEW_OVERWRITE)
                if not is_new:
                    self.load()
            except GnuCashBackendException as backend_exception:
                self.end()
                self.destroy()
                raise
 

Member Function Documentation

◆ enter()

python.gnucash_core.Session.__enter__ ( self )

Definition at line 386 of file gnucash_core.py.

    def __enter__(self):
        return self
 

◆ exit()

python.gnucash_core.Session.__exit__	(	self,
		exc_type,
		exc_value,
		traceback
	)

Definition at line 389 of file gnucash_core.py.

    def __exit__(self, exc_type, exc_value, traceback):
        # Roll back changes on exception by not calling save. Only works for XMl backend.
        if not exc_type:
            self.save()
        self.end()
        self.destroy()
 

◆ generate_errors()

python.gnucash_core.Session.generate_errors ( self )

A generator that yields any outstanding QofBackend errors

Definition at line 409 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()

python.gnucash_core.Session.pop_all_errors ( self )

Returns any accumulated qof backend errors as a tuple

Definition at line 416 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()

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 396 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()

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 423 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

Public Member Functions

Static Public Member Functions

Additional Inherited Members