[ZODB-Dev] API question

[Alex Clark]

On 2013-01-14 20:33:25 +0000, Marius Gedminas said:

> On Mon, Jan 14, 2013 at 01:32:07PM -0500, Tres Seaver wrote:
>> While working on preparation for a Py3k port, I've stumbled across a
>> fundamental issue with how ZODB structures its API.  Do we intend that
>> client code do the following::
>> 
>> from ZDOB import DB, FileStorage
>> db = DB(FileStorage('/path/to/Data.fs'))
> 
> ZODB.FileStorage is a module, you can't call it.
> 
> ZODB.DB, much to my surprise, refers to the ZODB.DB.DB class.  A
> backwards compatibility thing maybe?
> 
>> or use the module as a facade ::
>> 
>> import ZODB
>> db = ZODB.DB(ZODB.FileStorage.FileStorage('/path/to/Data.fs'))
> 
> This rings warning bells in my mind: if you're using the
> ZODB.FileStorage module, you should import it directly:
> 
>     import ZODB
>     import ZODB.FileStorage
>     db = ZODB.DB(ZODB.FileStorage.FileStorage('/path/to/Data.fs'))
> 
>> I would actually prefer that clients explicitly import the intermediate
>> modules::
>> 
>> from ZDOB import DB, FileStorage
>> db = DB.DB(FileStorage.FileStorage('/path/to/Data.fs'))
> 
> (I'm not a fan of this style, but never mind that.)
> 
>> or even better::
>> 
>> from ZDOB.DB import DB
>> # This one can even be ambiguous now
>> from ZODB.FileStorage import FileStorage
>> db = DB(FileStorage('/path/to/Data.fs'))
> 
> This is what I usually do.
> 
> 
> I don't get the ambiguous comment.  ZODB.DB is (currently) always the
> class[1].  ZODB.FileStorage is always the module.
> 
>   [1] I think (currently) the only way to refer to the ZODB.DB module is
>   to use sys.modules['ZODB.DB']:
> 
>     >>> import ZODB
>     >>> ZODB.DB
>     <class 'ZODB.DB.DB'>
> 
>     >>> from ZODB import DB
>     >>> DB
>     <class 'ZODB.DB.DB'>
> 
>     >>> import ZODB.DB
>     >>> ZODB.DB
>     <class 'ZODB.DB.DB'>
> 
>> The driver for the question is getting the tests to pass under both
>> 'nosetests' and 'setup.py test', where the order of module imports etc.
>> can make the ambiguous cases problematic.  It would be a good time to do
>> whatever BBB stuff we need to (I would guess figuring out how to emit
>> deprecation warnings for whichever variants) before releasing 4.0.0.
> 
> Can you demonstrate the ambiguity?  As I've shown before, I was unable
> to find it, at least with Python 2.x.


I've just skimmed this and can add that when experimenting with ZODB, I 
found that whatever I was inclined to do while experimenting (i.e. 
without documentation) was never what the documentation recommended. In 
other words, I found the API awkward (in some way that I can't recall 
at the moment).

The best non-awkward, documented way I found was (from an old IBM article):

- https://raw.github.com/aclark4life/zodb_test/master/zodb_test.py

FWIW






> 
> Marius Gedminas


-- 
Alex Clark · https://www.gittip.com/aclark4life/