[ZODB-Dev] n-way join algoritms

[Tim Peters]

[Steve Alexander, on the btrees interfaces.py]
> It is the first place I turn to when I need to do something with
> BTrees after not having used them for a while. I find it very useful
> and concise documentation.

Let's leave it be, then.

> ...
> How is a user of BTrees to hear about the existence of multiunion if
> its existence is not revealed in some API documentation.

I don't know.  In PythonLand we write reference manuals, and I understand
that model.

> In Zope 3, modules containing interfaces form our API documentation.

So it seems <wink>.

> ...
> Fine. I'd be happy with:
>
>    class IIntegerTreeModule(IBTreeModule):
>        "This interface is provided by the IIBTree and IOBTree
> modules."
>
>        def multiunion(list args):
>            "Explain what and why and whatever"

I'll add something like that, then, but only in Zope3/ZODB4.  There are
currently variations of the BTree code on 6 active branches, and I'm
spending too much of my life trying to update everything in half a dozen
diverging places.

BTW, it's hard to explain the truth about how to use multiunion, because it
accepts a sequence of objects each of which is convertible to an integer set
using the internal BTrees set iteration protocol.  That's actually true of
lots of arguments to lots of BTree methods.  The concept isn't covered by
the current interfaces, though -- which in one sense just begs your original
question ("how do you find out what isn't documented?"; my question is more
"how do you document something when there isn't a manual to hold any docs?"
<0.9 wink>).

> The zope.interface package provides the means to say that a module
> provides an interface, so you could use that if you like.

I don't know exactly what to do so am inclinced to skip this part.  Note
that the btree code is supposed to be usable independent of Zope.  As is,
Jeremy already had to comment out the classImplements() calls in the btrees
interfaces.py module because of intractable circular import problems.

> ...
> Ok. What about refactoring it so that its scope is BTree modules and
> classes as implemented, and nothing else? No pretensions to abstract
> generality.

Na, it sounds more like busy work than something useful, especially since
you already find the interface file useful as-is.