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

[Nick Coghlan]

On 16 July 2013 21:10, Nick Coghlan <ncoghlan at gmail.com> wrote:
> On 16 July 2013 20:28, Richard Oudkerk <shibturn at gmail.com> wrote:
>> On 16/07/2013 6:44am, Nick Coghlan wrote:
>>>
>>> Clarifying what constitutes an internal interface in a way that
>>> doesn't require renaming anything is a necessary prerequisite for
>>> bundling or bootstrapping the pip CLI in Python 3.4 (as pip exposes
>>> its internal implemetnation API as "import pip" rather than "import
>>> _pip" and renaming it would lead to a lot of pointless code churn).
>>> Without that concern, the topic never would have come up.
>>
>>
>> BTW, how does the use of __all__ effect things?  Somewhere I got the idea
>> that if a module uses __all__ then anything not listed is internal.  I take
>> it that is wrong?
>
> Gah, you're right. I did consider that, then forgot to include it in
> the proposed text.
>
> Rather than throwing more versions of the text at the list, I'll
> create a tracker issue and post a proposed patch for PEP 8.

Tracker issue: http://bugs.python.org/issue18472

When I went to write this in context, I realised it made more sense to
focus on defining what a *public* interface was, and how that differed
from an internal interface. WIth that approach, the natural flow of
the text was:

* the public interface is preferentially defined by the documentation
* __all__ is the main programmatic interface
* leading underscores are then mostly a helper that makes it easier to
remember which is which while actually *working* on the code (but
still a good practice)

I also spotted a few other oddities as I went through. The obviously
wrong ones I just fixed, but there were a couple relating to
exceptions that seem unnecessary or ill-advised given PEP 352 and
3151, plus the one about absolute vs explicit relative imports that I
started a separate thread for.

Cheers,
Nick.

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