git.notmuchmail.org Git - notmuch/blob - cnotmuch/notmuch.py

   1 """The :mod:`notmuch` module provides most of the functionality that a user is likely to need.
   2
   3 Many of its objects use python's logging module to log some output at DEBUG level.
   4
   5 .. note:: The underlying notmuch library is build on a hierarchical
   6     memory allocator called talloc. All objects derive from a
   7     top-level :class:`Database` object.
   8
   9     This means that as soon as an object is deleted, all underlying
  10     derived objects such as Queries, Messages, Message, and Tags will
  11     be freed by the underlying library as well. Accessing these
  12     objects will then lead to segfaults and other unexpected behavior.
  13
  14     We implement reference counting, so that parent objects can be
  15     automatically freed when they are not needed anymore. For
  16     example::
  17
  18             db = Database('path',create=True)
  19             msgs = Query(db,'from:myself').search_messages()
  20
  21     This returns a :class:`Messages` which internally contains a
  22     reference to its parent :class:`Query` object. Otherwise the
  23     Query() would be immediately freed, taking our *msgs* down with
  24     it.
  25
  26     In this case, the above Query() object will be automatically freed
  27     whenever we delete all derived objects, ie in our case:
  28     `del(msgs)` would also delete the parent Query (but not the parent
  29     Database() as that is still referenced from the variable *db* in
  30     which it is stored.
  31
  32     Pretty much the same is valid for all other objects in the
  33     hierarchy, such as :class:`Query`, :class:`Messages`,
  34     :class:`Message`, and :class:`Tags`.
  35
  36 """
  37 import ctypes
  38 from ctypes import c_int, c_char_p
  39 from database import Database,Tags,Query,Messages,Message,Tags
  40 from cnotmuch.globals import nmlib,STATUS,NotmuchError
  41 __LICENSE__="GPL v3+"
  42 __VERSION__=0.1
  43 __AUTHOR__ ="Sebastian Spaeth <Sebastian@SSpaeth.de>"
  44