Is `numpy.lib.shape_base.normalize_axis_index` considered part of the public API?

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|

Is `numpy.lib.shape_base.normalize_axis_index` considered part of the public API?

Warren Weckesser-2
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
_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
Reply | Threaded
Open this post in threaded view
|

Re: Is `numpy.lib.shape_base.normalize_axis_index` considered part of the public API?

Warren Weckesser-2
On 4/4/20, Warren Weckesser <[hidden email]> 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
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
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
Reply | Threaded
Open this post in threaded view
|

Re: Is `numpy.lib.shape_base.normalize_axis_index` considered part of the public API?

Sebastian Berg
On Sun, 2020-04-05 at 00:43 -0400, Warren Weckesser wrote:

> On 4/4/20, Warren Weckesser <[hidden email]> 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
> [hidden email]
> https://mail.python.org/mailman/listinfo/numpy-discussion
>

_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Is `numpy.lib.shape_base.normalize_axis_index` considered part of the public API?

Warren Weckesser-2
On 4/5/20, Sebastian Berg <[hidden email]> wrote:

> On Sun, 2020-04-05 at 00:43 -0400, Warren Weckesser wrote:
>> On 4/4/20, Warren Weckesser <[hidden email]> 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
>> [hidden email]
>> https://mail.python.org/mailman/listinfo/numpy-discussion
>>
>
>
_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
Reply | Threaded
Open this post in threaded view
|

Re: Is `numpy.lib.shape_base.normalize_axis_index` considered part of the public API?

Eric Wieser
In reply to this post by Sebastian Berg
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 <[hidden email]> wrote:
On Sun, 2020-04-05 at 00:43 -0400, Warren Weckesser wrote:
> On 4/4/20, Warren Weckesser <[hidden email]> 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
> [hidden email]
> https://mail.python.org/mailman/listinfo/numpy-discussion
>

_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion

_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
Reply | Threaded
Open this post in threaded view
|

Re: Is `numpy.lib.shape_base.normalize_axis_index` considered part of the public API?

ralfgommers


On Mon, Apr 6, 2020 at 3:31 PM Eric Wieser <[hidden email]> wrote:
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.

Cheers,
Ralf

 

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 <[hidden email]> wrote:
On Sun, 2020-04-05 at 00:43 -0400, Warren Weckesser wrote:
> On 4/4/20, Warren Weckesser <[hidden email]> 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
> [hidden email]
> https://mail.python.org/mailman/listinfo/numpy-discussion
>

_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion

_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
Reply | Threaded
Open this post in threaded view
|

Re: Is `numpy.lib.shape_base.normalize_axis_index` considered part of the public API?

Warren Weckesser-2
On 4/6/20, Ralf Gommers <[hidden email]> wrote:

> On Mon, Apr 6, 2020 at 3:31 PM Eric Wieser <[hidden email]>
> wrote:
>
>> 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.
>
> Cheers,
> Ralf
>

Thanks all.  So far, it looks like folks are in favor of ensuring that
`normalize_axis_index` is public.  So I'll remove the implementation
from the scipy PR, and use the one in numpy.  For the current and
older releases of numpy, scipy can import the function
`numpy.core.multiarray`.  If a newer version of numpy is found, scipy
can grab it from wherever it is decided its public home should be.

Can we also make `normalize_axis_tuple` public?  Currently it resides
in `numpy.core.numeric`.

Warren

>
>
>>
>> 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 <[hidden email]>
>> wrote:
>>
>>> On Sun, 2020-04-05 at 00:43 -0400, Warren Weckesser wrote:
>>> > On 4/4/20, Warren Weckesser <[hidden email]> 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
>>> > [hidden email]
>>> > https://mail.python.org/mailman/listinfo/numpy-discussion
>>> >
>>>
>>> _______________________________________________
>>> NumPy-Discussion mailing list
>>> [hidden email]
>>> https://mail.python.org/mailman/listinfo/numpy-discussion
>>>
>> _______________________________________________
>> NumPy-Discussion mailing list
>> [hidden email]
>> https://mail.python.org/mailman/listinfo/numpy-discussion
>>
>
_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion