Python updates

[Sebastian Spaeth]

Hi all,
I just wanted to keep everyone updated on the python API changes that
are in the master branch. With one exception everything is backwards
compatible. Feel free to stuff this into the .6 release notes :).

- Messages() can now be "listified" with a simple: msglist = list(...)
  in case you plan to keep doing stuff with the contained messages. For
  this to work, the API had to be broken: __len__ function was
  implicitly invoked by list(), exhausting the iterator. By removing
  __len__ (and implementing __nonzero__ instead), the list() function
  works now fine on a Messages() instance. If you need the length of
  your Messages() object, you can use:

    - Query(...).count_messages() #for a pretty close approximation
    - len(list(Messages())) #for the precise count (exhausting the
      iterator)
    - bool(Messages()) to see if still at least one more Message() is
      contained in the iterator.

- Message() now has a get_filenames() method which returns an iterator
  (generator function to be precise), pointing to all filenames that are
  recorded for that message ID. list(msg1.get_filenames()) will return
  all recorded names as a list.

- Message() now implements _cmp_ and _hash_. This enables a) comparison
  of Messages: msgs1 == msgs2 is True if they both 1) contain a Message
  object with the same Message-ID and 2) if the list of contained file
  names is identical.

  Another implication is that set() arithmetic on Messages() is now
  possible:
  db= notmuch.Database()
  msgs1= set(notmuch.Query(db, 'from:Sebastian').search_messages())
  msgs2= set(notmuch.Query(db, 'not to:notmuch').search_messages())

  msgs3 = msgs1.union(msgs2)
  msgs3 = msgs1.difference(msgs2)
  etc...

  I don't need to mention that the performance of set arithmetic (being
  completely done in python) is going to be abysmal compared to redoing
  proper Querys, yet, it might come in handy here or there.

  It also means you can do things like:

  msgs1= list(notmuch.Query(db, 'from:Sebastian').search_messages())
  msg= list(notmuch.Query(db, 'not to:notmuch').search_messages())[0]
  
  if msg in msgs1:
     #Yes!!!

- Both Message() and Messages() implement now __nonzero__() which is
  used for boolean testing. To see whether a Message() actually contains
  a Message, you can now do: bool(msg) or if msg: ...

  More useful, for Messages() you can check if your iterator still
  contains at least one more Message():

  msgs = notmuch.Query(db, 'from:Sebastian').search_messages()
  while msgs:
     msg = msgs.next() #yes, this will work we still had one!


  and also:

  msgs = notmuch.Query(db, 'from:quackydiquack').search_messages()
  if not msgs:
    print "Oh my, no search result for this weird query"


Have fun
Sebastian
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 197 bytes
Desc: not available
URL: <http://notmuchmail.org/pipermail/notmuch/attachments/20110616/09f3a1d1/attachment.pgp>