api stability

[Robert Collins]

On Thu, 2006-01-05 at 16:38 +1100, Martin Pool wrote:
> 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.

Uhm, this is confusing to me: we had __foo for things that are not
allowed to be used by subclasses, and _foo for things that are allowed
to be used by subclasses. If you have a data field that is not allowed
to be relied upon by the subclass, call it __foo.

> 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 dont think so, that would force the exposure of class internals in
common subclass cases.

> 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.

Eh? I'm *positive* you misread something. That was not implied or stated
at all.

> > 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.

Sure - the point was that non BzrException subclasses would *never* be
raised as part of our api.

Rob

-- 
GPG key available at: <http://www.robertcollins.net/keys.txt>.
-------------- 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/9e7be29d/attachment.pgp