DOC: zarr.errors changes in v3

[christine-e-smit]

Describe the issue linked to the documentation

It looks like you've completely changed the exceptions under zarr.errors in the transition from v2 to v3. Our v2 code catches zarr.errors.PathNotFoundError to determine if a zarr store exists, but v3 appears to be using python's FileNotFound exception now. This makes a lot of sense, but it is a change that anyone who catches v2 exceptions will need to know about.

Here's the errors in v2:

>>> import inspect
>>> import zarr
>>> for name,cls in inspect.getmembers(zarr.errors,inspect.isclass):
...     print(cls)
...     
<class 'zarr.errors.ArrayIndexError'>
<class 'zarr.errors.ArrayNotFoundError'>
<class 'zarr.errors.BadCompressorError'>
<class 'zarr.errors.BoundsCheckError'>
<class 'zarr.errors.ContainsArrayError'>
<class 'zarr.errors.ContainsGroupError'>
<class 'zarr.errors.CopyError'>
<class 'zarr.errors.FSPathExistNotDir'>
<class 'zarr.errors.GroupNotFoundError'>
<class 'zarr.errors.MetadataError'>
<class 'zarr.errors.NegativeStepError'>
<class 'zarr.errors.PathNotFoundError'>
<class 'zarr.errors.ReadOnlyError'>
<class 'zarr.errors.VindexInvalidSelectionError'>
<class 'zarr.errors._BaseZarrError'>
<class 'zarr.errors._BaseZarrIndexError'>

And here's v3:

>>> import inspect
>>> import zarr
>>> for name,cls in inspect.getmembers(zarr.errors,inspect.isclass):
...     print(cls)
...     
typing.Any
<class 'zarr.errors.BaseZarrError'>
<class 'zarr.errors.ContainsArrayAndGroupError'>
<class 'zarr.errors.ContainsArrayError'>
<class 'zarr.errors.ContainsGroupError'>
<class 'zarr.errors.MetadataValidationError'>
<class 'zarr.errors.NodeTypeValidationError'>

Given that there are many fewer v3 exceptions, I'm guessing you decided to clean up and consolidate your exception classes.

Suggested fix for documentation

I think that in the 3.0 Migration Guide, the section "Getting ready for 3.0", number 2 should include something short about the zarr.errors library. Unless you have an easy to understand grand philosophy for how you made these changes, I'm happy to submit a pull request with some generic language.

[christine-e-smit]

Actually, now I'm wondering if maybe there is a direct mapping between a lot of errors in v2 and v3? Maybe you always use FileNotFound where you previously used zarr.errors.PathNotFoundError? So perhaps it is possible to document at least some of these changes more specifically? Or did the underlying implementation change so much that it's problematic to try and tell folks to just update their except statements to catch FileNotFound wherever they previously caught zarr.errors.PathNotFoundError?

[d-v-b]

thanks for this issue @christine-e-smit, I think this is a part of the 3.0 release that fell between the cracks. We should definitely fix this, and I think replacing FileNotFound with a new zarr.errors.PathNotFoundError would be a great step.

[christine-e-smit]

@d-v-b - so you think that the error should go back to zarr.errors.PathNotFoundError? Interesting. I guess the real question is, what is the pythonic way of doing this? New exception classes or re-use of existing exceptions? I'm not immediately finding anything on the internet that seems to have an opinion on this subject, but that is probably down to my searching abilities. boto3, which is not necessarily known for being particularly pythonic, does use a custom exception when it is unable to find an object rather than using FileNotFound.

I guess I personally could go either way. FileNotFound is reasonably intuitive because Zarr stores are conceptually file-like. But you do have to ignore the fact that Zarr stores can be saved in things that are not files, including s3 objects, and you have to ignore the fact that Zarr stores are really a set of key-value pairs under the hood. So maybe they aren't all that file-like after all.

[d-v-b]

I think we actually have a simpler question to answer -- what did zarr-python 2 do, and is there any reason to deviate from that? I think for exceptions, there's no real need for innovation in zarr-python 3, so we should just use the same exceptions as before. Given that v3 was a complete re-write, I think we simply didn't have time to re-implement the old exception classes. In the next few days I will open a PR that corrects this omission.

[christine-e-smit]

@d-v-b - works for me! Thanks.