Status and Errors

Some methods return a status, indicating if an operation was successful and what the error was. Most of these status codes are expressed as a specific value, the notmuch.STATUS.

Note

Prior to version 0.12 the exception classes and the enumeration notmuch.STATUS were defined in notmuch.globals. They have since then been moved into notmuch.errors.

STATUS – Notmuch operation return value

class STATUS

STATUS is a class, whose attributes provide constants that serve as return indicators for notmuch functions. Currently the following ones are defined. For possible return values and specific meaning for each method, see the method description.

  • SUCCESS
  • OUT_OF_MEMORY
  • READ_ONLY_DATABASE
  • XAPIAN_EXCEPTION
  • FILE_ERROR
  • FILE_NOT_EMAIL
  • DUPLICATE_MESSAGE_ID
  • NULL_POINTER
  • TAG_TOO_LONG
  • UNBALANCED_FREEZE_THAW
  • UNBALANCED_ATOMIC
  • NOT_INITIALIZED

Invoke the class method notmuch.STATUS.status2str with a status value as argument to receive a human readable string

classmethod status2str(status)

Get a (unicode) string representation of a notmuch_status_t value.

classmethod STATUS.status2str(status)

Get a (unicode) string representation of a notmuch_status_t value.

NotmuchError – A Notmuch execution error

Whenever an error occurs, we throw a special Exception NotmuchError, or a more fine grained Exception which is derived from it. This means it is always safe to check for NotmuchErrors if you want to catch all errors. If you are interested in more fine grained exceptions, you can use those below.

exception NotmuchError(status=None, message=None)

Is initiated with a (notmuch.STATUS[, message=None]). It will not return an instance of the class NotmuchError, but a derived instance of a more specific Error Message, e.g. OutOfMemoryError. Each status but SUCCESS has a corresponding subclassed Exception.

The following exceptions are all directly derived from NotmuchError. Each of them corresponds to a specific notmuch.STATUS value. You can either check the status attribute of a NotmuchError to see if a specific error has occurred, or you can directly check for the following Exception types:

exception OutOfMemoryError(message=None)
exception ReadOnlyDatabaseError(message=None)
exception XapianError(message=None)
exception FileError(message=None)
exception FileNotEmailError(message=None)
exception DuplicateMessageIdError(message=None)
exception NullPointerError(message=None)
exception TagTooLongError(message=None)
exception UnbalancedFreezeThawError(message=None)
exception UnbalancedAtomicError(message=None)
exception NotInitializedError(message=None)

Derived from NotmuchError, this occurs if the underlying data structure (e.g. database is not initialized (yet) or an iterator has been exhausted. You can test for NotmuchError with .status = STATUS.NOT_INITIALIZED

Table Of Contents

Previous topic

Interfacing with notmuch

Next topic

Database – The underlying notmuch database

This Page