+1 This is already how we've been behaving for years.
On Sun, Jul 14, 2013 at 4:09 AM, Nick Coghlan <ncogh...@gmail.com> wrote: > On 14 July 2013 18:11, Nick Coghlan <ncogh...@gmail.com> wrote: > >> Currently, the naming section of PEP 8 doesn't say very much about what a >> leading underscore *means* in the Python standard library. >> >> I would like to add a new "Private interfaces" subsection under "Naming >> Conventions" to say the following: >> >> > Slight adjustment to the proposed wording to ensure completely > undocumented modules are also considered private: > > ================= > Private interfaces > > 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, > <snip> > 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. > 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. > 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. > > 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). > ================= >
_______________________________________________ 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
