On 03:48 pm, gu...@python.org wrote:
On Tue, Nov 16, 2010 at 7:16 AM, Alexander Belopolsky
<alexander.belopol...@gmail.com> wrote:
What this thread has shown is that there is no consensus on what
public names are and what rules should be followed when changing names
that can be imported from a module. �I have opened an issue at
http://bugs.python.org/issue10434 to address this. �My vote is to
adopt the definition spelled out in the language reference, copy it to
the library manual and add some discussion of the deprecation
policies.
Hm. Apart from the specific semantics assigned by the language to
single and double leading (and trailing) underscores, I still think
this belongs in a style guide, not in the library manual. When reading
the library manual, one should always assume that undocumented
features are subject to change at any time.
I don't think it belongs only in PEP 8 (that's "a style guide" you're
referring to, correct?). It needs to be front and center. This is
information that every single user of the stdlib needs in order to use
the stdlib correctly.
Imagine trying to use a dictionary without knowing about alphabetical
ordering. Or driving a car without knowing what lane markers indicate.
No matter how many times we discuss this policy on this list (I know
it's come up here before), the majority of python users still won't
learn about it.
PEP 8 isn't nearly visible enough, either. Whatever the rule is, it
needs to be presented with the information itself. If the rule is that
things not documented in the library manual have no compatibility
guarantees, then all of the means of getting documentation *other* than
looking at the library manual need to indicate this somehow
(alternatively, the information shouldn't be duplicated, but I doubt
I'll convince anyone of that).
Here's a stupid proposal. What if the top of pydoc output said (for
stdlib modules only) "The library manual is the canonical reference.
Refer to it before using APIs you find in this documentation." Still
inconvenient, but inconvenient is better than secret/impossible.
Jean-Paul
_______________________________________________
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
