[SciPy-Dev] Question about subpackage/submodule API

[Ralf Gommers]

On Tue, Feb 15, 2011 at 7:53 AM, Warren Weckesser
<warren.weckesser at enthought.com> wrote:
>
>
> On Sat, Feb 12, 2011 at 7:28 PM, Ralf Gommers <ralf.gommers at googlemail.com>
> wrote:
>>
>>
>> On Sun, Feb 13, 2011 at 5:05 AM, Pauli Virtanen <pav at iki.fi> wrote:
>>>
>>> One wild idea to make this clearer could be to prefix all internal sub-
>>> package names with the usual '_'. In the long run, it probably wouldn't
>>> be as bad as it initially sounds like.
>>>
>> This is not a wild idea at all, I think it should be done. I considered
>> all modules without '_' prefix public API.
>>
>
>
> Agreed (despite what I said in my initial post).
>
> To actually do this, we'll need to check which packages have modules that
> should be private.  These can be renamed in 0.10 to have an underscore,  and
> new public versions created that contain a deprecation warning and that
> import everything from the private version.   The deprecated public modules
> can be removed in 0.11.
>
> Some modules will require almost no changes.  For example, scipy.cluster
> *only* exposes two modules, vq and hierarchy, so no changes are needed.
> (Well, there is also the module info.py that all packages have.  That should
> become _info.py--there's no need for that to be public, is there?)

Agreed, rename to _info.py

> Other packages will probably require some discussion about what modules should be
> public.
>
> Consider the above a proposed change for 0.10 and 0.11--what do you think?
>
Sounds good. Attached is a file that goes through scipy sub-packages
and checks their __all__ for modules. Those are public by definition
(but this doesn't give you the whole API). It's pretty messy, for
example:

signal
======
bsplines
filter_design
fir_filter_design
integrate
interpolate
linalg
ltisys
np
numpy
optimize
scipy
signaltools
sigtools
special
spline
types
warnings
waveforms
wavelets
windows

That should be cleaned up. Then there are also public modules that
don't show up of course (for example odr.models).

How about doing the following? :
1. Start a doc, perhaps on the wiki, with a full list of public modules.
2. Put that doc at the beginning of the reference guide, as well as
the relevant part in the docstring for each sub-package.
3. Clean up existing __all__, and add __all__ to sub-packages that
don't have them yet.
4. Rename private modules, with suitable deprecation warning.

Cheers,
Ralf
-------------- next part --------------
A non-text attachment was scrubbed...
Name: check_for_modules.py
Type: application/octet-stream
Size: 943 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20110220/f228f454/attachment.obj>