[SciPy-Dev] defining public API (was: prepending underscores ...)

Ralf Gommers ralf.gommers@googlemail....
Mon Jun 13 11:07:38 CDT 2011


On Sat, Jun 4, 2011 at 1:38 AM, Ralf Gommers <ralf.gommers@googlemail.com>wrote:

>
>
> On Fri, Jun 3, 2011 at 10:05 PM, Robert Kern <robert.kern@gmail.com>wrote:
>
>> On Fri, Jun 3, 2011 at 14:57, Ralf Gommers <ralf.gommers@googlemail.com>
>> wrote:
>> > Hi,
>> >
>> > A while ago we discussed making a clear distinction between public and
>> > private modules by using underscores consistently, see
>> > http://thread.gmane.org/gmane.comp.python.scientific.devel/14936.
>> >
>> > I've done this for a few modules now, see
>> > https://github.com/rgommers/scipy/tree/underscores. Most files could
>> simply
>> > be underscored, some other would conflict with extension modules so I
>> also
>> > had to append _py to the name. Also I added a file doc/source/api.rst
>> that
>> > states which modules are public (up for discussion of course).
>> >
>> > With google code search I checked how common it is to import from
>> modules
>> > that are supposed to be private, for example "from
>> scipy.optimize.optimize
>> > import fmin". It's not very common but does happen, so deprecation
>> warnings
>> > should be put in.
>> >
>> > Before going further I'd like to check that this looks okay to people.
>> What
>> > do you think?
>>
>> I'm still -1 on it. I think it's unnecessary and potentially disruptive.
>>
>> It will indeed be disruptive for those users who imported from private
> modules, they will get deprecation warnings and would need to update their
> code. Those same users can run into trouble anyway though unless we treat
> everything that is now ambiguous as public.
>
> Unnecessary, I disagree. Even among developers it is not clear what the
> public API is. This is the clearest way to solve it.
>
> An alternative would be to just document very clearly what the API is. Just
> saying "The public API of a package is determined by any number of
> conventions which may or may not be documented explicitly." doesn't help
> much.
>
> Okay, I've taken one step back here and added documentation for the API.
I've sent a pull request for that:  https://github.com/scipy/scipy/pull/35

Any comments welcome.

Cheers,
Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/scipy-dev/attachments/20110613/80e4d1ef/attachment.html 


More information about the SciPy-Dev mailing list