Private and public package modules?

Question

In Python we usually make a distinction between private and public attributes of classes, objects and modules, by prefixing private attributes with a _ at the beginning of the name. So a module level function meant for private use would be named _func .

Is there such a convention for package level elements, ie modules? For example suppose I have several modules which are part of the public API (except for their private _ prefixed components) and several modules which are totally for private use. Should I prefix the private ones with a _ ? Should I put them in a " private " sub-package?

Is there a convention for this?

Answer 1

PEP8 is of course the accepted convention for Python coding style, however it doesn't go into much depth about package naming:

From Package and Module Names :

Modules should have short, all-lowercase names. Underscores can be used in the module name if it improves readability. Python packages should also have short, all-lowercase names, although the use of underscores is discouraged.

In short, there is no real accepted standard for letting users know a particular sub-package shouldn't be used. Instead, you should clearly document your code to indicate private and public packages. Your suggestion of using the private package would fit well there. internal could be another option.

Public and Internal Interfaces goes into more depth on this:

Documented interfaces are considered public, unless the documentation explicitly declares them to be provisional or internal interfaces exempt from the usual backwards compatibility guarantees. All undocumented interfaces should be assumed to be internal.

and

An interface is also considered internal if any containing namespace (package, module or class) is considered internal.