Improve error message on UnsupportedFileFormatError

[tlambert03]

Describe the Bug

UnsupportedFileFormatError not useful

im = bioio.BioImage('some.nd2')

File ~/miniforge3/envs/chunglab/lib/python3.11/site-packages/bioio/bio_image.py:171, in BioImage.determine_reader(image, fs_kwargs, **kwargs)
    168 # If we haven't hit anything yet, we likely don't support this file / object
    169 # with the current plugins installed
    170 image_type = str(type(image))
--> 171 raise biob.exceptions.UnsupportedFileFormatError(
    172     "BioImage",
    173     image_type,
    174     msg_extra=(
    175         "You may need to install an extra format dependency. "
    176         "See bioio README for list of some known plugins."
    177     ),
    178 )

UnsupportedFileFormatError: BioImage does not support the image: '<class 'str'>'. 
You may need to install an extra format dependency. 
See bioio README for list of some known plugins.

Expected Behavior

1. ~The type is shown incorrectly image_type = str(type(image)) is very likely to simply show '<class 'str'>' which is unlikely to help the user~ .... looks like this is fixed in main
2. The bioio README doesn't have a list of known plugins
3. It would be nice to have an in-library awareness of known plugins. that is, if you're going to be maintaining a list in a README somewhere, you might as well put that in that code too to suggest a specific plugin to install.

Reproduction

Environment

• OS Version: [e.g. macOS 11.3.1]
• bioio Version: [e.g. 0.5.0]

[SeanDuHare]

#16 should fix your second suggestion.

As for your third suggestion, I've been personally on the fence about this since I'm unsure how we'd like to go about choosing the best suggestion to make to users when multiple plug-ins support the same file format. Perhaps we could just return them all

[tlambert03]

Definitely, all is better than none (particularly when most cases will be one, and the rare case will be only 2 or 3?)

[BrianWhitneyAI]

Will #62 resolve this?

[evamaxfield]

I think there are a few things to try before closing this out.

1. When we report that we think the file isn't supported we should dump the list of plugins currently installed. Not all the extensions but the plugins. This should be a relatively short list and an easy way to alert someone if they forgot to install a plugin before trying to read (I forget dependencies a decent amount of the time).

2. We should link them to the registry table in #62 as a part of the error message. Example: please review our list of known plugins to see if there is a plugin that supports your file.

3. If all else fails, we should prompt them to run something like determine_plugin(file, debug=True) and link them to the bug report page in the case that they do have the plugin installed (and or they have tried installing a new one), which does the things you have laid out in #26. That is, dumps the list of plugin information and dumps the order in which plugins were tested and the reason for failure.

[evamaxfield]

I see this as: "this is the single entry point to using BioIO and if we fail here we should try everything we can to assist them, or tell them to alert us" and if that means a very long error message. So be it haha

[BrianWhitneyAI]

I think there are a few things to try before closing this out.

1. When we report that we think the file isn't supported we should dump the list of plugins currently installed. Not all the extensions but the plugins. This should be a relatively short list and an easy way to alert someone if they forgot to install a plugin before trying to read (I forget dependencies a decent amount of the time).
2. We should link them to the registry table in feature/plugin-registry #62 as a part of the error message. Example: please review our list of known plugins to see if there is a plugin that supports your file.
3. If all else fails, we should prompt them to run something like determine_plugin(file, debug=True) and link them to the bug report page in the case that they do have the plugin installed (and or they have tried installing a new one), which does the things you have laid out in Surface more information during reader/plugin selection #26. That is, dumps the list of plugin information and dumps the order in which plugins were tested and the reason for failure.

I have added 6ae38f3. I see this as a bare minimum so let me know if additional context is needed for this. I did not include a link/prompt to the issues page/determine_plugin(file, debug=True), I think this is too much information for an initial error and would swamp users with too many things. I think striking a balance of letting users know some tools but not regurgaitating all possible information will work a little better here.

[evamaxfield]

Looks good as a first pass! Thanks so much!