[ZODB-Dev] n-way join algoritms

[Steve Alexander]

>>Please can this be documented in the interfaces.py file of BTrees.
> 
> Maybe.  I usually think of that file as dead weight, so need some help
> understanding what would be useful there.

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.


>  As is, it seems to pretend to a
> lot of generality that doesn't exist, and defines any number of interfaces
> that aren't actually referenced anywhere (e.g., IReadSequence is never
> referenced in code, IIMerge is never referenced anywhere (not even in
> comments), and IMerge is referenced only as a base class for the
> unreferenced IIMerge).

I have no objections to it being made more concise.


> The multiunion business doesn't fit into any of the current interfaces
> (whether or not currently used):  it's supplied only by the btree flavors
> with integer keys, and that distinction isn't currently made anywhere.

How is a user of BTrees to hear about the existence of multiunion if its 
existence is not revealed in some API documentation. In Zope 3, modules 
containing interfaces form our API documentation.


> Now if I could just say "multiunion is supplied by IIBTree and IOBTree, and
> that's it", cool.

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"

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 seem to have the right kind of brain to pretend
> the world is 100x more general than that.

Ok. I think my suggestion is pretty specific, though.


> For example, would it be helpful
> to make up an interface meaning "like IMerge, but restricted to integer
> keys", and then make up an interface derived from that with a single
> multiunion method?  If so, I suppose it could be done.  OTOH, when I was
> first learning the btree package, I found its interfaces.py file to be more
> confusing than illuminating.

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

If you agree to such a thing, and Jim doesn't say "no", I'll do it.

--
Steve Alexander