On Mon, 2013-07-15 at 18:40 -0400, Barry Warsaw wrote: > Working from what I think is the latest version. > > In general, i'd rather be prescriptive of future conventions than descriptive > of current conventions. It's okay to exempt existing code, and as a general > rule we've never been fond of rewriting existing code to update it to new > standards or APIs. We don't need to do so here either.
FWIW, I'm very skeptical of a PEP 8 guideline that would try to proscribe that the "non-internal" API of a module or class would be defined solely by a naming convention. If what's being described here does become a rule, there is reason to believe that future users who treat this PEP as the word-of-god (and there are a *lot* of them; I hear from people literally every week who want to "PEP8-ify" my code in some limited-value-added way) will be harmed. They'll be living in a fantasy world where every non-underscore-prefixed thing is now a defacto API. But I have lived in a world where that has not been the case since 1998, and the chance that I'll go back and change all my public code to satisfy a questionable introspection convention is pretty slim. - C > > On Jul 15, 2013, at 05:48 PM, Nick Coghlan wrote: > > >Private interfaces > > "Internal" or "Non-public" > > >Unless explicitly documented otherwise, a leading underscore on any > >name indicates that it is an internal implementation detail and any > >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, 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. > > How about: > > "All internal interfaces (modules, classes, functions, attributes or other > names) should be prefixed with a single leading underscore. Such names are > internal implementation details for which no backward compatibility guarantees > are made, unless otherwise specified. > > Existing code and other narrowly accepted exceptions may override this > recommendation, in which case the docstrings and/or documentation for such > code must clearly and explicitly state the internal status of the APIs. > > Imported names should always be considered an implementation detail. Other > modules must not rely on indirect access to such imported names unless they > are an explicitly documented part of the containing module's API, such as > ``os.path`` or a package's ``__init__`` module that exposes functionality from > submodules. Public names exported by a module should be include in the > module's ``__all__`` attribute." > > >While the explicit use of a leading underscore is the preferred solution, > >the names of some private (or partially private) modules (such as ``test`` > >and ``idlelib``) lack the leading underscore either for historical reasons > >or because they expose a public command line interface through the > >``-m`` switch. Such modules should include an explicit disclaimer in > >their module docstring, indicating that they do not use the leading > >underscore convention and noting where the definition of the public > >API (if any) can be found (the public API definition may also be part > >of the module docstring). > > > >As a general principle, 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 that exposes functionality > >from submodules). > > Cheers, > -Barry > _______________________________________________ > 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/lists%40plope.com _______________________________________________ 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