[docs] [issue10434] Document the rules for "public names"

[Alexander Belopolsky]

Alexander Belopolsky <belopolsky at users.sourceforge.net> added the comment:

Michael Foord suggested adding the following to developer documentation such as PEP 8. [1] I am not sure PEP 8 is the right place for it.  In my opinion, PEP 8 is mostly about stylistic choices that don't have a major impact on the users.  In other words, unless you are developing python itself, you are unlikely to consult PEP 8.  The API stability rules, however affect every user who programmed in python long enough to see a major release.  I don't have objections to Michael's definitions below, but if included in the library manual, they should be reworded to address the user rather than the developer of the API.

"""
How about making this explicit (either pep 8 or our developer docs):

If a module or package defines __all__ that authoritatively defines the 
public interface. Modules with __all__ SHOULD still respect the naming 
conventions (leading underscore for private members) to avoid confusing 
users. Modules SHOULD NOT export private members in __all__.

Names imported into a module a never considered part of its public API 
unless documented to be so or included in __all__.

Methods / functions / classes and module attributes whose names begin 
with a leading underscore are private.

If a class name begins with a leading underscore none of its members are 
public, whether or not they begin with a leading underscore.

If a module name in a package begins with a leading underscore none of 
its members are public, whether or not they begin with a leading underscore.

If a module or package doesn't define __all__ then all names that don't 
start with a leading underscore are public.

All public members MUST be documented. Public functions, methods and 
classes SHOULD have docstrings. Private members may have docstrings.
""" [1]

[1] http://mail.python.org/pipermail/python-dev/2010-November/105476.html

----------
nosy: +michael.foord

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