[Python-Dev] Tweaking PEP 8 guidelines for use of leading underscores

[Nick Coghlan]

On 15 July 2013 09:48, Steven D'Aprano <steve at pearwood.info> wrote:
> On 14/07/13 21:09, Nick Coghlan wrote:
>
>> Slight adjustment to the proposed wording to ensure completely
>> undocumented
>> modules are also considered private:
>
>
> -1 on this adjustment. If somebody cannot be bothered writing a one-line doc
> string:
>
> "This module is private, don't touch."
>
> then they certainly shouldn't be allowed to use up a public name for a
> private module. I don't think we should be encouraging more private,
> undocumented modules. (Documentation is valuable even for private modules.)

For context, this arose when I checked PEP 8 after the point was
raised on distutils-sig that pip uses a public name for its
implementation module (also pip, same as the CLI), but officially
exposes no stable public programmatic API.

At the moment, according to what little PEP 8 has to say about public
vs private interfaces, that means a bundled pip would represent a new
public API, despite the fact that the only documented interface for
pip is the CLI, not the Python module API.

Since we've been burned by people assuming private APIs are public in
the past, I figured it made sense to get the actual standards we
follow in practice documented properly, *before* anyone further gets
the wrong idea from "import pip; help(pip)".

Cheers,
Nick.

--
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia