[Python-Dev] Breaking undocumented API

[Alexander Belopolsky]

On Wed, Nov 17, 2010 at 9:19 AM, Nick Coghlan <ncoghlan at gmail.com> wrote:
..
> The standard library documentation should say that the public API is
> what the documentation says it is. Officially, anyone going outside
> those documented APIs should not be surprised if things get removed or
> changed arbitrarily without warning. That has long been the python-dev
> policy and I, for one, don't think it should change.
>
+1

That's another reason why it is appropriate to document this in both
Library Reference and the Developers Guide (whatever it is).  In the
Library Reference we can say point-blank: "This is the authoritative
documentation of what Python Library provides.  Anything not mentioned
here is subject to change between releases without notice."  In the
Developers Guide, guide, however we can take a more nuanced approach
that would start with a general policy that changing existing APIs
public or not is costly and should not be done without significant
offsetting benefit.  More on this below.

> What we're talking about in this thread is what to do in the grey area
> of APIs which are not included in the official documentation, but also
> don't have names starting with an underscore so they "look public"
> when reading the source code or exploring the API in the interactive
> interpreter. It *may* be appropriate for the standard library
> documentation to acknowledge that this grey area exists (I'm not yet
> convinced on that point), but it definitely should *not* be
> encouraging anyone to rely on it or on our policies for dealing with
> it.
>

Users will venture into grey area regardless of whether its existence
is acknowledged or not.  Developers Guide should take this into
consideration, but there is no need to encourage this practice in the
Library Reference.   In the Developers Guide, we can list a set of
factors that need to be considered when changing or removing an
undocumented API.  For example:

1. Does it start with an underscore?
2. Is __all__ defined for the module? Id so, is the name in __all__?
3. Is API name well chosen for what it does?
4. How old is the module?  Was is written before modern policies  have
been adopted?
5. Is API used in the standard library outside of the module?
6. Is API broken?  Can it be fixed?  (If it was broken in several
releases and nobody complained - it is ok to remove.)
7. Is API used?  General google search or google code search can give
an insight.

The decision to remove an API should be always done on a case by case
basis.  Purely style compliance changes such as let's add __all__ and
rename all names not in all by prepending an underscore should always
add old names back as deprecated aliases.  (Breaking from xyz import *
by adding __all__ to xyz is probably ok because code using  from xyz
import * may be broken by any addition to xyz and users have been
warned.)

..
> So the official policy from a language *user* point of view would
> remain unchanged (i.e. if it isn't documented, you're on your own). As
> a *pragmatic* policy, however, we would explicitly acknowledge that
> developers may inadvertently use an undocumented API without realising
> that it isn't technically public, and hence apply the normal
> deprecation process even though the official policy says we don't have
> to.
+1