When I added this function, it was always my intent for it to be consumed by downstream packages, but as Sebastian remarks, it wasn't really desirable to put it in the top-level namespace.
I think I would be reasonably happy to make the guarantee that it would not be removed (or more likely, moved) without a lengthy deprecation cycle. Perhaps worth opening a github issue, so we can keep track of how many downstream projects are already using it. Eric On Sun, 5 Apr 2020 at 15:06, Sebastian Berg <sebast...@sipsolutions.net> wrote: > On Sun, 2020-04-05 at 00:43 -0400, Warren Weckesser wrote: > > On 4/4/20, Warren Weckesser <warren.weckes...@gmail.com> wrote: > > > It would be handy if in scipy we can use the function > > > `numpy.lib.shape_base.normalize_axis_index` as a consistent method > > > for > > > validating an `axis` argument. Is this function considered part of > > > the public API? > > > > > > There are modules in numpy that do not have leading underscores but > > > are still usually considered private. I'm not sure if > > > `numpy.lib.shape_base` is one of those. `normalize_axis_index` is > > > not > > > in the top-level `numpy` namespace, and it is not included in the > > > API > > > reference > > > ( > > > > https://numpy.org/devdocs/search.html?q=normalize_axis_index&check_keywords=yes&area=default > > > ), > > > so I'm not sure if we can safely consider this function to be > > > public. > > > > > I do not see a reason why we should not make those functions public. > The only thing I see is that they are maybe not really required in the > main namespace, i.e. you can be expected to use:: > > from numpy.something import normalize_axis_tuple > > I think, since this is a function for library authors more than end- > users. And we do not have much prior art around where to put something > like that. > > Cheers, > > Sebastian > > > > > > Warren > > > > > > > Answering my own question: > > > > "shape_base.py" is not where `normalize_axis_index` is originally > > defined, so that module can be ignored. > > > > The function is actually defined in `numpy.core.multiarray`. The > > pull > > request in which the function was created is > > https://github.com/numpy/numpy/pull/8584. Whether or not the function > > was to be public is discussed starting here: > > https://github.com/numpy/numpy/pull/8584#issuecomment-281179399. A > > leading underscore was discussed and intentionally not added to the > > function. On the other hand, it was not added to the top-level > > namespace, and Eric Wieser wrote "Right now, it is only accessible > > via > > np.core.multiarray.normalize_axis_index, so yes, an internal > > function". > > > > There is another potentially useful function, `normalize_axis_tuple`, > > defined in `numpy.core.numeric`. This function is also not in the > > top-level numpy namespace. > > > > So it looks like neither of these functions is currently intended to > > be public. For the moment, I think we'll create our own utility > > functions in scipy. We can switch to using the numpy functions if > > those functions are ever intentionally made public. > > > > Warren > > _______________________________________________ > > NumPy-Discussion mailing list > > NumPy-Discussion@python.org > > https://mail.python.org/mailman/listinfo/numpy-discussion > > > > _______________________________________________ > NumPy-Discussion mailing list > NumPy-Discussion@python.org > https://mail.python.org/mailman/listinfo/numpy-discussion >
_______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
