import ctypes
-from ctypes import c_int, c_char_p, c_void_p, c_uint64
+from ctypes import c_int, c_char_p, c_void_p, c_uint, c_uint64, c_bool
from cnotmuch.globals import nmlib, STATUS, NotmuchError, Enum
import logging
from datetime import date
_get_path = nmlib.notmuch_database_get_path
_get_path.restype = c_char_p
+ """notmuch_database_get_version"""
+ _get_version = nmlib.notmuch_database_get_version
+ _get_version.restype = c_uint
+
"""notmuch_database_open (const char *path, notmuch_database_mode_t mode)"""
_open = nmlib.notmuch_database_open
_open.restype = c_void_p
Wraps notmuch_database_get_path"""
return Database._get_path(self._db)
+ def get_version(self):
+ """Returns the database format version
+
+ :returns: The database version as positive integer
+ :exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if
+ the database was not intitialized.
+ """
+ if self._db is None:
+ raise NotmuchError(STATUS.NOT_INITIALIZED)
+
+ return Database._get_version (self._db)
+
+ def needs_upgrade(self):
+ """Does this database need to be upgraded before writing to it?
+
+ If this function returns True then no functions that modify the
+ database (:meth:`add_message`, :meth:`add_tag`,
+ :meth:`Directory.set_mtime`, etc.) will work unless :meth:`upgrade`
+ is called successfully first.
+
+ :returns: `True` or `False`
+ :exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if
+ the database was not intitialized.
+ """
+ if self._db is None:
+ raise NotmuchError(STATUS.NOT_INITIALIZED)
+
+ return notmuch_database_needs_upgrade(self.db)
+
def find_message(self, msgid):
"""Returns a :class:`Message` as identified by its message ID
@property
def db_p(self):
- """Property returning a pointer to the notmuch_database_t or `None`.
+ """Property returning a pointer to the notmuch_database_t or `None`
This should normally not be needed by a user."""
return self._db
Technically, it wraps the underlying *notmuch_query_t* struct.
.. note:: Do remember that as soon as we tear down this object,
- all underlying derived objects such as queries, threads,
+ all underlying derived objects such as threads,
messages, tags etc will be freed by the underlying library
as well. Accessing these objects will lead to segfaults and
other unexpected behavior. See above for more details.
nmlib.notmuch_query_set_sort(self._query, sort)
def search_messages(self):
- """Filter messages according to query and return
- :class:`Messages` in the defined sort order.
+ """Filter messages according to the query and return
+ :class:`Messages` in the defined sort order
Technically, it wraps the underlying
*notmuch_query_search_messages* function.
#------------------------------------------------------------------------------
class Message(object):
- """Wrapper around notmuch_message_t"""
+ """Represents a single Email message
+
+ Technically, this wraps the underlying *notmuch_message_t* structure.
+ """
"""notmuch_message_get_filename (notmuch_message_t *message)"""
_get_filename = nmlib.notmuch_message_get_filename
def __init__(self, msg_p, parent=None):
"""
- msg_p is a pointer to an notmuch_message_t Structure. If it is None,
- we will raise an NotmuchError(STATUS.NULL_POINTER).
-
- Is a 'parent' object is passed which this message is derived from,
- we save a reference to it, so we can automatically delete the parent
- object once all derived objects are dead.
+ :param msg_p: A pointer to an internal notmuch_message_t
+ Structure. If it is `None`, we will raise an :exc:`NotmuchError`
+ STATUS.NULL_POINTER.
+ :param parent: A 'parent' object is passed which this message is
+ derived from. We save a reference to it, so we can
+ automatically delete the parent object once all derived
+ objects are dead.
"""
if msg_p is None:
NotmuchError(STATUS.NULL_POINTER)
def get_message_id(self):
- """ return the msg id
+ """Return the message ID
- Raises NotmuchError(STATUS.NOT_INITIALIZED) if not inited
+ :returns: String with a message ID
+ :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
+ is not initialized.
"""
if self._msg is None:
raise NotmuchError(STATUS.NOT_INITIALIZED)
return Message._get_message_id(self._msg)
def get_date(self):
- """returns time_t of the message date
+ """Returns time_t of the message date
For the original textual representation of the Date header from the
message call notmuch_message_get_header() with a header value of
"date".
- Raises NotmuchError(STATUS.NOT_INITIALIZED) if not inited
+
+ :returns: a time_t timestamp
+ :rtype: c_unit64
+ :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
+ is not initialized.
"""
if self._msg is None:
raise NotmuchError(STATUS.NOT_INITIALIZED)
return Message._get_date(self._msg)
def get_header(self, header):
- """ TODO document me"""
+ """Returns a message header
+
+ This returns any message header that is stored in the notmuch database.
+ This is only a selected subset of headers, which is currently:
+
+ TODO: add stored headers
+
+ :param header: The name of the header to be retrieved.
+ It is not case-sensitive (TODO: confirm).
+ :type header: str
+ :returns: The header value as string
+ :exception: :exc:`NotmuchError`
+
+ * STATUS.NOT_INITIALIZED if the message
+ is not initialized.
+ * STATUS.NULL_POINTER, if no header was found
+ """
if self._msg is None:
raise NotmuchError(STATUS.NOT_INITIALIZED)
return header
def get_filename(self):
- """ return the msg filename
-
- Raises NotmuchError(STATUS.NOT_INITIALIZED) if not inited
+ """Return the file path of the message file
+
+ :returns: Absolute file path & name of the message file
+ :exception: :exc:`NotmuchError` STATUS.NOT_INITIALIZED if the message
+ is not initialized.
"""
if self._msg is None:
raise NotmuchError(STATUS.NOT_INITIALIZED)
return Message._get_filename(self._msg)
def get_tags(self):
- """ return the msg tags
-
- Raises NotmuchError(STATUS.NOT_INITIALIZED) if not inited
- Raises NotmuchError(STATUS.NULL_POINTER) on error.
+ """ Return the message tags
+
+ :returns: Message tags
+ :rtype: :class:`Tags`
+ :exception: :exc:`NotmuchError`
+
+ * STATUS.NOT_INITIALIZED if the message
+ is not initialized.
+ * STATUS.NULL_POINTER, on error
"""
if self._msg is None:
raise NotmuchError(STATUS.NOT_INITIALIZED)
raise NotmuchError(STATUS.NULL_POINTER)
return Tags(tags_p, self)
+ def add_tag(self, tag):
+ """Add a tag to the given message
+
+ Adds a tag to the current message. The maximal tag length is defined in
+ the notmuch library and is currently 200 bytes.
+
+ :param tag: String with a 'tag' to be added.
+ :returns: STATUS.SUCCESS if the tag was successfully added.
+ Raises an exception otherwise.
+ :exception: :exc:`NotmuchError`. They have the following meaning:
+
+ STATUS.NULL_POINTER
+ The 'tag' argument is NULL
+ STATUS.TAG_TOO_LONG
+ The length of 'tag' is too long
+ (exceeds Message.NOTMUCH_TAG_MAX)
+ STATUS.READ_ONLY_DATABASE
+ Database was opened in read-only mode so message cannot be
+ modified.
+ STATUS.NOT_INITIALIZED
+ The message has not been initialized.
+ """
+ if self._msg is None:
+ raise NotmuchError(STATUS.NOT_INITIALIZED)
+
+ status = nmlib.notmuch_message_add_tag (self._msg, tag)
+
+ if STATUS.SUCCESS == status:
+ # return on success
+ return status
+
+ raise NotmuchError(status)
+
+ def remove_tag(self, tag):
+ """Removes a tag from the given message
+
+ If the message has no such tag, this is a non-operation and
+ will report success anyway.
+
+ :param tag: String with a 'tag' to be removed.
+ :returns: STATUS.SUCCESS if the tag was successfully removed or if
+ the message had no such tag.
+ Raises an exception otherwise.
+ :exception: :exc:`NotmuchError`. They have the following meaning:
+
+ STATUS.NULL_POINTER
+ The 'tag' argument is NULL
+ STATUS.TAG_TOO_LONG
+ The length of 'tag' is too long
+ (exceeds NOTMUCH_TAG_MAX)
+ STATUS.READ_ONLY_DATABASE
+ Database was opened in read-only mode so message cannot
+ be modified.
+ STATUS.NOT_INITIALIZED
+ The message has not been initialized.
+ """
+ if self._msg is None:
+ raise NotmuchError(STATUS.NOT_INITIALIZED)
+
+ status = nmlib.notmuch_message_remove_tag(self._msg, tag)
+
+ if STATUS.SUCCESS == status:
+ # return on success
+ return status
+
+ raise NotmuchError(status)
+
+ def remove_all_tags(self):
+ """Removes all tags from the given message.
+
+ See :meth:`freeze` for an example showing how to safely
+ replace tag values.
+
+ :returns: STATUS.SUCCESS if the tags were successfully removed.
+ Raises an exception otherwise.
+ :exception: :exc:`NotmuchError`. They have the following meaning:
+
+ STATUS.READ_ONLY_DATABASE
+ Database was opened in read-only mode so message cannot
+ be modified.
+ STATUS.NOT_INITIALIZED
+ The message has not been initialized.
+ """
+ if self._msg is None:
+ raise NotmuchError(STATUS.NOT_INITIALIZED)
+
+ status = nmlib.notmuch_message_remove_all_tags(self._msg)
+
+ if STATUS.SUCCESS == status:
+ # return on success
+ return status
+
+ raise NotmuchError(status)
+
+ def freeze(self):
+ """Freezes the current state of 'message' within the database
+
+ This means that changes to the message state, (via :meth:`add_tag`,
+ :meth:`remove_tag`, and :meth:`remove_all_tags`), will not be
+ committed to the database until the message is :meth:`thaw`ed.
+
+ Multiple calls to freeze/thaw are valid and these calls will
+ "stack". That is there must be as many calls to thaw as to freeze
+ before a message is actually thawed.
+
+ The ability to do freeze/thaw allows for safe transactions to
+ change tag values. For example, explicitly setting a message to
+ have a given set of tags might look like this::
+
+ msg.freeze()
+ msg.remove_all_tags()
+ for tag in new_tags:
+ msg.add_tag(tag)
+ msg.thaw()
+
+ With freeze/thaw used like this, the message in the database is
+ guaranteed to have either the full set of original tag values, or
+ the full set of new tag values, but nothing in between.
+
+ Imagine the example above without freeze/thaw and the operation
+ somehow getting interrupted. This could result in the message being
+ left with no tags if the interruption happened after
+ :meth:`remove_all_tags` but before :meth:`add_tag`.
+
+ :returns: STATUS.SUCCESS if the message was successfully frozen.
+ Raises an exception otherwise.
+ :exception: :exc:`NotmuchError`. They have the following meaning:
+
+ STATUS.READ_ONLY_DATABASE
+ Database was opened in read-only mode so message cannot
+ be modified.
+ STATUS.NOT_INITIALIZED
+ The message has not been initialized.
+ """
+ if self._msg is None:
+ raise NotmuchError(STATUS.NOT_INITIALIZED)
+
+ status = nmlib.notmuch_message_freeze(self._msg)
+
+ if STATUS.SUCCESS == status:
+ # return on success
+ return status
+
+ raise NotmuchError(status)
+
+ def thaw(self):
+ """Thaws the current 'message'
+
+ Thaw the current 'message', synchronizing any changes that may have
+ occurred while 'message' was frozen into the notmuch database.
+
+ See :meth:`freeze` for an example of how to use this
+ function to safely provide tag changes.
+
+ Multiple calls to freeze/thaw are valid and these calls with
+ "stack". That is there must be as many calls to thaw as to freeze
+ before a message is actually thawed.
+
+ :returns: STATUS.SUCCESS if the message was successfully frozen.
+ Raises an exception otherwise.
+ :exception: :exc:`NotmuchError`. They have the following meaning:
+
+ STATUS.UNBALANCED_FREEZE_THAW
+ An attempt was made to thaw an unfrozen message.
+ That is, there have been an unbalanced number of calls
+ to :meth:`freeze` and :meth:`thaw`.
+ STATUS.NOT_INITIALIZED
+ The message has not been initialized.
+ """
+ if self._msg is None:
+ raise NotmuchError(STATUS.NOT_INITIALIZED)
+
+ status = nmlib.notmuch_message_thaw(self._msg)
+
+ if STATUS.SUCCESS == status:
+ # return on success
+ return status
+
+ raise NotmuchError(status)
+
+
def __str__(self):
"""A message() is represented by a 1-line summary"""
msg = {}
return "%(from)s (%(date)s) (%(tags)s)" % (msg)
def format_as_text(self):
- """ Output like notmuch show """
+ """Output like notmuch show (Not implemented)"""
return str(self)
def __del__(self):
projects / notmuch / blobdiff