notmuch as a shared object aka library knigge

diff --git a/3e/55b63cdc7033db2fc3af9024dc75c20064abc0 b/3e/55b63cdc7033db2fc3af9024dc75c20064abc0
new file mode 100644 (file)
index 0000000..49e472e
--- /dev/null
+++ b/3e/55b63cdc7033db2fc3af9024dc75c20064abc0
@@ -0,0 +1,126 @@
+Return-Path: <teythoon@jade-hamburg.de>\r
+X-Original-To: notmuch@notmuchmail.org\r
+Delivered-To: notmuch@notmuchmail.org\r
+Received: from localhost (localhost [127.0.0.1])\r
+       by olra.theworths.org (Postfix) with ESMTP id 8B820431FAF\r
+       for <notmuch@notmuchmail.org>; Mon, 20 Feb 2012 16:29:30 -0800 (PST)\r
+X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
+X-Amavis-Alert: BAD HEADER SECTION, Duplicate header field: "Date"\r
+X-Spam-Flag: NO\r
+X-Spam-Score: 0.432\r
+X-Spam-Level: \r
+X-Spam-Status: No, score=0.432 tagged_above=-999 required=5\r
+       tests=[INVALID_DATE=0.432] autolearn=disabled\r
+Received: from olra.theworths.org ([127.0.0.1])\r
+       by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
+       with ESMTP id aSJ7quxRkytu for <notmuch@notmuchmail.org>;\r
+       Mon, 20 Feb 2012 16:29:29 -0800 (PST)\r
+Received: from mail.cryptobitch.de (cryptobitch.de [88.198.7.68])\r
+       (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits))\r
+       (No client certificate requested)\r
+       by olra.theworths.org (Postfix) with ESMTPS id D22A9431FAE\r
+       for <notmuch@notmuchmail.org>; Mon, 20 Feb 2012 16:29:28 -0800 (PST)\r
+Received: from mail.jade-hamburg.de (unknown [85.183.11.228])\r
+       (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits))\r
+       (No client certificate requested)\r
+       by mail.cryptobitch.de (Postfix) with ESMTPSA id 218E45312DC\r
+       for <notmuch@notmuchmail.org>; Tue, 21 Feb 2012 01:29:27 +0100 (CET)\r
+Received: by mail.jade-hamburg.de (Postfix, from userid 401)\r
+       id 180BBDF2A4; Tue, 21 Feb 2012 01:29:26 +0100 (CET)\r
+Received: from thinkbox.jade-hamburg.de\r
+       (dslb-088-075-032-221.pools.arcor-ip.net [88.75.32.221])\r
+       (using TLSv1 with cipher AES256-SHA (256/256 bits))\r
+       (No client certificate requested) (Authenticated sender: teythoon)\r
+       by mail.jade-hamburg.de (Postfix) with ESMTPSA id 46CD7DF2A1\r
+       for <notmuch@notmuchmail.org>; Tue, 21 Feb 2012 01:29:25 +0100 (CET)\r
+Received: from teythoon by thinkbox.jade-hamburg.de with local (Exim 4.77)\r
+       (envelope-from <teythoon@thinkbox.jade-hamburg.de>)\r
+       id 1Rzdbd-0002Sp-Ss\r
+       for notmuch@notmuchmail.org; Tue, 21 Feb 2012 01:29:21 +0100\r
+Content-Type: text/plain; charset="utf-8"\r
+MIME-Version: 1.0\r
+Content-Transfer-Encoding: quoted-printable\r
+From: Justus Winter <4winter@informatik.uni-hamburg.de>\r
+User-Agent: alot/0.21+\r
+To: notmuch mailing list      <notmuch@notmuchmail.org>, \r
+Date: Tue, 21 Feb 2012 00:29:21 -0000\r
+Message-ID: <20120221002921.8534.57091@thinkbox.jade-hamburg.de>\r
+Subject: notmuch as a shared object aka library knigge\r
+Date: Tue, 21 Feb 2012 01:29:21 +0100\r
+X-BeenThere: notmuch@notmuchmail.org\r
+X-Mailman-Version: 2.1.13\r
+Precedence: list\r
+List-Id: "Use and development of the notmuch mail system."\r
+       <notmuch.notmuchmail.org>\r
+List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
+       <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
+List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
+List-Post: <mailto:notmuch@notmuchmail.org>\r
+List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
+List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
+       <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
+X-List-Received-Date: Tue, 21 Feb 2012 00:29:30 -0000\r
+\r
+Hi fellow notmuchrs,\r
+\r
+while going through the python bindings I recently came across the\r
+following note in the documentation for the Database.get_directory\r
+function [0]:\r
+\r
+~~~ snip ~~~\r
+Warning\r
+\r
+This call needs a writable database in Database.MODE.READ_WRITE\r
+mode. The underlying library will exit the program if this method is\r
+used on a read-only database!\r
+~~~ snap ~~~\r
+\r
+and indeed, the following program exits with an error:\r
+\r
+~~~ snip ~~~\r
+import os\r
+import notmuch\r
+\r
+db_path =3D os.path.expanduser('~/Maildir')\r
+\r
+with notmuch.Database(db_path, mode=3Dnotmuch.Database.MODE.READ_ONLY) as d=\r
+b:\r
+    db.get_directory('')\r
+~~~ snap ~~~\r
+\r
+% python temp/get_directory.py\r
+Internal error: Failure to ensure database is writable (lib/directory.cc:10=\r
+0).\r
+\r
+The line mentioned in the error message reads:\r
+\r
+    if (notmuch->mode =3D=3D NOTMUCH_DATABASE_MODE_READ_ONLY)\r
+        INTERNAL_ERROR ("Failure to ensure database is writable");\r
+\r
+with\r
+\r
+/* There's no point in continuing when we've detected that we've done\r
+ * something wrong internally (as opposed to the user passing in a\r
+ * bogus value).\r
+ *\r
+ * Note that __location__ comes from talloc.h.\r
+ */\r
+#define INTERNAL_ERROR(format, ...)                     \\r
+    _internal_error (format " (%s).\n",                 \\r
+                         ##__VA_ARGS__, __location__)\r
+\r
+and _internal_error calling exit(3).\r
+\r
+If creating a shared library is the preferred way to increase the\r
+startup time of the notmuch binary that's totally cool, but if\r
+libnotmuch is to be used as a library for arbitrary programs it is not\r
+acceptable to call exit(3).\r
+\r
+(And as mentioned before, neither is writing to any file descriptor\r
+unless it has been specifically requested by the caller.)\r
+\r
+Cheers,\r
+Justus\r
+\r
+0: http://notmuch.readthedocs.org/en/latest/index.html#notmuch.Database.get=\r
+_directory\r