[Python-Dev] Breaking undocumented API

[Michael Foord]

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,

Michael

> 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.
>
> 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
> procedures)
>
> 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
> to.
>
> Regards,
> Nick.
>


-- 
http://www.voidspace.org.uk/