Use add_note() to annotate exceptions when encoding fails

[shoyer]

We now always add variable names and contents when encoding fails, in contrast to the current practice where variable names and values are only sometimes specified, based on the name passed into VariableCoder.encode(). This provides better debugging experience for users.

In the future, we might remove name from VariableCoder.encode() because this makes it redundant.

For example, attempting to save a int64 fail in netCDF3 file now shows something like the following:

ValueError: could not safely cast array from int64 to int32...
Raised while encoding variable 'invalid' with value <xarray.Variable (invalid: 1)> Size: 8B
array([9223372036854775807])

Note that Exception.add_note() is a Python 3.11+ feature, so this PR will need to wait until #10438 is submitted.

• Tests added
• User visible changes (including notable bug fixes) are documented in whats-new.rst

[kmuehlbauer]

That's great for Errors, but for Warnings we would still need the name-kwarg, or am I missing something?

[keewis]

technically, warnings.warn also accepts Warning instances and Warning inherits from Exception, so this should be possible:

import warnings

w = UserWarning("message")
w.add_note("note")

warnings.warn(w)

However, the note on warnings is usually not printed (unless the warning is raised as an exception), so yes, I think we still need the name for warnings.

[kmuehlbauer]

However, the note on warnings is usually not printed (unless the warning is raised as an exception), so yes, I think we still need the name for warnings.

I've digged a bit deeper. So a warning equipped with add_note(), this additional note isn't printed when emitted as warning unfortunately. It only gets printed when emitted as error.

It would be possible to achieve this by a custom warning like SerializationWarning for all encoding/decoding warnings. In with warnings.catch_warnings() we can elevate the custom warning to error, catch elevated custom warning, rewrite the message with the added note and re-emit the warning. It would be much easier, if the notes would get printed for warnings, too. I didn't find anything related on the CPython issue tracker, most likely because of my mediocre search-fu.

[spencerkclark]

This is nice, thanks!