Is `numpy.lib.shape_base.normalize_axis_index` considered part of the public API?
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
On 4/4/20, Warren Weckesser <warren.weckesser@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 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
On Sun, 2020-04-05 at 00:43 -0400, Warren Weckesser wrote:
On 4/4/20, Warren Weckesser <warren.weckesser@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@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
On 4/5/20, Sebastian Berg <sebastian@sipsolutions.net> wrote:
On Sun, 2020-04-05 at 00:43 -0400, Warren Weckesser wrote:
On 4/4/20, Warren Weckesser <warren.weckesser@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@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
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@sipsolutions.net> wrote:
On Sun, 2020-04-05 at 00:43 -0400, Warren Weckesser wrote:
On 4/4/20, Warren Weckesser <warren.weckesser@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@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
_______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
On Mon, Apr 6, 2020 at 3:31 PM Eric Wieser <wieser.eric+numpy@gmail.com> 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 <sebastian@sipsolutions.net> wrote:
On Sun, 2020-04-05 at 00:43 -0400, Warren Weckesser wrote:
On 4/4/20, Warren Weckesser <warren.weckesser@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@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
_______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
_______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
On 4/6/20, Ralf Gommers <ralf.gommers@gmail.com> wrote:
On Mon, Apr 6, 2020 at 3:31 PM Eric Wieser <wieser.eric+numpy@gmail.com> 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 <sebastian@sipsolutions.net> wrote:
On Sun, 2020-04-05 at 00:43 -0400, Warren Weckesser wrote:
On 4/4/20, Warren Weckesser <warren.weckesser@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@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
_______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
_______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
participants (4)
-
Eric Wieser -
Ralf Gommers -
Sebastian Berg -
Warren Weckesser