[SciPy-Dev] defining public API (was: prepending underscores ...)
Mon Jun 13 11:07:38 CDT 2011
On Sat, Jun 4, 2011 at 1:38 AM, Ralf Gommers <firstname.lastname@example.org>wrote:
> On Fri, Jun 3, 2011 at 10:05 PM, Robert Kern <email@example.com>wrote:
>> On Fri, Jun 3, 2011 at 14:57, Ralf Gommers <firstname.lastname@example.org>
>> > 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
>> > be underscored, some other would conflict with extension modules so I
>> > had to append _py to the name. Also I added a file doc/source/api.rst
>> > states which modules are public (up for discussion of course).
>> > With google code search I checked how common it is to import from
>> > that are supposed to be private, for example "from
>> > import fmin". It's not very common but does happen, so deprecation
>> > should be put in.
>> > Before going further I'd like to check that this looks okay to people.
>> > 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
> 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.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the SciPy-Dev