[ZODB-Dev] Handling more databases with zeo

Tim Peters tim at zope.com
Wed Jun 29 16:46:15 EDT 2005

[Chris McDonough]
> I also use this feature but I would be happy to stop using it if it made
> the code materially simpler to maintain.

I don't hate the feature, but I hate that it's undocumented, and I hate that
it's untested.  I particularly hate that the ClientStorage constructor has
17 arguments now, and that the docs for its `name` and `storage` arguments
are incomprehensible when taken together:

        storage -- The storage name, defaulting to '1'.  The name must
            match one of the storage names supported by the server(s)
            specified by the addr argument.  The storage name is
            displayed in the Zope control panel.

        name -- The storage name, defaulting to ''.  If this is false,
            str(addr) is used as the storage name.

WTF?  I had no idea what either of these were for until I peed away an hour
trying to guess at a useful answer to Lukas's question.  I'm still not sure
what _possible_ values `storage` can have, although noted that runzeo.py's
handle_filename() generates names "1", "2", "3", ..., without possibility to
change that.  And I'm still not sure what `name` is for.  Well, OK, it's the
storage name -- but it's not the `storage` storage name.  You can tell the
difference because one of them may _be_ str(addr), but the other must be a
name supported _by_ addr <wink>.

IME, ZODB maintenance isn't injured nearly so much by feature creep as it is
by that I so often end up adrift in a sea of undocumented assumptions, or
code crucial to supplying an undocumented behavior I didn't even know
existed.  It's docs and testing that have gotten the short end of the stick
here.  There appears to be very little code supporting the "1" "2" "3"
gimmick, and it all appears quite simple, so I don't have a problem with
that.  The problems are more that, in the absence of docs, it takes hours of
staring at the code trying to guess what this feature might be; and, in the
absence of tests, who can say whether it "still works"?

The end result is that it's more likely for a feature like this to get
ripped out than rehabilitated (less time, less work, less hassle, leaves
remaining code clearer and cleaner -- e.g., just getting rid of the
`storage` docs above would eliminate the confusion of having two arguments
each claiming to be "the storage name").  That's why I said before that if
someone wants this, the best way to ensure it sticks around is to contribute
docs and tests for it.

More information about the ZODB-Dev mailing list