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

Warren Weckesser warren.weckesser at gmail.com
Sun Apr 5 00:43:02 EDT 2020

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.
> 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

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.


More information about the NumPy-Discussion mailing list