[SciPy-Dev] Question about subpackage/submodule API

[Ralf Gommers]

On Mon, Feb 21, 2011 at 2:14 AM, Pauli Virtanen <pav at iki.fi> wrote:
> On Sun, 20 Feb 2011 11:40:27 -0600, Robert Kern wrote:
> [clip]
>> Actually, it is de facto standard practice. The presence of underscores
>> do mark something as private, but the absence of underscores do not mark
>> something as public. Almost no one prepends underscores to module names
>> regardless of whether they are considered "public" or "private". The
>> public API of a package is determined by any number of conventions which
>> may or may not be documented explicitly.

I tried to find a clear explanation somewhere in the Python docs but
failed. So you're right.

On the other hand Python itself seems to be consistent with
underscored modules, and in the first Stackoverflow hit for "python
API __init__" Alex Martelli says the same thing I did. I could be in
worse company:)

>> For scipy, the convention is that public functions are exposed in the __init__.py.

Only one level down from the scipy namespace. Unless it's two. With a
lot of stuff exposed that obviously isn't part of the API. It's pretty
inconsistent.

> True, it is what is typically done. The reason why it's done like this is
> however usually more laziness than some well-thought-out design principle.
>
> This does not have to be so. I don't foresee prefixing an underscore to
> "private" modules to be a PITA in practice. Some people also add a
> "packagename.api" module to expose a well-defined API. It's true that
> this doesn't matter very much, but carefully painted bike sheds look nice.

Once you accidentally break users' code with a refactor like the one
that started this thread, it may matter a little....

Cheers,
Ralf