[Python-Dev] Breaking undocumented API
fuzzyman at voidspace.org.uk
Wed Nov 17 15:25:01 CET 2010
On 17/11/2010 14:19, Nick Coghlan wrote:
> On Wed, Nov 17, 2010 at 11:45 PM, Fred Drake<fdrake at acm.org> wrote:
>> On Wed, Nov 17, 2010 at 8:30 AM, Nick Coghlan<ncoghlan at gmail.com> wrote:
>>> The library documentation is *not* the right place for quibbling about
>>> what constitutes a public API when using other means than the library
>>> documentation to find APIs to call.
>> Quibbling can happen on the mailing list, where it can be ignored by
>> those who aren't interested.
>> But the documentation is the right place to document what we come up
>> with for the standard library. I expect what the tools do will inform
>> any decisions, and the tools (those in the stdlib) will henceforth be
>> maintained with that in mind.
>> I *am* suggesting that the scope of this be restricted to what's
>> appropriate for the standard library, rather than a general
>> recommendation for others. Third-party projects are free to use what
>> we come up with, or provide their own policies. That's theirs to
>> decide, and I see no value in interfering with that.
> 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.
> 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"
We're *also* discussing codifying the naming conventions (or using
__all__) within the standard library, so it isn't just about
deprecations (which is why I think PEP 8 rather than PEP 5). This is so
that in the future if a name looks public users can have more confidence
that it actually is...
Obviously what to do about modules that don't follow these rules
currently is a big part of it (and how the discussion started).
All the best,
> 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
> The policy we're aiming to clarify here is what we should do when we
> come across standard library APIs that land in the grey area, with
> there being two appropriate ways to deal with them:
> 1. Document them and make them officially public
> 2. Deprecate the public names and make them officially private (with
> the public names later removed in accordance with normal deprecation
> The actual approach taken will vary on a case-by-case basis (and is a
> little trickier in the case of module level globals, since those can't
> be deprecated properly), but is always aimed at bringing the standard
> library more into line with the official position (i.e. APIs are
> either public-and-documented or private).
> 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
More information about the Python-Dev