<div dir="ltr">+1  This is already how we've been behaving for years.<div class="gmail_extra"><br><br><div class="gmail_quote">On Sun, Jul 14, 2013 at 4:09 AM, Nick Coghlan <span dir="ltr"><<a href="mailto:ncoghlan@gmail.com" target="_blank">ncoghlan@gmail.com</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div><div class="h5"><div class="gmail_quote">On 14 July 2013 18:11, Nick Coghlan <span dir="ltr"><<a href="mailto:ncoghlan@gmail.com" target="_blank">ncoghlan@gmail.com</a>></span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<div dir="ltr"><div><div><div><div>Currently, the naming section of PEP 8 doesn't say very much about what a leading underscore *means* in the Python standard library.<br><br></div>I would like to add a new "Private interfaces" subsection under "Naming Conventions" to say the following:<br>



<br></div></div></div></div></blockquote><div><br></div></div></div></div>Slight adjustment to the proposed wording to ensure completely undocumented modules are also considered private:<br><br>=================<br>Private interfaces<br>


<br>Unless 
explicitly documented otherwise, a leading underscore on any name 
indicates that it is an internal implementation detail and backwards 
compatibility guarantees do not apply. It is strongly encouraged that 
private APIs (whether modules, classes, functions, attributes or other 
names) be clearly marked in this way,</div></div></blockquote><div><br></div><div><snip></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr">

<div class="gmail_extra">as Python users may rely on 
introspection to identify available functionality and may be misled 
into believing an API without a leading underscore is in fact a public
 API with the standard backwards compatibility guarantees.<br></div></div></blockquote><div><br></div><div>While true, I'm not sure the last part of the sentence is necessary. Once we've established that a leading _ indicates something is private there isn't much point in explaining the various ways people might find them.  I'm happy regardless of this bit being there.</div>

<div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra">
<br>Even when their names do not start with a leading underscore, all test modules and all modules that are not covered in the documentation are also considered private interfaces.<br><br>Similarly, the specific modules and external APIs imported by a module are always considered an implementation detail. Other 
modules should not rely on indirect access to such imported interfaces unless they
 are an explicitly documented part of the containing module's API (such as ``os.path`` or a package ``__init__`` module exposing functionality from submodules).<br>
=================<br></div></div></blockquote></div></div></div>