better distinguishing public and private APIs in SciPy
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
participants (1)
-
Ralf Gommers