[Zope-dev] Interfaces vs ZCA concepts

[Tres Seaver]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Martijn Faassen wrote:
> Hey,
> 
> Tres Seaver wrote:
> [let's not suddenly change the behavior of __call__ for backwards 
> compatibility reasons]
> 
>> If so, that code is already broken:  it depends on an undocumented
>> implementation detail (of a non-API method).  The patch makes the
>> __call__ method an API, and documents the (new) exception type. Anybody
>> whose code breaks when this happens can hold off upgrading
>> zope.interface until they fix that usage.
> 
> Documentation status aside, are you really maintaining that a feature 
> that people have been using for many years is not actually part of the 
> API? So that we can change willy-nilly without any concern for backwards 
> compatibility?

I didn't say "without concern" -- I suggested that we bump the minor
version to indicate that this was something of an API change.  If you
would rather raise a compatibliity error (blending the two types
together), I could live with that.  I would still rather document
LookupError, as it is the *correct* exception type:  TypeError says "you
violated the contract by passing me a bad argument", rather than "I
couldn't find what you were looking for."  Note that CLE already derives
from LookupError, which reinforces the point.

> If you do insist on taking that position, then please note that while 
> API may not be documented in zope.interface it is certainly documented 
> in other places. The __call__ behavior and the TypeError behavior for 
> instance is documented in at least one published book (see bottom of the 
> page):
> 
> http://docs.zope.org/zope3/Book/ifaceschema/interface/show.html
> 
> Documented for years.

That example is a poor bit of documentation, as well as a bad test
(depends on the repr of an exception).  There is way too much "example
cruft" and way too little prose there to help anybody figure out how to
use interfaces by calling them.  In particular, the role of the adapter
hook is completely obscured.

If __call__ is an API, why is it not documented where the rest of the
API for Interface is specified?


Tres.
- --
===================================================================
Tres Seaver          +1 540-429-0999          tseaver at palladion.com
Palladion Software   "Excellence by Design"    http://palladion.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAksr/lUACgkQ+gerLs4ltQ620ACgifVngQZiIOhHNtHsDLtF8i0l
dVYAoNhlXxcfJA4eMiyFIFo7nNHKiUQ+
=FCFu
-----END PGP SIGNATURE-----