[New-bugs-announce] [issue10894] Making stdlib APIs private
report at bugs.python.org
Wed Jan 12 14:17:16 CET 2011
New submission from SilentGhost <ghost.adh at gmail.com>:
Following suggestion in the Developers Guide (http://docs.python.org/devguide/#index-5) and the rules proposed by Michael Foord (http://mail.python.org/pipermail/python-dev/2010-November/105476.html):
> 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.
> Where in the standard library this means that a module exports stuff
that isn't helpful or shouldn't be part of the public API we need to
migrate to private names and follow our deprecation process for the
The following deprecation method is adopted:
from warnings import warn as _warn
_warn("The module.no_underscore() function is deprecated",
Note: this is a meta-issue. It should only depend on all individual issues fixing APIs. It's currently dependant only on resolved issue10371.
As I don't think it's reasonable to create an issue per stdlib module, I'm going to group a few modules in issue. However, when submitting patches, please create a patch per module to minimize disturbance. The files to check: Lib/module.py, Lib/test/test_module.py, Doc/library/module.rst
components: Library (Lib)
nosy: SilentGhost, brett.cannon
title: Making stdlib APIs private
versions: Python 3.3
Python tracker <report at bugs.python.org>
More information about the New-bugs-announce