git.notmuchmail.org Git - notmuch/blob - bindings/python/README

   1 notmuch -- The python interface to notmuch.so
   2 ==============================================
   3
   4 This module makes the functionality of the notmuch library
   5 (`http://notmuchmail.org`_) available to python. Successful import of
   6 this modul depends on a libnotmuch.so|dll being available on the
   7 user's system.
   8
   9 If you have downloaded the full source tarball, you can create the
  10 documentation with sphinx installed, go to the docs directory and
  11 "make html". A static version of the documentation is available at:
  12
  13 http://packages.python.org/notmuch/
  14
  15 The current source code is being hosted at
  16 http://bitbucket.org/spaetz/cnotmuch which also provides an issue
  17 tracker, and release downloads. This package is tracked by the python
  18 package index repository at `http://pypi.python.org/pypi/notmuch`_ and can thus be installed on a user's computer easily via "sudo easy_install notmuch" (you will still need to install the notmuch shared library separately as it is not included in this package).
  19
  20 The original source has been provided by (c)Sebastian Spaeth, 2010.
  21 All code is available under the GNU GPLv3+ (see docs/COPYING) unless specified otherwise.
  22
  23
  24 INSTALLATION & DEINSTALL
  25 ------------------------
  26
  27 The notmuch python module is available on pypi.python.org. This means
  28 you can do "easy_install notmuch" on your linux box and it will get
  29 installed into:
  30
  31 /usr/local/lib/python2.x/dist-packages/
  32
  33 For uninstalling, you'll need to remove the "notmuch-0.4-py2.x.egg"
  34 (or similar) directory and delete one entry in the "easy-install.pth"
  35 file in that directory.
  36
  37 It needs to have a libnotmuch.so or libnotmuch.so.1 available in some
  38 library folder or will raise an exception when loading.
  39 "OSError: libnotmuch.so.1: cannot open shared object file: No such file or directory"
  40
  41
  42 Usage
  43 -----
  44 For more examples of how to use the notmuch interface, have a look at the
  45 notmuch "binary" and the generated documentation.
  46
  47 Example session:
  48 >>>import notmuch
  49 >>>db = notmuch.Database("/home/spaetz/mail")
  50 db.get_path()
  51 '/home/spaetz/mail'
  52 >>>tags = db.get_all_tags()
  53 >>>for tag in tags:
  54 >>>  print tag
  55 inbox
  56 ...
  57 maildir::draft
  58 #---------------------------------------------
  59
  60 q = notmuch.Query(db,'from:Sebastian')
  61 count = len(q.search_messages())
  62 1300
  63
  64 #---------------------------------------------
  65
  66 >>>db = notmuch.Database("/home/spaetz/mailHAHA")
  67 NotmuchError: Could not open the specified database
  68
  69 #---------------------------------------------
  70
  71 >>>tags = notmuch.Database("/home/spaetz/mail").get_all_tags()
  72 >>>del(tags)
  73
  74
  75 Building for a Debian package
  76 ------------------------------
  77 dpkg-buildpackage -i"\.hg|\/build"
  78
  79
  80 Changelog
  81 ---------
  82 0.1   First public release
  83 0.1.1 Fixed Database.create_query()
  84 0.2.0 Implemented Thread() and Threads() methods
  85 0.2.1 Implemented the remaining API methods, notably Directory() and Filenames()
  86 0.2.2 Bug fixes
  87 0.3.0 Incorporated in the notmuchmail.org git repository