api stability

[Martin Pool]

On Tue, 2005-12-20 at 13:56 +1100, Robert Collins wrote:
> On Mon, 2005-12-19 at 20:28 -0600, John Arbash Meinel wrote:

> 'symbol' : Is a public symbol.
> '_symbol' : Is a private symbol to whatever context it appears in. If
> that context is publicly extensible then its public [for extensions
> only].
> Specifically, _foo symbols in module scope are private.
>               _foo symbols in class scope where the class
>                    is named like 'Foo' are public for child classes.
>               _foo symbols in class scope where the class is named 
>                    like '_Foo' are private because the class is 
>                    private and extension is not publically supported.

This is OK but I'm not totally happy with it: there is a bit of a gap
between __name (which Python tries to hide from all subclasses), and
allowing things to be used by subclasses.  In particular this implies
that data fields can be relied upon by subclasses, which is going too
far.

Perhaps we should change this to just say that only 'symbol' names can
are public, even when subclassing.  So classes that are intended to be
subclassed in particular ways need to expose with unprefixed names the
symbols needed to define and implement the subclass.

I would think only some particular classes need to be subclassed, and
it's better to think about which behaviours should be guaranteed, rather
than potentially promising that none of the internal behaviour will
change.

> Exceptions
> ----------
> Any exception that is raised by a public symbol in bzrlib and is a plain
> python exception is a private symbol. 
> 
> All other exceptions are classified as per the symbol classification
> guidelines above.

I agree, but it's also important for callers to know what exceptions
they can expect to be raised.  In particular, if they want to detect a
particular error case, what exception can they expect will be raised to
indicate it.  (Secondarily, if defining a subclass, what exception
should they raise when the subclass hits an error?)

There are three ways they might expect to know this

 0 - because we explicitly say "when foo occurs, raises FooException"
 1 - by looking at the implementation
 2 - by trying it and observing what happens

I don't think any behaviour implied by 1 or 2 will necessarily be
supported in the long term as the code evolves.  Therefore I think
callers can only rely on particular exceptions being thrown if the
documentation says that will happen.  And similarly when implementing
subclasses.

It may seem like this will cause a lot of documentation of exceptions,
but remember that it is a rare (exceptional!) case to want to catch a
particular exception.  The documentation could be done at a class,
module or global level, rather than on every single method/function that
could raise it.

As you say there are two main types: plain Python exceptions, and
exceptions that descend from BzrException.  (I don't think they should
need to be named Bzr*).  In general we should be raising BzrException,
as in the HACKING guide.  The contents of the BzrException are subject
to the visibility rules above.

-- 
Martin

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20060105/1423277c/attachment.pgp