ENH: Add the axis and ndim attributes to np.AxisError

[BvB93]

This PR adds the new axis and ndim attributes to the np.AxisError class, an addition inspired by similar
changes introduced to AttributeError in Python 3.10.

It also provided an excuse to update the classes' documentation and tests, both of which were previously rather lacking.

Examples

In [1]: import numpy as np

In [2]: exc = np.AxisError(2, 1)
   ...: print(exc)
axis 2 is out of bounds for array of dimension 1

In [3]: exc.axis
Out[3]: 2

In [4]: exc.ndim
Out[4]: 1

[BvB93]

A few other candidates the might be worthwhile to add here:

numpy/numpy/__init__.pyi

Lines 3646 to 3653 in 89babbd

	# Warnings
	class ModuleDeprecationWarning(DeprecationWarning): ...
	class VisibleDeprecationWarning(UserWarning): ...
	class ComplexWarning(RuntimeWarning): ...
	class RankWarning(UserWarning): ...
	# Errors
	class TooHardError(RuntimeError): ...

[BvB93]

Currently I'm in favor of either using the current approach with cls._reconstructor or
to use the updated__reduce__ from #19459 (comment). Is there any preference?

[seberg]

LGTM, I am happy with the patterns as is. Delaying string construction might be worthwhile, but doesn't seem too important?

The one thing I thought might be nice, is to note that AxisError subclasses both IndexError and ValueError, since that is important for try/except clauses. But also fine to improve later, it isn't like we had docs before...

[BvB93]

The one thing I thought might be nice, is to note that AxisError subclasses both IndexError and ValueError, since that is important for try/except clauses. But also fine to improve later, it isn't like we had docs before...

It seems like an easy (and sensible) change to make though, so done as of 16964ae.

[eric-wieser]

To be clear, the alternative I'm suggesting is:

class AxisError(ValueError, IndexError):
    def __init__(self, axis, ndim=None, msg_prefix=None):
        if ndim is None and msg_prefix is None:
            # single-argument form (for backwards compatibility) sets just the message
            self._msg = axis
            self.axis = None
            self.ndim = None
        else:
            self._msg = msg_prefix
            self.axis = axis
            self.ndim = ndim

    def __str__(self):
        if self.axis is not None and self.ndim is not None:
            msg = "axis {} is out of bounds for array of dimension {}".format(
                self.axis, self.ndim)
            if self._msg is not None:
                msg = "{}: {}".format(self._msg, msg)
            return msg
        else:
            return self._msg

Which also provides an AxisError(10, 3)-style __repr__ for free

[eric-wieser]

Thanks for the iteration. The new docs are great!

I've suggested a possible longer explanation of why we subclass indexerror and valueerror - feel free to reword it. The versionadded definitely seems like a good thing to mention, but I'm not sure how far up the docstring it belongs.

[seberg]

Great also following up with the __str__ method :). Lets put this in, thanks Bas and Eric.