[ZODB-Dev] standalone and the docs...

[Kendall Clark]

All,

I hate to be a documentation-carper, but the mismatches between the
docs and the code are super annoying.

First, AMK's docs (well, the docs that come with Standalone, which
seem to be unchanged from the ones that AMK wrote for his version of
ZODB) suggest "import BTree" and "b=BTree.BTree()", which of course is
now superseded by "import BTrees" and "b=BTrees.OOBTree()" -- not a
big deal code-wise, but if you're trying to use AMK's docs, it's
pretty frustrating. Despite the "cleverness" of the little *BTree
prefixing scheme, if you don't already know the code, IO, OO, OI,
etc. is *super* opaque. I suspect relative newbies to Python might
stumble around on that one for some time. (I would have preferred a
BTreeFactory that took a sole string argument, one of "oo", "io",
etc. Or even BTreeFactory(key="int", value="object")... That seems far
less opaque. Just my preference, I suppose.)

Second, I still haven't quite figured out how to get a
PersistentList... I see the code in Standalone for one; I even see
ZODB/__init__.py machinery for it, but what's the magic invocation to
actually get at it?

That, too, seems out of phase with the docs.

These aren't huge problems, but they can be frustrating. And they
don't *seem* to be the kind of thing that takes a long time to fix,
prose-wise. There are promises fix up the docs in the zodb-dev
archives going back to the summer of 2001, after all.

If Standalone-ZODB weren't marked "1.0" -- which seems to imply that
it's ready for use by ordinary Pythoneers -- I wouldn't even complain
about this. As things stand, however, the out-of-box experience
(including mystery segfault on a Linux box, about which I sent bug
reports and stack traces to this list some weeks ago, and still
haven't heard back anything -- if I need to file a real bug report in
some bug tracker, please, by all means, someone let me know and I
will) of Standalone for me has not been up the usual level of quality
I've come to expect from Zope and from Python.

Just another data point.

Best,
Kendall Clark