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

Michael Foord fuzzyman at voidspace.org.uk
Wed Nov 17 14:11:51 CET 2010

On 17/11/2010 12:37, Łukasz Langa wrote:

Am 17.11.2010 12:57, schrieb Michael Foord:

On 17/11/2010 11:45, Nick Coghlan wrote:

The definition of the public/private policy in all its gory detail should be in PEP 8 as Guido suggests.

+1 Guido did not said that, though.

I think that is a reasonable interpretation, and the suggestion that by "in a style guide" means "create a new style guide" is more of a stretch.

I'm with Fred and other people that agree that PEPs should be more-less immutable. Let's make a new document (PEP 88?). The reasoning was well laid out here:

http://mail.python.org/pipermail/python-dev/2010-November/105641.html http://mail.python.org/pipermail/python-dev/2010-November/105642.html

In those emails Fred provides a solution to his most substantial difficulty, that other people base their own documents off pep8, by recommending that extension documents should refer to a specific revision.

I don't think those reasons are compelling and the cost of splitting the Python development style guide into multiple documents are higher. (They run the risk of contradicting each other, if you want to find a particular rule you have multiple places to check, there is no single authoritative place to send people, people wanting to base documents off the Python style rules now have to refer to multiple places, etc.)

So -1 on splitting Python development style guide into multiple documents.

Michael

Have we agreed the policy though?

Everybody has their own opinion on the matter. This discussion thread is getting too fractured to actually get us far enough with the conclusions. Let's make a PEP and discuss concrete wording on a concrete proposal. The library documentation may then contain a note about the difference in compatibility guarantees for public and private APIs, say that any interface and behaviour documented in the manual qualifies as public, then point readers to PEP 8 for the precise details.

+1 Yes, point to PEP 88. Best regards, Łukasz Langa

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/fuzzyman%40voidspace.org.uk

--

http://www.voidspace.org.uk/

READ CAREFULLY. By accepting and reading this email you agree, on behalf of your employer, to release me from all obligations and waivers arising from any and all NON-NEGOTIATED agreements, licenses, terms-of-service, shrinkwrap, clickwrap, browsewrap, confidentiality, non-disclosure, non-compete and acceptable use policies (”BOGUS AGREEMENTS”) that I have entered into with your employer, its partners, licensors, agents and assigns, in perpetuity, without prejudice to my ongoing rights and privileges. You further represent that you have the authority to release me from any BOGUS AGREEMENTS on behalf of your employer.

More information about the Python-Dev mailing list