From c50524efd523e885f370374e33cd5d5549ed9079 Mon Sep 17 00:00:00 2001
From: Sebastian Spaeth <Sebastian@SSpaeth.de>
Date: Sun, 16 May 2010 15:56:27 -0700
Subject: [PATCH] python: have docs reflect current return value behavior
Database.find_message() used to be able to reliably indicate whether a
message exists or not (in which case it returns None). However, the
recent API change of the notmuch library means we will return None
even for all Xapian exceptions, which happens e.g. when the current
Database has been modified by another project. Therefore the return
value of None cannot be reliably be used to indicate whether a message
exists or not. Make the docs state that explicitely.
Signed-off-by: Sebastian Spaeth <Sebastian@SSpaeth.de>
---
bindings/python/notmuch/database.py | 10 ++++++++--
1 file changed, 8 insertions(+), 2 deletions(-)
diff --git a/bindings/python/notmuch/database.py b/bindings/python/notmuch/database.py
index fc7edf0b..7f0091de 100644
--- a/bindings/python/notmuch/database.py
+++ b/bindings/python/notmuch/database.py
@@ -358,8 +358,14 @@ class Database(object):
:param msgid: The message ID
:type msgid: string
- :returns: :class:`Message` or `None` if no message is found or if an
- out-of-memory situation occurs.
+ :returns: :class:`Message` or `None` if no message is found or
+ if any xapian exception or out-of-memory situation
+ occurs. Do note that Xapian Exceptions include
+ "Database modified" situations, e.g. when the
+ notmuch database has been modified by
+ another program in the meantime. A return value of
+ `None` is therefore no guarantee that the message
+ does not exist.
:exception: :exc:`NotmuchError` with STATUS.NOT_INITIALIZED if
the database was not intitialized.
"""
--
2.45.2