[issue10434] Document the rules for "public names"

[Alexander Belopolsky]

New submission from Alexander Belopolsky <belopolsky at users.sourceforge.net>:

As discussed in "Breaking undocumented API" thread [1] on python-dev,  a definition of "public names" is buried deep in the language reference manual:

"""
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).
"""  [2]

It has been argued that this is not the authoritative definition and alternatives have been suggested such as "any name that does not begin with an underscore except imported modules."
mportant for the users and developers of cpython and other python implementations to know what names they can rely upon to stay defined between releases, the rules for "public names" should be documented.

I agree that the library manual is a more appropriate place for such documentation.  The definition should include the naming conventions and the set of promises that Python makes about public name availability in the future releases.


[1] http://mail.python.org/pipermail/python-dev/2010-November/105490.html
[2] http://docs.python.org/reference/simple_stmts.html

----------
assignee: docs at python
components: Documentation
messages: 121297
nosy: belopolsky, docs at python
priority: normal
severity: normal
stage: needs patch
status: open
title: Document the rules for "public names"
versions: Python 3.2

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue10434>
_______________________________________