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

[Nick Coghlan]

On 15 Jul 2013 13:43, "Steven D'Aprano" <steve at pearwood.info> wrote:
>
> On Mon, Jul 15, 2013 at 10:30:02AM +1000, Nick Coghlan wrote:
> > 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.
>
> I don't think we should bless this as official policy, certainly not for
> the standard library. We can't tell external modules what to do, and
> possibly there's nothing we can do about existing undocumented private
> modules, short of renaming them, but I think that at least for new
> additions to the std lib module names should follow the same
> single-underscore convention as functions, classes etc. A single leading
> underscore introduces the private namespace, everything else is public.
>
> I've seen too much undocumented public code to ever assume that lack of
> documentation implies it is private.
>
>
> > 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)".
>
> I can tell you that people will do that regardless of what PEP 8 has to
> say about "not documented == private". Especially as worded. I'm sure I
> won't be the only person to reason that if a module has a docstring, it
> is therefore documented.
>
> It takes one character to explicitly document a module as private.
> That's much better than expecting people to treat their failure to
> find documentation as an implicit warning.

We're considering bundling the pip CLI for the convenience of educators and
beginners, not adding their implementation module to the standard library.
That means we need a bright shining line for what constitutes "in the
standard library". Yes, it's better if people properly use a leading
underscore, but the fact is many don't (including idlelib, as Terry noted)
and it becomes a disruptive change to add it later if people don't start
with it. The pip and IDLE developers have better things to be doing than
changing the names of undocumented APIs just because the application is
distributed along with CPython.

Cheers,
Nick.

>
>
>
> --
> Steven
> _______________________________________________
> Python-Dev mailing list
> Python-Dev at python.org
> http://mail.python.org/mailman/listinfo/python-dev
> Unsubscribe:
http://mail.python.org/mailman/options/python-dev/ncoghlan%40gmail.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20130715/7a182b78/attachment.html>