class IndexOptions(base.NotmuchObject): """Indexing options. This represents the indexing options which can be used to index a message. See :meth:`Database.default_indexopts` to create an instance of this. It can be used e.g. when indexing a new message using :meth:`Database.add`. """ _opts_p = base.MemoryPointer() def __init__(self, parent, opts_p): self._parent = parent self._opts_p = opts_p @property def alive(self): if not self._parent.alive: return False try: self._opts_p except errors.ObjectDestroyedError: return False else: return True def _destroy(self): if self.alive: capi.lib.notmuch_indexopts_destroy(self._opts_p) self._opts_p = None @property def decrypt_policy(self): """The decryption policy. This is an enum from the :class:`DecryptionPolicy`. See the `index.decrypt` section in :man:`notmuch-config` for details on the options. **Do not set this to :attr:`DecryptionPolicy.TRUE`** without considering the security of your index. You can change this policy by assigning a new :class:`DecryptionPolicy` to this property. :raises ObjectDestroyedError: if used after destroyed. :returns: A :class:`DecryptionPolicy` enum instance. """ raw = capi.lib.notmuch_indexopts_get_decrypt_policy(self._opts_p) return DecryptionPolicy(raw) @decrypt_policy.setter def decrypt_policy(self, val): ret = capi.lib.notmuch_indexopts_set_decrypt_policy( self._opts_p, val.value) if ret != capi.lib.NOTMUCH_STATUS_SUCCESS: raise errors.NotmuchError(ret, msg)
class Cls: ptr = base.MemoryPointer()
class Database(base.NotmuchObject): """Toplevel access to notmuch. A :class:`Database` can be opened read-only or read-write. Modifications are not atomic by default, use :meth:`begin_atomic` for atomic updates. If the underlying database has been modified outside of this class a :exc:`XapianError` will be raised and the instance must be closed and a new one created. You can use an instance of this class as a context-manager. :cvar MODE: The mode a database can be opened with, an enumeration of ``READ_ONLY`` and ``READ_WRITE`` :cvar SORT: The sort order for search results, ``OLDEST_FIRST``, ``NEWEST_FIRST``, ``MESSAGE_ID`` or ``UNSORTED``. :cvar EXCLUDE: Which messages to exclude from queries, ``TRUE``, ``FLAG``, ``FALSE`` or ``ALL``. See the query documentation for details. :cvar AddedMessage: A namedtuple ``(msg, dup)`` used by :meth:`add` as return value. :cvar STR_MODE_MAP: A map mapping strings to :attr:`MODE` items. This is used to implement the ``ro`` and ``rw`` string variants. :ivar closed: Boolean indicating if the database is closed or still open. :param path: The directory of where the database is stored. If ``None`` the location will be read from the user's configuration file, respecting the ``NOTMUCH_CONFIG`` environment variable if set. :type path: str, bytes, os.PathLike or pathlib.Path :param mode: The mode to open the database in. One of :attr:`MODE.READ_ONLY` OR :attr:`MODE.READ_WRITE`. For convenience you can also use the strings ``ro`` for :attr:`MODE.READ_ONLY` and ``rw`` for :attr:`MODE.READ_WRITE`. :type mode: :attr:`MODE` or str. :raises KeyError: if an unknown mode string is used. :raises OSError: or subclasses if the configuration file can not be opened. :raises configparser.Error: or subclasses if the configuration file can not be parsed. :raises NotmuchError: or subclasses for other failures. """ MODE = Mode SORT = QuerySortOrder EXCLUDE = QueryExclude AddedMessage = collections.namedtuple('AddedMessage', ['msg', 'dup']) _db_p = base.MemoryPointer() STR_MODE_MAP = { 'ro': MODE.READ_ONLY, 'rw': MODE.READ_WRITE, } def __init__(self, path=None, mode=MODE.READ_ONLY): if isinstance(mode, str): mode = self.STR_MODE_MAP[mode] self.mode = mode if path is None: path = self.default_path() if not hasattr(os, 'PathLike') and isinstance(path, pathlib.Path): path = bytes(path) db_pp = capi.ffi.new('notmuch_database_t **') cmsg = capi.ffi.new('char**') ret = capi.lib.notmuch_database_open_verbose(os.fsencode(path), mode.value, db_pp, cmsg) if cmsg[0]: msg = capi.ffi.string(cmsg[0]).decode(errors='replace') capi.lib.free(cmsg[0]) else: msg = None if ret != capi.lib.NOTMUCH_STATUS_SUCCESS: raise errors.NotmuchError(ret, msg) self._db_p = db_pp[0] self.closed = False @classmethod def create(cls, path=None): """Create and open database in READ_WRITE mode. This is creates a new notmuch database and returns an opened instance in :attr:`MODE.READ_WRITE` mode. :param path: The directory of where the database is stored. If ``None`` the location will be read from the user's configuration file, respecting the ``NOTMUCH_CONFIG`` environment variable if set. :type path: str, bytes or os.PathLike :raises OSError: or subclasses if the configuration file can not be opened. :raises configparser.Error: or subclasses if the configuration file can not be parsed. :raises NotmuchError: if the config file does not have the database.path setting. :raises FileError: if the database already exists. :returns: The newly created instance. """ if path is None: path = cls.default_path() if not hasattr(os, 'PathLike') and isinstance(path, pathlib.Path): path = bytes(path) db_pp = capi.ffi.new('notmuch_database_t **') cmsg = capi.ffi.new('char**') ret = capi.lib.notmuch_database_create_verbose(os.fsencode(path), db_pp, cmsg) if cmsg[0]: msg = capi.ffi.string(cmsg[0]).decode(errors='replace') capi.lib.free(cmsg[0]) else: msg = None if ret != capi.lib.NOTMUCH_STATUS_SUCCESS: raise errors.NotmuchError(ret, msg) # Now close the db and let __init__ open it. Inefficient but # creating is not a hot loop while this allows us to have a # clean API. ret = capi.lib.notmuch_database_destroy(db_pp[0]) if ret != capi.lib.NOTMUCH_STATUS_SUCCESS: raise errors.NotmuchError(ret) return cls(path, cls.MODE.READ_WRITE) @staticmethod def default_path(cfg_path=None): """Return the path of the user's default database. This reads the user's configuration file and returns the default path of the database. :param cfg_path: The pathname of the notmuch configuration file. If not specified tries to use the pathname provided in the :env:`NOTMUCH_CONFIG` environment variable and falls back to :file:`~/.notmuch-config. :type cfg_path: str, bytes, os.PathLike or pathlib.Path. :returns: The path of the database, which does not necessarily exists. :rtype: pathlib.Path :raises OSError: or subclasses if the configuration file can not be opened. :raises configparser.Error: or subclasses if the configuration file can not be parsed. :raises NotmuchError if the config file does not have the database.path setting. """ if not cfg_path: cfg_path = _config_pathname() if not hasattr(os, 'PathLike') and isinstance(cfg_path, pathlib.Path): cfg_path = bytes(cfg_path) parser = configparser.ConfigParser() with open(cfg_path) as fp: parser.read_file(fp) try: return pathlib.Path(parser.get('database', 'path')) except configparser.Error: raise errors.NotmuchError( 'No database.path setting in {}'.format(cfg_path)) def __del__(self): self._destroy() @property def alive(self): try: self._db_p except errors.ObjectDestroyedError: return False else: return True def _destroy(self): try: ret = capi.lib.notmuch_database_destroy(self._db_p) except errors.ObjectDestroyedError: ret = capi.lib.NOTMUCH_STATUS_SUCCESS else: self._db_p = None if ret != capi.lib.NOTMUCH_STATUS_SUCCESS: raise errors.NotmuchError(ret) def close(self): """Close the notmuch database. Once closed most operations will fail. This can still be useful however to explicitly close a database which is opened read-write as this would otherwise stop other processes from reading the database while it is open. :raises ObjectDestroyedError: if used after destroyed. """ ret = capi.lib.notmuch_database_close(self._db_p) if ret != capi.lib.NOTMUCH_STATUS_SUCCESS: raise errors.NotmuchError(ret) self.closed = True def __enter__(self): return self def __exit__(self, exc_type, exc_value, traceback): self.close() @property def path(self): """The pathname of the notmuch database. This is returned as a :class:`pathlib.Path` instance. :raises ObjectDestroyedError: if used after destroyed. """ try: return self._cache_path except AttributeError: ret = capi.lib.notmuch_database_get_path(self._db_p) self._cache_path = pathlib.Path(os.fsdecode(capi.ffi.string(ret))) return self._cache_path @property def version(self): """The database format version. This is a positive integer. :raises ObjectDestroyedError: if used after destroyed. """ try: return self._cache_version except AttributeError: ret = capi.lib.notmuch_database_get_version(self._db_p) self._cache_version = ret return ret @property def needs_upgrade(self): """Whether the database should be upgraded. If *True* the database can be upgraded using :meth:`upgrade`. Not doing so may result in some operations raising :exc:`UpgradeRequiredError`. A read-only database will never be upgradable. :raises ObjectDestroyedError: if used after destroyed. """ ret = capi.lib.notmuch_database_needs_upgrade(self._db_p) return bool(ret) def upgrade(self, progress_cb=None): """Upgrade the database to the latest version. Upgrade the database, optionally with a progress callback which should be a callable which will be called with a floating point number in the range of [0.0 .. 1.0]. """ raise NotImplementedError def atomic(self): """Return a context manager to perform atomic operations. The returned context manager can be used to perform atomic operations on the database. .. note:: Unlinke a traditional RDBMS transaction this does not imply durability, it only ensures the changes are performed atomically. :raises ObjectDestroyedError: if used after destroyed. """ ctx = AtomicContext(self, '_db_p') return ctx def revision(self): """The currently committed revision in the database. Returned as a ``(revision, uuid)`` namedtuple. :raises ObjectDestroyedError: if used after destroyed. """ raw_uuid = capi.ffi.new('char**') rev = capi.lib.notmuch_database_get_revision(self._db_p, raw_uuid) return DbRevision(rev, capi.ffi.string(raw_uuid[0])) def get_directory(self, path): raise NotImplementedError def default_indexopts(self): """Returns default index options for the database. :raises ObjectDestroyedError: if used after destroyed. :returns: :class:`IndexOptions`. """ opts = capi.lib.notmuch_database_get_default_indexopts(self._db_p) return IndexOptions(self, opts) def add(self, filename, *, sync_flags=False, indexopts=None): """Add a message to the database. Add a new message to the notmuch database. The message is referred to by the pathname of the maildir file. If the message ID of the new message already exists in the database, this adds ``pathname`` to the list of list of files for the existing message. :param filename: The path of the file containing the message. :type filename: str, bytes, os.PathLike or pathlib.Path. :param sync_flags: Whether to sync the known maildir flags to notmuch tags. See :meth:`Message.flags_to_tags` for details. :type sync_flags: bool :param indexopts: The indexing options, see :meth:`default_indexopts`. Leave as `None` to use the default options configured in the database. :type indexopts: :class:`IndexOptions` or `None` :returns: A tuple where the first item is the newly inserted messages as a :class:`Message` instance, and the second item is a boolean indicating if the message inserted was a duplicate. This is the namedtuple ``AddedMessage(msg, dup)``. :rtype: Database.AddedMessage If an exception is raised, no message was added. :raises XapianError: A Xapian exception occurred. :raises FileError: The file referred to by ``pathname`` could not be opened. :raises FileNotEmailError: The file referreed to by ``pathname`` is not recognised as an email message. :raises ReadOnlyDatabaseError: The database is opened in READ_ONLY mode. :raises UpgradeRequiredError: The database must be upgraded first. :raises ObjectDestroyedError: if used after destroyed. """ if not hasattr(os, 'PathLike') and isinstance(filename, pathlib.Path): filename = bytes(filename) msg_pp = capi.ffi.new('notmuch_message_t **') opts_p = indexopts._opts_p if indexopts else capi.ffi.NULL ret = capi.lib.notmuch_database_index_file(self._db_p, os.fsencode(filename), opts_p, msg_pp) ok = [ capi.lib.NOTMUCH_STATUS_SUCCESS, capi.lib.NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID ] if ret not in ok: raise errors.NotmuchError(ret) msg = message.Message(self, msg_pp[0], db=self) if sync_flags: msg.tags.from_maildir_flags() return self.AddedMessage( msg, ret == capi.lib.NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID) def remove(self, filename): """Remove a message from the notmuch database. Removing a message which is not in the database is just a silent nop-operation. :param filename: The pathname of the file containing the message to be removed. :type filename: str, bytes, os.PathLike or pathlib.Path. :returns: True if the message is still in the database. This can happen when multiple files contain the same message ID. The true/false distinction is fairly arbitrary, but think of it as ``dup = db.remove_message(name); if dup: ...``. :rtype: bool :raises XapianError: A Xapian exception occurred. :raises ReadOnlyDatabaseError: The database is opened in READ_ONLY mode. :raises UpgradeRequiredError: The database must be upgraded first. :raises ObjectDestroyedError: if used after destroyed. """ if not hasattr(os, 'PathLike') and isinstance(filename, pathlib.Path): filename = bytes(filename) ret = capi.lib.notmuch_database_remove_message(self._db_p, os.fsencode(filename)) ok = [ capi.lib.NOTMUCH_STATUS_SUCCESS, capi.lib.NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID ] if ret not in ok: raise errors.NotmuchError(ret) if ret == capi.lib.NOTMUCH_STATUS_DUPLICATE_MESSAGE_ID: return True else: return False def find(self, msgid): """Return the message matching the given message ID. If a message with the given message ID is found a :class:`Message` instance is returned. Otherwise a :exc:`LookupError` is raised. :param msgid: The message ID to look for. :type msgid: str :returns: The message instance. :rtype: Message :raises LookupError: If no message was found. :raises OutOfMemoryError: When there is no memory to allocate the message instance. :raises XapianError: A Xapian exception occurred. :raises ObjectDestroyedError: if used after destroyed. """ msg_pp = capi.ffi.new('notmuch_message_t **') ret = capi.lib.notmuch_database_find_message(self._db_p, msgid.encode(), msg_pp) if ret != capi.lib.NOTMUCH_STATUS_SUCCESS: raise errors.NotmuchError(ret) msg_p = msg_pp[0] if msg_p == capi.ffi.NULL: raise LookupError msg = message.Message(self, msg_p, db=self) return msg def get(self, filename): """Return the :class:`Message` given a pathname. If a message with the given pathname exists in the database return the :class:`Message` instance for the message. Otherwise raise a :exc:`LookupError` exception. :param filename: The pathname of the message. :type filename: str, bytes, os.PathLike or pathlib.Path :returns: The message instance. :rtype: Message :raises LookupError: If no message was found. This is also a subclass of :exc:`KeyError`. :raises OutOfMemoryError: When there is no memory to allocate the message instance. :raises XapianError: A Xapian exception occurred. :raises ObjectDestroyedError: if used after destroyed. """ if not hasattr(os, 'PathLike') and isinstance(filename, pathlib.Path): filename = bytes(filename) msg_pp = capi.ffi.new('notmuch_message_t **') ret = capi.lib.notmuch_database_find_message_by_filename( self._db_p, os.fsencode(filename), msg_pp) if ret != capi.lib.NOTMUCH_STATUS_SUCCESS: raise errors.NotmuchError(ret) msg_p = msg_pp[0] if msg_p == capi.ffi.NULL: raise LookupError msg = message.Message(self, msg_p, db=self) return msg @property def tags(self): """Return an immutable set with all tags used in this database. This returns an immutable set-like object implementing the collections.abc.Set Abstract Base Class. Due to the underlying libnotmuch implementation some operations have different performance characteristics then plain set objects. Mainly any lookup operation is O(n) rather then O(1). Normal usage treats tags as UTF-8 encoded unicode strings so they are exposed to Python as normal unicode string objects. If you need to handle tags stored in libnotmuch which are not valid unicode do check the :class:`ImmutableTagSet` docs for how to handle this. :rtype: ImmutableTagSet :raises ObjectDestroyedError: if used after destroyed. """ try: ref = self._cached_tagset except AttributeError: tagset = None else: tagset = ref() if tagset is None: tagset = tags.ImmutableTagSet( self, '_db_p', capi.lib.notmuch_database_get_all_tags) self._cached_tagset = weakref.ref(tagset) return tagset @property def config(self): """Return a mutable mapping with the settings stored in this database. This returns an mutable dict-like object implementing the collections.abc.MutableMapping Abstract Base Class. :rtype: Config :raises ObjectDestroyedError: if used after destroyed. """ try: ref = self._cached_config except AttributeError: config_mapping = None else: config_mapping = ref() if config_mapping is None: config_mapping = config.ConfigMapping(self, '_db_p') self._cached_config = weakref.ref(config_mapping) return config_mapping def _create_query( self, query, *, omit_excluded=EXCLUDE.TRUE, sort=SORT.UNSORTED, # Check this default exclude_tags=None): """Create an internal query object. :raises OutOfMemoryError: if no memory is available to allocate the query. """ if isinstance(query, str): query = query.encode('utf-8') query_p = capi.lib.notmuch_query_create(self._db_p, query) if query_p == capi.ffi.NULL: raise errors.OutOfMemoryError() capi.lib.notmuch_query_set_omit_excluded(query_p, omit_excluded.value) capi.lib.notmuch_query_set_sort(query_p, sort.value) if exclude_tags is not None: for tag in exclude_tags: if isinstance(tag, str): tag = tag.encode('utf-8') capi.lib.notmuch_query_add_tag_exclude(query_p, tag) return querymod.Query(self, query_p) def messages( self, query, *, omit_excluded=EXCLUDE.TRUE, sort=SORT.UNSORTED, # Check this default exclude_tags=None): """Search the database for messages. :returns: An iterator over the messages found. :rtype: MessageIter :raises OutOfMemoryError: if no memory is available to allocate the query. :raises ObjectDestroyedError: if used after destroyed. """ query = self._create_query(query, omit_excluded=omit_excluded, sort=sort, exclude_tags=exclude_tags) return query.messages() def count_messages( self, query, *, omit_excluded=EXCLUDE.TRUE, sort=SORT.UNSORTED, # Check this default exclude_tags=None): """Search the database for messages. :returns: An iterator over the messages found. :rtype: MessageIter :raises ObjectDestroyedError: if used after destroyed. """ query = self._create_query(query, omit_excluded=omit_excluded, sort=sort, exclude_tags=exclude_tags) return query.count_messages() def threads( self, query, *, omit_excluded=EXCLUDE.TRUE, sort=SORT.UNSORTED, # Check this default exclude_tags=None): query = self._create_query(query, omit_excluded=omit_excluded, sort=sort, exclude_tags=exclude_tags) return query.threads() def count_threads( self, query, *, omit_excluded=EXCLUDE.TRUE, sort=SORT.UNSORTED, # Check this default exclude_tags=None): query = self._create_query(query, omit_excluded=omit_excluded, sort=sort, exclude_tags=exclude_tags) return query.count_threads() def status_string(self): raise NotImplementedError def __repr__(self): return 'Database(path={self.path}, mode={self.mode})'.format(self=self)
class Message(base.NotmuchObject): """An email message stored in the notmuch database retrieved via a query. This should not be directly created, instead it will be returned by calling methods on :class:`Database`. A message keeps a reference to the database object since the database object can not be released while the message is in use. Note that this represents a message in the notmuch database. For full email functionality you may want to use the :mod:`email` package from Python's standard library. You could e.g. create this as such:: notmuch_msg = db.get_message(msgid) # or from a query parser = email.parser.BytesParser(policy=email.policy.default) with notmuch_msg.path.open('rb) as fp: email_msg = parser.parse(fp) Most commonly the functionality provided by notmuch is sufficient to read email however. Messages are considered equal when they have the same message ID. This is how libnotmuch treats messages as well, the :meth:`pathnames` function returns multiple results for duplicates. :param parent: The parent object. This is probably one off a :class:`Database`, :class:`Thread` or :class:`Query`. :type parent: NotmuchObject :param db: The database instance this message is associated with. This could be the same as the parent. :type db: Database :param msg_p: The C pointer to the ``notmuch_message_t``. :type msg_p: <cdata> :param dup: Whether the message was a duplicate on insertion. :type dup: None or bool """ _msg_p = base.MemoryPointer() def __init__(self, parent, msg_p, *, db): self._parent = parent self._msg_p = msg_p self._db = db @property def alive(self): if not self._parent.alive: return False try: self._msg_p except errors.ObjectDestroyedError: return False else: return True def __del__(self): self._destroy() def _destroy(self): if self.alive: capi.lib.notmuch_message_destroy(self._msg_p) self._msg_p = None @property def messageid(self): """The message ID as a string. The message ID is decoded with the ignore error handler. This is fine as long as the message ID is well formed. If it is not valid ASCII then this will be lossy. So if you need to be able to write the exact same message ID back you should use :attr:`messageidb`. Note that notmuch will decode the message ID value and thus strip off the surrounding ``<`` and ``>`` characters. This is different from Python's :mod:`email` package behaviour which leaves these characters in place. :returns: The message ID. :rtype: :class:`BinString`, this is a normal str but calling bytes() on it will return the original bytes used to create it. :raises ObjectDestroyedError: if used after destroyed. """ ret = capi.lib.notmuch_message_get_message_id(self._msg_p) return base.BinString(capi.ffi.string(ret)) @property def threadid(self): """The thread ID. The thread ID is decoded with the surrogateescape error handler so that it is possible to reconstruct the original thread ID if it is not valid UTF-8. :returns: The thread ID. :rtype: :class:`BinString`, this is a normal str but calling bytes() on it will return the original bytes used to create it. :raises ObjectDestroyedError: if used after destroyed. """ ret = capi.lib.notmuch_message_get_thread_id(self._msg_p) return base.BinString(capi.ffi.string(ret)) @property def path(self): """A pathname of the message as a pathlib.Path instance. If multiple files in the database contain the same message ID this will be just one of the files, chosen at random. :raises ObjectDestroyedError: if used after destroyed. """ ret = capi.lib.notmuch_message_get_filename(self._msg_p) return pathlib.Path(os.fsdecode(capi.ffi.string(ret))) @property def pathb(self): """A pathname of the message as a bytes object. See :attr:`path` for details, this is the same but does return the path as a bytes object which is faster but less convenient. :raises ObjectDestroyedError: if used after destroyed. """ ret = capi.lib.notmuch_message_get_filename(self._msg_p) return capi.ffi.string(ret) def filenames(self): """Return an iterator of all files for this message. If multiple files contained the same message ID they will all be returned here. The files are returned as instances of :class:`pathlib.Path`. :returns: Iterator yielding :class:`pathlib.Path` instances. :rtype: iter :raises ObjectDestroyedError: if used after destroyed. """ fnames_p = capi.lib.notmuch_message_get_filenames(self._msg_p) return PathIter(self, fnames_p) def filenamesb(self): """Return an iterator of all files for this message. This is like :meth:`pathnames` but the files are returned as byte objects instead. :returns: Iterator yielding :class:`bytes` instances. :rtype: iter :raises ObjectDestroyedError: if used after destroyed. """ fnames_p = capi.lib.notmuch_message_get_filenames(self._msg_p) return FilenamesIter(self, fnames_p) @property def ghost(self): """Indicates whether this message is a ghost message. A ghost message if a message which we know exists, but it has no files or content associated with it. This can happen if it was referenced by some other message. Only the :attr:`messageid` and :attr:`threadid` attributes are valid for it. :raises ObjectDestroyedError: if used after destroyed. """ ret = capi.lib.notmuch_message_get_flag( self._msg_p, capi.lib.NOTMUCH_MESSAGE_FLAG_GHOST) return bool(ret) @property def excluded(self): """Indicates whether this message was excluded from the query. When a message is created from a search, sometimes messages that where excluded by the search query could still be returned by it, e.g. because they are part of a thread matching the query. the :meth:`Database.query` method allows these messages to be flagged, which results in this property being set to *True*. :raises ObjectDestroyedError: if used after destroyed. """ ret = capi.lib.notmuch_message_get_flag( self._msg_p, capi.lib.NOTMUCH_MESSAGE_FLAG_EXCLUDED) return bool(ret) @property def date(self): """The message date as an integer. The time the message was sent as an integer number of seconds since the *epoch*, 1 Jan 1970. This is derived from the message's header, you can get the original header value with :meth:`header`. :raises ObjectDestroyedError: if used after destroyed. """ return capi.lib.notmuch_message_get_date(self._msg_p) def header(self, name): """Return the value of the named header. Returns the header from notmuch, some common headers are stored in the database, others are read from the file. Headers are returned with their newlines stripped and collapsed concatenated together if they occur multiple times. You may be better off using the standard library email package's ``email.message_from_file(msg.path.open())`` if that is not sufficient for you. :param header: Case-insensitive header name to retrieve. :type header: str or bytes :returns: The header value, an empty string if the header is not present. :rtype: str :raises LookupError: if the header is not present. :raises NullPointerError: For unexpected notmuch errors. :raises ObjectDestroyedError: if used after destroyed. """ # The returned is supposedly guaranteed to be UTF-8. Header # names must be ASCII as per RFC x822. if isinstance(name, str): name = name.encode('ascii') ret = capi.lib.notmuch_message_get_header(self._msg_p, name) if ret == capi.ffi.NULL: raise errors.NullPointerError() hdr = capi.ffi.string(ret) if not hdr: raise LookupError return hdr.decode(encoding='utf-8') @property def tags(self): """The tags associated with the message. This behaves as a set. But removing and adding items to the set removes and adds them to the message in the database. :raises ReadOnlyDatabaseError: When manipulating tags on a database opened in read-only mode. :raises ObjectDestroyedError: if used after destroyed. """ try: ref = self._cached_tagset except AttributeError: tagset = None else: tagset = ref() if tagset is None: tagset = tags.MutableTagSet(self, '_msg_p', capi.lib.notmuch_message_get_tags) self._cached_tagset = weakref.ref(tagset) return tagset @contextlib.contextmanager def frozen(self): """Context manager to freeze the message state. This allows you to perform atomic tag updates:: with msg.frozen(): msg.tags.clear() msg.tags.add('foo') Using This would ensure the message never ends up with no tags applied at all. It is safe to nest calls to this context manager. :raises ReadOnlyDatabaseError: if the database is opened in read-only mode. :raises UnbalancedFreezeThawError: if you somehow managed to call __exit__ of this context manager more than once. Why did you do that? :raises ObjectDestroyedError: if used after destroyed. """ ret = capi.lib.notmuch_message_freeze(self._msg_p) if ret != capi.lib.NOTMUCH_STATUS_SUCCESS: raise errors.NotmuchError(ret) self._frozen = True try: yield except Exception: # Only way to "rollback" these changes is to destroy # ourselves and re-create. Behold. msgid = self.messageid self._destroy() with contextlib.suppress(Exception): new = self._db.find(msgid) self._msg_p = new._msg_p new._msg_p = None del new raise else: ret = capi.lib.notmuch_message_thaw(self._msg_p) if ret != capi.lib.NOTMUCH_STATUS_SUCCESS: raise errors.NotmuchError(ret) self._frozen = False @property def properties(self): """A map of arbitrary key-value pairs associated with the message. Be aware that properties may be used by other extensions to store state in. So delete or modify with care. The properties map is somewhat special. It is essentially a multimap-like structure where each key can have multiple values. Therefore accessing a single item using :meth:`PropertiesMap.get` or :meth:`PropertiesMap.__getitem__` will only return you the *first* item if there are multiple and thus are only recommended if you know there to be only one value. Instead the map has an additional :meth:`PropertiesMap.all` method which can be used to retrieve all properties of a given key. This method also allows iterating of a a subset of the keys starting with a given prefix. """ try: ref = self._cached_props except AttributeError: props = None else: props = ref() if props is None: props = PropertiesMap(self, '_msg_p') self._cached_props = weakref.ref(props) return props def replies(self): """Return an iterator of all replies to this message. This method will only work if the message was created from a thread. Otherwise it will yield no results. :returns: An iterator yielding :class:`Message` instances. :rtype: MessageIter """ # The notmuch_messages_valid call accepts NULL and this will # become an empty iterator, raising StopIteration immediately. # Hence no return value checking here. msgs_p = capi.lib.notmuch_message_get_replies(self._msg_p) return MessageIter(self, msgs_p, db=self._db) def __hash__(self): return hash(self.messageid) def __eq__(self, other): if isinstance(other, self.__class__): return self.messageid == other.messageid
class Thread(base.NotmuchObject, collections.abc.Iterable): _thread_p = base.MemoryPointer() def __init__(self, parent, thread_p, *, db): self._parent = parent self._thread_p = thread_p self._db = db @property def alive(self): if not self._parent.alive: return False try: self._thread_p except errors.ObjectDestroyedError: return False else: return True def __del__(self): self._destroy() def _destroy(self): if self.alive: capi.lib.notmuch_thread_destroy(self._thread_p) self._thread_p = None @property def threadid(self): """The thread ID as a :class:`BinString`. :raises ObjectDestroyedError: if used after destroyed. """ ret = capi.lib.notmuch_thread_get_thread_id(self._thread_p) return base.BinString.from_cffi(ret) def __len__(self): """Return the number of messages in the thread. :raises ObjectDestroyedError: if used after destroyed. """ return capi.lib.notmuch_thread_get_total_messages(self._thread_p) def toplevel(self): """Return an iterator of the toplevel messages. :returns: An iterator yielding :class:`Message` instances. :raises ObjectDestroyedError: if used after destroyed. """ msgs_p = capi.lib.notmuch_thread_get_toplevel_messages(self._thread_p) return message.MessageIter(self, msgs_p, db=self._db, msg_cls=message.OwnedMessage) def __iter__(self): """Return an iterator over all the messages in the thread. :returns: An iterator yielding :class:`Message` instances. :raises ObjectDestroyedError: if used after destroyed. """ msgs_p = capi.lib.notmuch_thread_get_messages(self._thread_p) return message.MessageIter(self, msgs_p, db=self._db, msg_cls=message.OwnedMessage) @property def matched(self): """The number of messages in this thread which matched the query. Of the messages in the thread this gives the count of messages which did directly match the search query which this thread originates from. :raises ObjectDestroyedError: if used after destroyed. """ return capi.lib.notmuch_thread_get_matched_messages(self._thread_p) @property def authors(self): """A comma-separated string of all authors in the thread. Authors of messages which matched the query the thread was retrieved from will be at the head of the string, ordered by date of their messages. Following this will be the authors of the other messages in the thread, also ordered by date of their messages. Both groups of authors are separated by the ``|`` character. :returns: The stringified list of authors. :rtype: BinString :raises ObjectDestroyedError: if used after destroyed. """ ret = capi.lib.notmuch_thread_get_authors(self._thread_p) return base.BinString.from_cffi(ret) @property def subject(self): """The subject of the thread, taken from the first message. The thread's subject is taken to be the subject of the first message according to query sort order. :returns: The thread's subject. :rtype: BinString :raises ObjectDestroyedError: if used after destroyed. """ ret = capi.lib.notmuch_thread_get_subject(self._thread_p) return base.BinString.from_cffi(ret) @property def first(self): """Return the date of the oldest message in the thread. The time the first message was sent as an integer number of seconds since the *epoch*, 1 Jan 1970. :raises ObjectDestroyedError: if used after destroyed. """ return capi.lib.notmuch_thread_get_oldest_date(self._thread_p) @property def last(self): """Return the date of the newest message in the thread. The time the last message was sent as an integer number of seconds since the *epoch*, 1 Jan 1970. :raises ObjectDestroyedError: if used after destroyed. """ return capi.lib.notmuch_thread_get_newest_date(self._thread_p) @property def tags(self): """Return an immutable set with all tags used in this thread. This returns an immutable set-like object implementing the collections.abc.Set Abstract Base Class. Due to the underlying libnotmuch implementation some operations have different performance characteristics then plain set objects. Mainly any lookup operation is O(n) rather then O(1). Normal usage treats tags as UTF-8 encoded unicode strings so they are exposed to Python as normal unicode string objects. If you need to handle tags stored in libnotmuch which are not valid unicode do check the :class:`ImmutableTagSet` docs for how to handle this. :rtype: ImmutableTagSet :raises ObjectDestroyedError: if used after destroyed. """ try: ref = self._cached_tagset except AttributeError: tagset = None else: tagset = ref() if tagset is None: tagset = tags.ImmutableTagSet( self, '_thread_p', capi.lib.notmuch_thread_get_tags) self._cached_tagset = weakref.ref(tagset) return tagset
class Query(base.NotmuchObject): """Private, minimal query object. This is not meant for users and is not a full implementation of the query API. It is only an intermediate used internally to match libnotmuch's memory management. """ _query_p = base.MemoryPointer() def __init__(self, db, query_p): self._db = db self._query_p = query_p @property def alive(self): if not self._db.alive: return False try: self._query_p except errors.ObjectDestroyedError: return False else: return True def __del__(self): self._destroy() def _destroy(self): if self.alive: capi.lib.notmuch_query_destroy(self._query_p) self._query_p = None @property def query(self): """The query string as seen by libnotmuch.""" q = capi.lib.notmuch_query_get_query_string(self._query_p) return base.BinString.from_cffi(q) def messages(self): """Return an iterator over all the messages found by the query. This executes the query and returns an iterator over the :class:`Message` objects found. """ msgs_pp = capi.ffi.new('notmuch_messages_t**') ret = capi.lib.notmuch_query_search_messages(self._query_p, msgs_pp) if ret != capi.lib.NOTMUCH_STATUS_SUCCESS: raise errors.NotmuchError(ret) return message.MessageIter(self, msgs_pp[0], db=self._db) def count_messages(self): """Return the number of messages matching this query.""" count_p = capi.ffi.new('unsigned int *') ret = capi.lib.notmuch_query_count_messages(self._query_p, count_p) if ret != capi.lib.NOTMUCH_STATUS_SUCCESS: raise errors.NotmuchError(ret) return count_p[0] def collect_tags(self): """Return the tags of messages matching this query.""" msgs_pp = capi.ffi.new('notmuch_messages_t**') ret = capi.lib.notmuch_query_search_messages(self._query_p, msgs_pp) if ret != capi.lib.NOTMUCH_STATUS_SUCCESS: raise errors.NotmuchError(ret) self._msgs_p = msgs_pp[0] tagset = tags.ImmutableTagSet(self, '_msgs_p', capi.lib.notmuch_messages_collect_tags) return tags.ImmutableTagSet._from_iterable(tagset) def threads(self): """Return an iterator over all the threads found by the query.""" threads_pp = capi.ffi.new('notmuch_threads_t **') ret = capi.lib.notmuch_query_search_threads(self._query_p, threads_pp) if ret != capi.lib.NOTMUCH_STATUS_SUCCESS: raise errors.NotmuchError(ret) return thread.ThreadIter(self, threads_pp[0], db=self._db) def count_threads(self): """Return the number of threads matching this query.""" count_p = capi.ffi.new('unsigned int *') ret = capi.lib.notmuch_query_count_threads(self._query_p, count_p) if ret != capi.lib.NOTMUCH_STATUS_SUCCESS: raise errors.NotmuchError(ret) return count_p[0]
class TagsIter(base.NotmuchObject, collections.abc.Iterator): """Iterator over tags. This is only an iterator, not a container so calling :meth:`__iter__` does not return a new, replenished iterator but only itself. :param parent: The parent object to keep alive. :param tags_p: The CFFI pointer to the C-level tags iterator. :param encoding: Which codec to use. The default *None* does not decode at all and will return the unmodified bytes. Otherwise this is passed on to :func:`str.decode`. :param errors: If using a codec, this is the error handler. See :func:`str.decode` to which this is passed on. :raises ObjectDestroyedError: if used after destroyed. """ _tags_p = base.MemoryPointer() def __init__(self, parent, tags_p, *, encoding=None, errors='strict'): self._parent = parent self._tags_p = tags_p self._encoding = encoding self._errors = errors def __del__(self): self._destroy() @property def alive(self): if not self._parent.alive: return False try: self._tags_p except errors.ObjectDestroyedError: return False else: return True def _destroy(self): if self.alive: try: capi.lib.notmuch_tags_destroy(self._tags_p) except errors.ObjectDestroyedError: pass self._tags_p = None def __iter__(self): """Return the iterator itself. Note that as this is an iterator and not a container this will not return a new iterator. Thus any elements already consumed will not be yielded by the :meth:`__next__` method anymore. """ return self def __next__(self): if not capi.lib.notmuch_tags_valid(self._tags_p): self._destroy() raise StopIteration() tag_p = capi.lib.notmuch_tags_get(self._tags_p) tag = capi.ffi.string(tag_p) if self._encoding: tag = tag.decode(encoding=self._encoding, errors=self._errors) capi.lib.notmuch_tags_move_to_next(self._tags_p) return tag def __repr__(self): try: self._tags_p except errors.ObjectDestroyedError: return '<TagsIter (exhausted)>' else: return '<TagsIter>'