[Python-Dev] Breaking undocumented API (original) (raw)

Nick Coghlan ncoghlan at gmail.com
Wed Nov 17 15:19:39 CET 2010

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

-- Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia

More information about the Python-Dev mailing list