On 17/11/2010 11:45, Nick Coghlan wrote:
On Wed, Nov 17, 2010 at 2:34 AM,<exar...@twistedmatrix.com> wrote:
I don't think it belongs only in PEP 8 (that's "a style guide" you're
referring to, correct?). 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.
Imagine trying to use a dictionary without knowing about alphabetical
ordering. Or driving a car without knowing what lane markers indicate.
The definition of the public/private policy in all its gory detail
should be in PEP 8 as Guido suggests.
+1
Have we agreed the policy though?
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
This sounds like the right approach to me.
All the best,
Michael
A similar note could be placed in the C API documentation (with a
reference to the detailed policy in PEP 7, perhaps REsTify'ing that
PEP in the process in order to link directly to the naming convention
section).
Cheers,
Nick.
--
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.
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
