[Python-Dev] Breaking undocumented API

[Alexander Belopolsky]

On Thu, Nov 11, 2010 at 7:01 AM, Michael Foord
<fuzzyman at voidspace.org.uk> wrote:
..
>> I don't understand why everyone seem to have accepted Michael's
>> premise that "we don't have a clearly stated policy for what defines
>> the public API of standard library modules."  We do have such a policy
>> and it is well known (while the location in the reference manual may
>> not be):
>
> Ha. 14 paragraphs into the grammar reference on the import statement is
> perhaps not where developers would go to look for Python standard library
> development policy..

Very true.  To make it slightly more visible, any objections to the
following patch? (It adds "public names (in module globals)" linking
to that 14-th paragraph in the index.)

Index: Doc/reference/simple_stmts.rst
===================================================================
--- Doc/reference/simple_stmts.rst	(revision 86409)
+++ Doc/reference/simple_stmts.rst	(working copy)
@@ -794,6 +794,7 @@
 namespace of the :keyword:`import` statement..

 .. index:: single: __all__ (optional module attribute)
+.. index:: public names (in module globals)

 The *public names* defined by a module are determined by checking the module's
 namespace for a variable named ``__all__``; if defined, it must be a
sequence of