[Python-Dev] Breaking undocumented API

[Michael Foord]

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.