[New-bugs-announce] [issue10894] Making stdlib APIs private

[SilentGhost]

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 
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

----------
components: Library (Lib)
messages: 126094
nosy: SilentGhost, brett.cannon
priority: normal
severity: normal
status: open
title: Making stdlib APIs private
versions: Python 3.3

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