+++ /dev/null
-import abc
-import collections.abc
-
-from notdb import _capi as capi
-from notdb import _errors as errors
-
-
-__all__ = ['NotmuchObject', 'BinString']
-
-
-class NotmuchObject(metaclass=abc.ABCMeta):
- """Base notmuch object syntax.
-
- This base class exists to define the memory management handling
- required to use the notmuch library. It is meant as an interface
- definition rather than a base class, though you can use it as a
- base class to ensure you don't forget part of the interface. It
- only concerns you if you are implementing this package itself
- rather then using it.
-
- libnotmuch uses a hierarchical memory allocator, where freeing the
- memory of a parent object also frees the memory of all child
- objects. To make this work seamlessly in Python this package
- keeps references to parent objects which makes them stay alive
- correctly under normal circumstances. When an object finally gets
- deleted the :meth:`__del__` method will be called to free the
- memory.
-
- However during some peculiar situations, e.g. interpreter
- shutdown, it is possible for the :meth:`__del__` method to have
- been called, whele there are still references to an object. This
- could result in child objects asking their memeory to be freed
- after the parent has already freed the memory, making things
- rather unhappy as double frees are not taken lightly in C. To
- handle this case all objects need to follow the same protocol to
- destroy themselves, see :meth:`destroy`.
-
- Once an object has been destroyed trying to use it should raise
- the :exc:`ObjectDestroyedError` exception. For this see also the
- convenience :class:`MemoryPointer` descriptor in this module which
- can be used as a pointer to libnotmuch memory.
- """
-
- @abc.abstractmethod
- def __init__(self, parent, *args, **kwargs):
- """Create a new object.
-
- Other then for the toplevel :class:`Database` object
- constructors are only ever called by internal code and not by
- the user. Per convention their signature always takes the
- parent object as first argument. Feel free to make the rest
- of the signature match the object's requirement. The object
- needs to keep a reference to the parent, so it can check the
- parent is still alive.
- """
-
- @property
- @abc.abstractmethod
- def alive(self):
- """Whether the object is still alive.
-
- This indicates whether the object is still alive. The first
- thing this needs to check is whether the parent object is
- still alive, if it is not then this object can not be alive
- either. If the parent is alive then it depends on whether the
- memory for this object has been freed yet or not.
- """
-
- def __del__(self):
- self._destroy()
-
- @abc.abstractmethod
- def _destroy(self):
- """Destroy the object, freeing all memory.
-
- This method needs to destory the object on the
- libnotmuch-level. It must ensure it's not been destroyed by
- it's parent object yet before doing so. It also must be
- idempotent.
- """
-
-
-class MemoryPointer:
- """Data Descriptor to handle accessing libnotmuch pointers.
-
- Most :class:`NotmuchObject` instances will have one or more CFFI
- pointers to C-objects. Once an object is destroyed this pointer
- should no longer be used and a :exc:`ObjectDestroyedError`
- exception should be raised on trying to access it. This
- descriptor simplifies implementing this, allowing the creation of
- an attribute which can be assigned to, but when accessed when the
- stored value is *None* it will raise the
- :exc:`ObjectDestroyedError` exception::
-
- class SomeOjb:
- _ptr = MemoryPointer()
-
- def __init__(self, ptr):
- self._ptr = ptr
-
- def destroy(self):
- somehow_free(self._ptr)
- self._ptr = None
-
- def do_something(self):
- return some_libnotmuch_call(self._ptr)
- """
-
- def __get__(self, instance, owner):
- try:
- val = getattr(instance, self.attr_name, None)
- except AttributeError:
- # We're not on 3.6+ and self.attr_name does not exist
- self.__set_name__(instance, 'dummy')
- val = getattr(instance, self.attr_name, None)
- if val is None:
- raise errors.ObjectDestroyedError()
- return val
-
- def __set__(self, instance, value):
- try:
- setattr(instance, self.attr_name, value)
- except AttributeError:
- # We're not on 3.6+ and self.attr_name does not exist
- self.__set_name__(instance, 'dummy')
- setattr(instance, self.attr_name, value)
-
- def __set_name__(self, instance, name):
- self.attr_name = '_memptr_{}_{:x}'.format(name, id(instance))
-
-
-class BinString(str):
- """A str subclass with binary data.
-
- Most data in libnotmuch should be valid ASCII or valid UTF-8.
- However since it is a C library these are represented as
- bytestrings intead which means on an API level we can not
- guarantee that decoding this to UTF-8 will both succeed and be
- lossless. This string type converts bytes to unicode in a lossy
- way, but also makes the raw bytes available.
-
- This object is a normal unicode string for most intents and
- purposes, but you can get the original bytestring back by calling
- ``bytes()`` on it.
- """
-
- def __new__(cls, data, encoding='utf-8', errors='ignore'):
- if not isinstance(data, bytes):
- data = bytes(data, encoding=encoding)
- strdata = str(data, encoding=encoding, errors=errors)
- inst = super().__new__(cls, strdata)
- inst._bindata = data
- return inst
-
- @classmethod
- def from_cffi(cls, cdata):
- """Create a new string from a CFFI cdata pointer."""
- return cls(capi.ffi.string(cdata))
-
- def __bytes__(self):
- return self._bindata
-
-
-class NotmuchIter(NotmuchObject, collections.abc.Iterator):
- """An iterator for libnotmuch iterators.
-
- It is tempting to use a generator function instead, but this would
- not correctly respect the :class:`NotmuchObject` memory handling
- protocol and in some unsuspecting cornercases cause memory
- trouble. You probably want to sublcass this in order to wrap the
- value returned by :meth:`__next__`.
-
- :param parent: The parent object.
- :type parent: NotmuchObject
- :param iter_p: The CFFI pointer to the C iterator.
- :type iter_p: cffi.cdata
- :param fn_destory: The CFFI notmuch_*_destroy function.
- :param fn_valid: The CFFI notmuch_*_valid function.
- :param fn_get: The CFFI notmuch_*_get function.
- :param fn_next: The CFFI notmuch_*_move_to_next function.
- """
- _iter_p = MemoryPointer()
-
- def __init__(self, parent, iter_p,
- *, fn_destroy, fn_valid, fn_get, fn_next):
- self._parent = parent
- self._iter_p = iter_p
- self._fn_destroy = fn_destroy
- self._fn_valid = fn_valid
- self._fn_get = fn_get
- self._fn_next = fn_next
-
- def __del__(self):
- self._destroy()
-
- @property
- def alive(self):
- if not self._parent.alive:
- return False
- try:
- self._iter_p
- except errors.ObjectDestroyedError:
- return False
- else:
- return True
-
- def _destroy(self):
- if self.alive:
- try:
- self._fn_destroy(self._iter_p)
- except errors.ObjectDestroyedError:
- pass
- self._iter_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 self._fn_valid(self._iter_p):
- self._destroy()
- raise StopIteration()
- obj_p = self._fn_get(self._iter_p)
- self._fn_next(self._iter_p)
- return obj_p
-
- def __repr__(self):
- try:
- self._iter_p
- except errors.ObjectDestroyedError:
- return '<NotmuchIter (exhausted)>'
- else:
- return '<NotmuchIter>'
projects / notmuch / blobdiff