[Numpy-discussion] Is `numpy.lib.shape_base.normalize_axis_index` considered part of the public API?
ralf.gommers at gmail.com
Mon Apr 6 09:52:14 EDT 2020
On Mon, Apr 6, 2020 at 3:31 PM Eric Wieser <wieser.eric+numpy at gmail.com>
> 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.
This is a nice function indeed, +1 for making it public.
Regarding namespace, it would be nice to decouple the `numpy` and
`numpy.lib` namespaces, so we can put this in `numpy.lib` and say that's
where library author functions go from now on. That'd be better than making
all `numpy.lib.*` submodules public.
> 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.
> On Sun, 5 Apr 2020 at 15:06, Sebastian Berg <sebastian at sipsolutions.net>
>> 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
>> > > (
>> > >
>> > > ),
>> > > 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.
>> > > 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
> NumPy-Discussion mailing list
> NumPy-Discussion at python.org
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the NumPy-Discussion