[docs] [issue10434] Document the rules for "public names"
report at bugs.python.org
Tue Nov 16 16:48:42 CET 2010
Alexander Belopolsky <belopolsky at users.sourceforge.net> added the comment:
Michael Foord suggested adding the following to developer documentation such as PEP 8.  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.
Python tracker <report at bugs.python.org>
More information about the docs