On 17/11/2010 14:19, Nick Coghlan wrote:
On Wed, Nov 17, 2010 at 11:45 PM, Fred Drake<fdr...@acm.org> wrote:
On Wed, Nov 17, 2010 at 8:30 AM, Nick Coghlan<ncogh...@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/
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
