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

[Nick Coghlan]

On 16 July 2013 10:23, Chris McDonough <chrism at plope.com> wrote:
> On Mon, 2013-07-15 at 18:40 -0400, Barry Warsaw wrote:
>> Working from what I think is the latest version.
>>
>> In general, i'd rather be prescriptive of future conventions than descriptive
>> of current conventions.  It's okay to exempt existing code, and as a general
>> rule we've never been fond of rewriting existing code to update it to new
>> standards or APIs.  We don't need to do so here either.
>
> FWIW, I'm very skeptical of a PEP 8 guideline that would try to
> proscribe that the "non-internal" API of a module or class would be
> defined solely by a naming convention.
>
> If what's being described here does become a rule, there is reason to
> believe that future users who treat this PEP as the word-of-god (and
> there are a *lot* of them; I hear from people literally every week who
> want to "PEP8-ify" my code in some limited-value-added way) will be
> harmed.  They'll be living in a fantasy world where every
> non-underscore-prefixed thing is now a defacto API.  But I have lived in
> a world where that has not been the case since 1998, and the chance that
> I'll go back and change all my public code to satisfy a questionable
> introspection convention is pretty slim.

Hence the "just say it's an internal API in the docstring" escape
clause. That's a pretty low bar to meet for PEP 8 compliance, and one
we need, too (for things like test, idlelib and a bundled pip).

I do need to figure out how to tweak the wording to make it clear that
internal nature of an API applies to all contained APIs as well.

Cheers,
Nick.

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