Move Xarray custom exceptions into a new xarray.errors module

[benbovy]

A bit cleaner, especially when displayed in error tracebacks.

[benbovy]

I think this is ready. The warning emitted in the doc build seems unrelated.

All errors are still exposed in Xarray's root namespace for backward compatibility, although we might want to remove this at some point and only access them via xarray.errors? How best to let users know that this is deprecated? I updated all references in the doc already (hopefully I didn't miss any).

[dcherian]

Looks like we need to update this PR to include CoordinateValidationError from #10137

[dcherian]

Seems good to me.

@keewis do you have any ideas for handling the deprecation cycle here?

[mathause]

You could use a module level __getattr__ - add the following at the end of __init__.py (untested):

import warnings

def __getattr__(attr):

    moved_errors = (
        "MergeError",
    )

    import xarray.errors

    if attr in moved_errors:

        warnings.warn(f"Please import {attr} from xarray.errors", FutureWarning)

        # NOTE: could maybe use importlib.import_module() but it registers the function 
        # in sys.modules such that the warning is only called once

        return getattr(xarray.errors, attr)

    # required for ipython tab completion
    raise AttributeError(f"module {__name__!r} has no attribute {attr!r}")