From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2 ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms11 with LMTPS id UMERGVqw1l59XAAA0tVLHw (envelope-from ) for ; Tue, 02 Jun 2020 20:02:34 +0000 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2 with LMTPS id CC/wFFqw1l4gZAAAB5/wlQ (envelope-from ) for ; Tue, 02 Jun 2020 20:02:34 +0000 Received: from arlo.cworth.org (arlo.cworth.org [50.126.95.6]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) server-signature RSA-PSS (4096 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id D03AB940538 for ; Tue, 2 Jun 2020 20:02:30 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by arlo.cworth.org (Postfix) with ESMTP id 04F4E6DE0F5A; Tue, 2 Jun 2020 13:02:27 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at cworth.org Received: from arlo.cworth.org ([127.0.0.1]) by localhost (arlo.cworth.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id KzReMslnpTVX; Tue, 2 Jun 2020 13:02:26 -0700 (PDT) Received: from arlo.cworth.org (localhost [IPv6:::1]) by arlo.cworth.org (Postfix) with ESMTP id B5EBF6DE0F4C; Tue, 2 Jun 2020 13:02:22 -0700 (PDT) Received: from localhost (localhost [127.0.0.1]) by arlo.cworth.org (Postfix) with ESMTP id 9852D6DE0F4C for ; Tue, 2 Jun 2020 13:02:20 -0700 (PDT) X-Virus-Scanned: Debian amavisd-new at cworth.org Received: from arlo.cworth.org ([127.0.0.1]) by localhost (arlo.cworth.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id dKEw9n_zbGje for ; Tue, 2 Jun 2020 13:02:19 -0700 (PDT) Received: from mail-ej1-f48.google.com (mail-ej1-f48.google.com [209.85.218.48]) by arlo.cworth.org (Postfix) with ESMTPS id 1B8AA6DE0F42 for ; Tue, 2 Jun 2020 13:02:19 -0700 (PDT) Received: by mail-ej1-f48.google.com with SMTP id mb16so14028089ejb.4 for ; Tue, 02 Jun 2020 13:02:19 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:subject:in-reply-to:references:date:message-id :mime-version; bh=0Fw7v+anWn66vq7HfKgWDRgqtdzrn9X9PF3AVub9P1E=; b=e/tMinfLi/8ZsKWAZwyFAS57W/RK0kyztS28e6UxE3NQiYLfGALFqhHGXmB5aVvYpo ejANyH77+Ey0stq6k7EQzNCqgckEdzqy3Rhy/yACXK159r7YH1M2OMYgB9JEYHUXjCeu N2B+9j8Asn0sgcYQQdPLxJehbI3DPwi4OOuj22/zIkI7sXuCZ0stk08kbRDx2cdLru69 k3tiv9R83RI+8SWJMuYPrrmd69qbueL0hrQqaRwRyZ/+YFe3xKQxmvrz+JszmVhckYYp 5CbKwli1uXP+RTqEpVHXXriZ+JXhQ7wYYek5aHRDMM5xptQbuPEayv1mKT75gk+MQH9j w+jg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:subject:in-reply-to:references :date:message-id:mime-version; bh=0Fw7v+anWn66vq7HfKgWDRgqtdzrn9X9PF3AVub9P1E=; b=HQdIWCXl/tzFqGLEK9NYU/30OHCluMR1fhGNBIkf+sudcP/J7pGA3YtDBMAEvr25vw T42RS5t/BkFCV6VgKasjzzmvE57e4nvq1G94JN+osXW6LbB5Nwb+2roVy4t4Co+biEjG i8RuTNvG26iHpQIe5V3goahemEv6XP1lj3Iyuz62N/epzYVkx+MqKYjXco5w545AbvUQ bkdRGGvSMcr97t82PU5OuGcsDJf9yh42bSuYMVc4OFb3Y+E3BANluweUJ+qBUdbhfLsQ bIvfpvB+Jx7A1OVkC+p1E/aKgBAxEih2krWlyRdwAvlssj8ooAYLyrArpAW7TGUcIw01 Slyw== X-Gm-Message-State: AOAM530A9Exv3leqCti5BVIqvl9IG6pSUMCshSKvRq8aNzFAFBm3NJrW 0fVC1Lsh88wwXetduNR0ndo= X-Google-Smtp-Source: ABdhPJzS6wf0MDcnofHDi+K9+eufMQJ/G4vU7IZxkyMepUXsE9nTzVcAD5Eq7r8MxKYsYNwSNMsQZA== X-Received: by 2002:a17:906:d153:: with SMTP id br19mr2692871ejb.201.1591128136209; Tue, 02 Jun 2020 13:02:16 -0700 (PDT) Received: from powell.devork.be (2a02-8388-8480-1180-4c18-fc69-8d8c-22b5.cable.dynamic.v6.surfer.at. [2a02:8388:8480:1180:4c18:fc69:8d8c:22b5]) by smtp.gmail.com with ESMTPSA id a62sm1950545edf.38.2020.06.02.13.02.14 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 02 Jun 2020 13:02:15 -0700 (PDT) Received: (nullmailer pid 97835 invoked by uid 1000); Tue, 02 Jun 2020 20:02:14 -0000 From: Floris Bruynooghe To: Anton Khirnov , Notmuch Mail Subject: Re: status of the new python bindings In-Reply-To: <158885985981.5773.4257129906401430063@lain.red.khirnov.net> References: <158885985981.5773.4257129906401430063@lain.red.khirnov.net> Date: Tue, 02 Jun 2020 22:02:14 +0200 Message-ID: <87v9k96xtl.fsf@powell.devork.be> MIME-Version: 1.0 X-BeenThere: notmuch@notmuchmail.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Use and development of the notmuch mail system." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: notmuch-bounces@notmuchmail.org Sender: "notmuch" X-Scanner: scn0 Authentication-Results: aspmx1.migadu.com; dkim=fail (body hash did not verify) header.d=gmail.com header.s=20161025 header.b=e/tMinfL; dmarc=none; spf=pass (aspmx1.migadu.com: domain of notmuch-bounces@notmuchmail.org designates 50.126.95.6 as permitted sender) smtp.mailfrom=notmuch-bounces@notmuchmail.org X-Spam-Score: -0.01 X-TUID: M36DjMm0cq+2 Hi Anton, Great that you're looking at this API! My apologies for the late response, this slipped by me probably as I was bulk marking things as read when I came back from a few weeks away. On Thu 07 May 2020 at 15:57 +0200, Anton Khirnov wrote: > 1) What is the logic behind choosing whether something is exported as > a property or as a method? E.g. Database.needs_upgrade is a property, > while Database.revision() is a method. In my own python code, I tend to > use @property for things that are "cheap" - i.e. do not involve > (significant) IO or heavy computation and methods for those that do. But > both of the above attributes involve library calls, presumably(?) of > similar complexity. Would be nice if this was consistent. Choosing when something should be a property is sometimes indeed tricky and in general I agree you're right to expect property calls to be not too expensive. But I wouldn't go so far to consider every call into libnotmuch as expensive. I think there is also an element of how static something is. Usually I expect properties to behave more like attributes, that is after all the point of them, and thus I don't expect them to change often without explicitly manipulating them. So that could justifies why I choose Database.version as a property while Database.revision() is a method. The revision changes all the time as a side-effect of other things. I think it also justifies generally why tags are exposed as properties. Database.needs_upgrade is indeed a more questionable choice, especially given its naming which is more of a question being asked and thus probably more suitable as a method. It does change rarely, but does so by interaction with another method - Database.upgrade(). So I would agree that this perhaps wasn't the best choice and maybe that was better as a method. > 2) Atomic transactions are now exported as a context manager, which is > nice and convenient for the usual use cases, but AFAIU does not have the > same power. E.g. my tagging script does the tagging as a single atomic > transaction and has a "dry-run" mode in which it omits the end_atomic() > call, which is documented to throw away all the changes. This seems to > not be possible with the new bindings. > Would it be okay to add bindings for explicitly calling > start/end_atomic()? Or is my approach considered invalid? This is indeed a good usecase that I overlooked, I stopped reading at the part where is says being and end atomic must always be used in pairs... But yes, we should add support for this too. What would you think of a .abort() on the context manager instead of directly exposing the start/end? E.g.: db = notmuch2.Database() with db.atomic() as txn: # do stuff txn.abort() However if I read the docs correctly the transaction only actually is aborted once the database is closed? But when I try this: with db.atomic(): # do stuff db.close() I discover that after calling .close() it's very easy to segfault by making other calls, e.g. the above currently segfaults. I thought this wasn't so bad but perhaps .close() should immediately destroy the database too. This would again disallow some funky behaviour that the raw C API allows I guess where some objects might still be valid to use. But this is really hard to get right I think and I'd prefer to vote on the side of safety in the Python bindings. Still, it could be reasonable to make AtomicContext.abort() also close the database and then make sure it doesn't call notmuch_database_end_atomic() on exit. I tried this locally and it seems reasonable. What do you think? Lastly you can do this today by calling the C API directly: db = notmuch2.Database() notmuch2._capi.notmuch_database_being_atomic(db._db_p) Yes, that uses a lot of internal stuff but it's also pretty advanced usage. I'm only suggesting you this to maybe unblock you in the short term. > 3) There seem to be no bindings for notmuch_database_set_config(). There are still bits of the API missing indeed. Would be great to add them but would be even better to have someone who needs it to validate the API. There were recently some good patches posted to expose the config stuff, would be good to see that merged indeed. > 4) The setup for building the documentation seems to be missing. Hmm, yes. The docstrings are written to work with sphinx autodoc but a doc directory with sphinx configured never got added. Perhaps we should do this so that people can at least build docs locally. > Anything else of note that remains to be implemented? Probably. Thanks for caring! Cheers, Floris