Message126094
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
public names.
------------
The following deprecation method is adopted:
from warnings import warn as _warn
def no_underscore(<parameters>):
_warn("The module.no_underscore() function is deprecated",
DeprecationWarning, 2)
return _no_underscore(<parameters>)
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 |
|
Date |
User |
Action |
Args |
2011-01-12 13:17:17 | SilentGhost | set | recipients:
+ SilentGhost, brett.cannon |
2011-01-12 13:17:16 | SilentGhost | set | messageid: <1294838236.87.0.84648349826.issue10894@psf.upfronthosting.co.za> |
2011-01-12 13:17:13 | SilentGhost | link | issue10894 messages |
2011-01-12 13:17:12 | SilentGhost | create | |
|