git.notmuchmail.org Git - notmuch/blob - bindings/python-cffi/notmuch2/__init__.py

   1 """Pythonic API to the notmuch database.
   2
   3 Creating Objects
   4 ================
   5
   6 Only the :class:`Database` object is meant to be created by the user.
   7 All other objects should be created from this initial object.  Users
   8 should consider their signatures implementation details.
   9
  10 Errors
  11 ======
  12
  13 All errors occuring due to errors from the underlying notmuch database
  14 are subclasses of the :exc:`NotmuchError`.  Due to memory management
  15 it is possible to try and use an object after it has been freed.  In
  16 this case a :exc:`ObjectDestroyedError` will be raised.
  17
  18 Memory Management
  19 =================
  20
  21 Libnotmuch uses a hierarchical memory allocator, this means all
  22 objects have a strict parent-child relationship and when the parent is
  23 freed all the children are freed as well.  This has some implications
  24 for these Python bindings as parent objects need to be kept alive.
  25 This is normally schielded entirely from the user however and the
  26 Python objects automatically make sure the right references are kept
  27 alive.  It is however the reason the :class:`BaseObject` exists as it
  28 defines the API all Python objects need to implement to work
  29 correctly.
  30
  31 Collections and Containers
  32 ==========================
  33
  34 Libnotmuch exposes nearly all collections of things as iterators only.
  35 In these python bindings they have sometimes been exposed as
  36 :class:`collections.abc.Container` instances or subclasses of this
  37 like :class:`collections.abc.Set` or :class:`collections.abc.Mapping`
  38 etc.  This gives a more natural API to work with, e.g. being able to
  39 treat tags as sets.  However it does mean that the
  40 :meth:`__contains__`, :meth:`__len__` and frieds methods on these are
  41 usually more and essentially O(n) rather than O(1) as you might
  42 usually expect from Python containers.
  43 """
  44
  45 from notmuch2 import _capi
  46 from notmuch2._base import *
  47 from notmuch2._database import *
  48 from notmuch2._errors import *
  49 from notmuch2._message import *
  50 from notmuch2._tags import *
  51 from notmuch2._thread import *
  52
  53
  54 NOTMUCH_TAG_MAX = _capi.lib.NOTMUCH_TAG_MAX
  55 del _capi
  56
  57
  58 # Re-home all the objects to the package.  This leaves __qualname__ intact.
  59 for x in locals().copy().values():
  60     if hasattr(x, '__module__'):
  61         x.__module__ = __name__
  62 del x