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

[Warren Weckesser]

On 4/5/20, 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


Thanks, Sebastian.  For now, I proposed a private Python
implementation in scipy: https://github.com/scipy/scipy/pull/11797
If the numpy version is added to the public numpy API, it will be easy
to change scipy to use it.

Warren



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