[SciPy-Dev] better distinguishing public and private APIs in SciPy

[Ralf Gommers]

Hi all,

Last week I filed https://github.com/scipy/scipy/issues/14360. The summary
of that is: I think it's time to make private APIs really private, and have
a better-defined public API. People don't read docs, even maintainers of
other libraries like Dask and CuPy. While we have very prominently
documented what our public API is, on the front page of the reference guide
(http://scipy.github.io/devdocs/reference/index.html#api-definition), this
is not enough. Now that more and more other libraries (Dask, CuPy, JAX,
Pytorch, RAPIDS, etc.) are starting to reimplement SciPy APIs, this is
becoming more of an issue.

GitHub has gotten better (I think) at following renames, so `git blame`
still works as expected after renaming a file - which was my main concern.
My proposed approach is to add a test that ensures we won't add any new
namespaces with missing underscores (we can steal this test from NumPy),
add underscores to file names that are missing them, and deprecate
accessing `scipy.submodule.some_private_namespace` with a deprecation that
only expires in SciPy 2.0. There may be a few places where we find that
some semi-private API is used quite a lot in the wild. In those cases, I
suggest to still do the rename but don't add the deprecation (just use a
code comment instead to explain), to avoid too much downstream churn.

Please look at https://github.com/scipy/scipy/issues/14360 for more details
on this, and comment if you see a potential issue with this.

Cheers,
Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.python.org/pipermail/scipy-dev/attachments/20210713/002223a8/attachment.html>