[Python-Dev] Breaking undocumented API

[Alexander Belopolsky]

On Wed, Nov 10, 2010 at 6:10 PM, Ron Adam <rrr at ronadam.com> wrote:
..
>> On Nov 10, 2010, at 5:47 AM, Michael Foord wrote:
>>>
>>> So it is obvious that we don't have a clearly stated policy for what
>>> defines the public API of standard library modules.
>>>
>>> How about making this explicit (either pep 8 or our developer docs):
>> ..
> The way I read Guido's email is that it is a situation dependent judgment
> call for those cases that aren't clear.
>
> I think what Micheal is trying to say is for us to agree on some things so
> we can go forward with a little more clarity.

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):

"""
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 strings which are names defined or imported by that
module. The names given in __all__ are all considered public and are
required to exist. If __all__ is not defined, the set of public names
includes all names found in the module’s namespace which do not begin
with an underscore character ('_'). __all__ should contain the entire
public API. It is intended to avoid accidentally exporting items that
are not part of the API (such as library modules which were imported
and used within the module).
"""  -- <http://docs.python.org/reference/simple_stmts.html>

The question that I had when I started this thread was not about a
definition of "public API."  It was about a policy with respect to
modules that precede the introduction of __all__ and the modern
definition of public names.  (See r18692 "Two changes to
from...import", and r23920 ' adding a definition of "public names"'.)

Is it OK to add __all__ to such modules that does not include all
names not starting with an underscore?  Is it OK to then remove names
that clearly were not intended to be public?

Case in point: trace.rx_blank.  See also <http://bugs.python.org/issue10371>.