On 15 July 2013 17:31, Terry Reedy <tjreedy@udel.edu> wrote:
I do not think absence of documentation is a good signal. I would rather say that any private or partially private package that does not have a _ name *must* have a docstring saying that it is all or mostly private. (Or be a subpackage or module of something so marked.) And presuming that it is associated with something that is documented, then the doc should state that the implementation files are private.
In other words, I suggest that "modules that are not explicitly covered in the documentation ... [whose] names do not start with a leading underscore" should be empty. And I think "even if they include a module level documentation string." is backwards. Such files *should* have a docstring that serves as a substitute for a _ prefix.
I (now) agree - a disclaimer in the docstring is a better signal than an absence of documentation, and one we can reasonably make a requirement even for external applications that we bundle or otherwise bless as the "obvious way to do it" (as is happening with pip). ================= Private interfaces 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. 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, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia