Author SilentGhost
Recipients SilentGhost, brett.cannon
Date 2011-01-12.13:17:12
SpamBayes Score 3.56604e-13
Marked as misclassified No
Message-id <1294838236.87.0.84648349826.issue10894@psf.upfronthosting.co.za>
In-reply-to
Content
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
History
Date User Action Args
2011-01-12 13:17:17SilentGhostsetrecipients: + SilentGhost, brett.cannon
2011-01-12 13:17:16SilentGhostsetmessageid: <1294838236.87.0.84648349826.issue10894@psf.upfronthosting.co.za>
2011-01-12 13:17:13SilentGhostlinkissue10894 messages
2011-01-12 13:17:12SilentGhostcreate