New submission from SilentGhost <ghost....@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 <rep...@bugs.python.org>
<http://bugs.python.org/issue10894>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
