[ZODB-Dev] API question

2013-01-14 Thread Tres Seaver 
-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1

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'))

or use the module as a facade ::

  import ZODB
  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'))

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'))

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.



Tres.
- -- 
===
Tres Seaver  +1 540-429-0999  tsea...@palladion.com
Palladion Software   Excellence by Designhttp://palladion.com
-BEGIN PGP SIGNATURE-
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with undefined - http://www.enigmail.net/

iEYEARECAAYFAlD0TycACgkQ+gerLs4ltQ4AgACg3MCYrEOga5KF8goWyu2OxjWe
H7QAoLEyHTShzBc9ZkMENWbG+hqzrpTg
=nBoy
-END PGP SIGNATURE-

___
For more information about ZODB, see http://zodb.org/

ZODB-Dev mailing list  -  ZODB-Dev@zope.org
https://mail.zope.org/mailman/listinfo/zodb-dev

Re: [ZODB-Dev] API question

2013-01-14 Thread Marius Gedminas 
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.

Marius Gedminas
-- 
We don't really understand it, so we'll give it to the programmers.


signature.asc
Description: Digital signature
___
For more information about ZODB, see http://zodb.org/

ZODB-Dev mailing list  -  ZODB-Dev@zope.org
https://mail.zope.org/mailman/listinfo/zodb-dev

Re: [ZODB-Dev] API question

2013-01-14 Thread Tres Seaver 
-BEGIN PGP SIGNED MESSAGE-
Hash: SHA1

On 01/14/2013 03:33 PM, Marius Gedminas wrote:
 Can you demonstrate the ambiguity?  As I've shown before, I was
 unable to find it, at least with Python 2.x.

On the filesystem:

 $ find src/ZODB/FileStorage/ -name *.py
 src/ZODB/FileStorage/fspack.py
 src/ZODB/FileStorage/__init__.py
 src/ZODB/FileStorage/fsdump.py
 src/ZODB/FileStorage/fsoids.py
 src/ZODB/FileStorage/format.py
 src/ZODB/FileStorage/interfaces.py
 src/ZODB/FileStorage/tests.py
 src/ZODB/FileStorage/FileStorage.py

So, 'ZODB.FileStorage.FilesStorage' could logically be either the
'Filestorage' module inside the 'ZODB.FileStorage' package, or else the
same-named class.  As with ZODB.DB, getting to the actual module is
tricky, because both thses imports give you the class::

 from ZODB.FileStorage import FileStorage

and::

 From ZODB.FileStorage.FileStorage import FileStorage

I'm tempted to rename the 'DB.py' module 'db.py', and jam in a BBB entry
in sys.modules for 'ZODB.DB';  likewise, I am tempted to rename the
'FileStorage.py' package 'filestorage', its same-named module
'_filestorage.py', and jam in BBB entries for the old names.

Those renames would make the preferred API:

   from ZODB import DB # convenience alias for the class
   from ZODB import db # the moodule
   from ZODB.db import DB # my preferred speling
   from ZDOB.filestorage imoprt FileStorage # conv. alias for class
   from ZODB import filestorage # the package
   from ZODB.filestorage import FileStorage # my preferred speling
   from ZODB.filestorage import _filestorage # if needed

For extra bonus fun, we could rename 'ZODB' to 'zodb' :)



Tres.
- -- 
===
Tres Seaver  +1 540-429-0999  tsea...@palladion.com
Palladion Software   Excellence by Designhttp://palladion.com
-BEGIN PGP SIGNATURE-
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with undefined - http://www.enigmail.net/

iEYEARECAAYFAlD0oOgACgkQ+gerLs4ltQ4LOwCgu3VSRklLjFMdkuWLkUNV4h2S
m/MAoKMI+ZrTqFUnXkgGNSw7Gq2yYN0V
=67De
-END PGP SIGNATURE-

___
For more information about ZODB, see http://zodb.org/

ZODB-Dev mailing list  -  ZODB-Dev@zope.org
https://mail.zope.org/mailman/listinfo/zodb-dev