[Numpy-discussion] Is `numpy.lib.shape_base.normalize_axis_index` considered part of the public API?

[Eric Wieser]

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 <sebastian at sipsolutions.net>
wrote:

> On Sun, 2020-04-05 at 00:43 -0400, Warren Weckesser wrote:
> > On 4/4/20, Warren Weckesser <warren.weckesser at 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 at python.org
> > https://mail.python.org/mailman/listinfo/numpy-discussion
> >
>
> _______________________________________________
> NumPy-Discussion mailing list
> NumPy-Discussion at python.org
> https://mail.python.org/mailman/listinfo/numpy-discussion
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20200406/6d8a37ac/attachment.html>