New submission from Alexander Belopolsky <[email protected]>:
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: d...@python
components: Documentation
messages: 121297
nosy: belopolsky, d...@python
priority: normal
severity: normal
stage: needs patch
status: open
title: Document the rules for "public names"
versions: Python 3.2
_______________________________________
Python tracker <[email protected]>
<http://bugs.python.org/issue10434>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
