[Python-Dev] Breaking undocumented API (original) (raw)

Ben Finney ben+python at benfinney.id.au
Tue Nov 16 22:31:41 CET 2010

exarkun at twistedmatrix.com writes:

On 03:48 pm, guido at python.org wrote: >Hm. Apart from the specific semantics assigned by the language to >single and double leading (and trailing) underscores, I still think >this belongs in a style guide, not in the library manual.

I don't think it belongs only in PEP 8 (that's "a style guide" you're referring to, correct?).

I don't know about Guido, but I'd be −1 on suggestions to add more normative information to PEP 7, PEP 8, PEP 257, or any other established style guide PEP. I certainly don't want to have to keep going back to the same documents frequently just to see if the set of recommendations I already know has changed recently.

Rather, I took Guido's mention of “this belongs in a style guide” as suggesting a new style guide. Perhaps one that explicitly obsoletes an existing one or perhaps not; either way, the updated normative recommendations are in a new document with a new name, so that one knows whether one has already read it.

It needs to be front and center. This is information that every single user of the stdlib needs in order to use the stdlib correctly.

True enough. This is information that goes beyond a style guide for writers, and into conventions that API users need to know also.

-- \ “I went to the museum where they had all the heads and arms | `\ from the statues that are in all the other museums.” —Steven | o_) Wright | Ben Finney

More information about the Python-Dev mailing list