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