Add helpful hint error message if optional dependencies not yet installed.

[Sevans711]

Addresses part of #1224 #1225 but does not fully close them.

Overview

Adds _raise_hint_if_optional_deps_missing which raises helpful hint upon trying but failing to import optional dependencies due to them not yet being installed.

PR Checklist

General

• An issue is created and linked
• Added appropriate labels (if your uxarray repo permissions allow it)
• Filled out Overview and Expected Usage (if applicable) sections

Testing & Benchmarking

• Adequate tests are created if there is new functionality
• Tests are not too basic (such as simply calling a function and nothing else)
• Tests cover all major paths in your new functions
• [N/A] If this PR could affect performance, ran ASV benchmarks and confirmed they show expected behavior (add a new benchmark if necessary)

Documentation

• Docstrings have been added to all new functions
• Docstrings have been updated with any function changes
• [N/A] User (public) functions have been added to docs/api.rst
• Internal (private) function names start with an underscore (_)

AI Disclosure

AI Usage: GitHub Copilot inline code suggestions, some discussion with Claude.

• I take responsibility for all AI-generated content in my PR.
• I have tested all AI-generated content in my PR.

[rajeeja]

One unreachable branch, see inline.

[rajeeja]

Unreachable — the assert above guarantees len(extras) >= 2, so this likely wants >= 2 not == 0. Means a cartopy-only miss suggests [all] instead of [geo] or [viz].

[Sevans711]

Thank you for looking into this! Commit 0f638de fixes this, makes slight improvements to message readability in case of many extras, and adds a test to the CI with expectations about the error messages. That test would have crashed before this fix, and it hard-codes the expected error messages for clarity and readability.

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB

[cmdupuis3]

This pattern looks like it will be difficult to maintain consistently throughout the codebase as we develop it. If we're going to have this, there should definitely be some kind of linting for this so we'll know in the PRs if these are done correctly, and provide an easy way to fix it.

[Sevans711]

Thank you for looking into this! Commit c78f80a adds a test to the pytest test suite which should fail if anyone defines a function that imports optional dependencies without all of them being properly included in a call to _raise_hint_if_optional_deps_missing(). The failure mode includes a helpful message which should make it clear enough on how to fix it.

(It also raises clear warnings if bonus optional dependencies are being included, unnecessarily, inside a call to the raise_hint... function.)

I chose to implement this as a pytest test instead of full-blown linting because I have a suspicion that this will be easier to maintain (e.g., I'm not yet familiar with building customized linting algorithms). There's no "fix it for me" button like a proper linting algorithm might provide, but I think that this should still be sufficient? I believe it grants the most important benefits of ensuring this pattern gets maintained, and providing clear instructions for how to fix if it if needed.

[cmdupuis3]

Eh, it's better, but the "fix it for me" button is my ideal in this case.