GnuCash  4.11-11-ge9df8d41d2+
Public Member Functions | Static Public Member Functions
python.gnucash_core.Session Class Reference
Inheritance diagram for python.gnucash_core.Session:
python.gnucash_core.GnuCashCoreClass

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_urimust 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.
instanceargument can be passed if new Session is used as a wrapper for an existing session instance
modeThe 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
asbegin() 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.

163  def __init__(self, book_uri=None, mode=None, instance=None, book=None):
164  """!
165  A convenient constructor that allows you to specify a book URI,
166  begin the session, and load the book.
167 
168  This can give you the power of calling
169  qof_session_new, qof_session_begin, and qof_session_load all in one!
170 
171  qof_session_load is only called if url scheme is "xml" and
172  mode is SESSION_NEW_STORE or SESSION_NEW_OVERWRITE
173 
174  @param book_uri must be a string in the form of a URI/URL. The access
175  method specified depends on the loaded backends. Paths may be relative
176  or absolute. If the path is relative, that is if the argument is
177  "file://somefile.xml", then the current working directory is
178  assumed. Customized backends can choose to search other
179  application-specific directories or URI schemes as well.
180  It be None to skip the calls to qof_session_begin and
181  qof_session_load.
182 
183  @param instance argument can be passed if new Session is used as a
184  wrapper for an existing session instance
185 
186  @param mode The SessionOpenMode.
187  @note SessionOpenMode replaces deprecated ignore_lock, is_new and force_new.
188 
189  @par SessionOpenMode
190  `SESSION_NORMAL_OPEN`: Find an existing file or database at the provided uri and
191  open it if it is unlocked. If it is locked post a QOF_BACKEND_LOCKED error.
192  @par
193  `SESSION_NEW_STORE`: Check for an existing file or database at the provided
194  uri and if none is found, create it. If the file or database exists post a
195  QOF_BACKED_STORE_EXISTS and return.
196  @par
197  `SESSION_NEW_OVERWRITE`: Create a new file or database at the provided uri,
198  deleting any existing file or database.
199  @par
200  `SESSION_READ_ONLY`: Find an existing file or database and open it without
201  disturbing the lock if it exists or setting one if not. This will also set a
202  flag on the book that will prevent many elements from being edited and will
203  prevent the backend from saving any edits.
204  @par
205  `SESSION_BREAK_LOCK`: Find an existing file or database, lock it, and open
206  it. If there is already a lock replace it with a new one for this session.
207 
208  @par Errors
209  qof_session_begin() signals failure by queuing errors. After it completes use
210  qof_session_get_error() and test that the value is `ERROR_BACKEND_NONE` to
211  determine that the session began successfully.
212 
213  @exception as begin() and load() are wrapped with raise_backend_errors_after_call()
214  this function can raise a GnuCashBackendException. If it does,
215  you don't need to cleanup and call end() and destroy(), that is handled
216  for you, and the exception is raised.
217  """
218  if instance is not None:
219  GnuCashCoreClass.__init__(self, instance=instance)
220  else:
221  if book is None:
222  book = Book()
223  GnuCashCoreClass.__init__(self, book)
224 
225  if book_uri is not None:
226  try:
227  if mode is None:
228  mode = SessionOpenMode.SESSION_NORMAL_OPEN
229  self.begin(book_uri, mode)
230  # Take care of backend inconsistency
231  # New xml file can't be loaded, new sql store
232  # has to be loaded before it can be altered
233  # Any existing store obviously has to be loaded
234  # More background: https://bugs.gnucash.org/show_bug.cgi?id=726891
235  is_new = mode in (SessionOpenMode.SESSION_NEW_STORE, SessionOpenMode.SESSION_NEW_OVERWRITE)
236  scheme = urlparse(book_uri).scheme
237  if not (is_new and scheme == 'xml'):
238  self.load()
239  except GnuCashBackendException as backend_exception:
240  self.end()
241  self.destroy()
242  raise
243 

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.

266  def generate_errors(self):
267  """A generator that yields any outstanding QofBackend errors
268  """
269  while self.get_error() is not ERR_BACKEND_NO_ERR:
270  error = self.pop_error()
271  yield error
272 

◆ 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.

273  def pop_all_errors(self):
274  """Returns any accumulated qof backend errors as a tuple
275  """
276  return tuple( self.generate_errors() )
277 

◆ 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.

253  def raise_backend_errors(self, called_function="qof_session function"):
254  """Raises a GnuCashBackendException if there are outstanding
255  QOF_BACKEND errors.
256 
257  set called_function to name the function that was last called
258  """
259  errors = self.pop_all_errors()
260  if errors != ():
261  raise GnuCashBackendException(
262  "call to %s resulted in the "
263  "following errors, %s" % (called_function, backend_error_dict[errors[0]]),
264  errors )
265 

◆ 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.

280  def raise_backend_errors_after_call(function, *args, **kwargs):
281  """A function decorator that results in a call to
282  raise_backend_errors after execution.
283  """
284  def new_function(self, *args, **kwargs):
285  return_value = function(self, *args, **kwargs)
286  self.raise_backend_errors(function.__name__)
287  return return_value
288  return new_function
289 

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