Fix use_dual type hints

[Sanjays2402]

Fixes part of #1593 but does not fully close it.

Overview

• Narrow use_dual to bool across the public grid-loading APIs and Grid.from_dataset, matching the documented and implemented contract.
• Add a focused type-hint regression test covering all four signatures.

PR Checklist

General

• An issue is linked created and linked
• Add appropriate labels
• Filled out Overview and Expected Usage (if applicable) sections

Testing

• Adequate tests are created if there is new functionality
• Tests cover all possible logical paths in your function
• Tests are not too basic (such as simply calling a function and nothing else)

Documentation

• [N/A] Docstrings have been added to all new functions
• [N/A] Docstrings have updated with any function changes
• [N/A] Internal functions have a preceding underscore (_) and have been added to docs/internal_api/index.rst
• [N/A] User functions have been added to docs/user_api/index.rst

Examples

• [N/A] Any new notebook examples added to docs/examples/ folder
• [N/A] Clear the output of all cells before committing
• [N/A] New notebook files added to docs/examples.rst toctree
• [N/A] New notebook files added to new entry in docs/gallery.yml with appropriate thumbnail photo in docs/_static/thumbnails/

[Sevans711]

Thank you for these contributions, @Sanjays2402! This looks like a clean fix to the None type hints on the use_dual kwarg, and one good way to test things.

I have a few thoughts/notes before we get this merged into main:

1. Note: this doesn't actually solve the entirety of Type hints allows None for too many parameters #1593, which only used use_dual as an example. In reality, there are many more cases of kwargs which type hint None despite not really handling None internally. Examples include: destination in UxDataArray.difference(); start_index in Grid.from_topology(); and tol in Grid.from_structured(). This is not a complete list of examples where this needs to be solved (it will take more time to generate the complete list). Because of this, I am going to change the "Closes #XXX" phrase to "Fixes part of #XXX but does not fully close it" so that the issue can remain open even after this PR merges.
2. Asking other developers (e.g. @erogluorhan, @rajeeja) do we want this sort of test case for type hinting in general? This test works but looks dependent on type hint spelling, and I'm not sure if it would be ideal to set the expectation of having similar tests for all the other kwargs with this issue and the functions in which they appear. Options include: (A) merge as-is and expect similar tests for all other such kwargs, (B) keep this test but add a comment in the code clarifying it is a "spot check" and not expected for all such kwargs, (C) drop the test and do not worry about testing type hinting, (D) add more comprehensive type hinting checks (mypy/pyright?) to the CI.

Also, out of curiosity, @Sanjays2402 what led you to uxarray? It is always helpful to hear how people find out about the project!

[cmdupuis3]

Yeah, I've been noticing this too, seems like an anti-pattern to allow both None and false to mean the same thing. Maybe it's a legacy API issue?

[Sanjays2402]

Agreed on the scope, "fixes part of #1593" is the accurate framing, use_dual was just the example that surfaced it.

On the test: I'd lean (B). It's spot-check by nature and I share your concern about setting an expectation that every kwarg gets a hand-written type-hint test, that gets unmaintainable fast and the test does key off hint spelling. Happy to add a comment saying as much. If the team would rather go (C) I won't argue, the signature fix stands on its own without it.

Say which way you want it and I'll push.

[Sevans711]

Thank you again for your contributions here, @Sanjays2402. Letting you know, there is some internal discussion happening with other uxarray devs about how people want to proceed in this case. Will provide an update here with decision / reasoning, once that discussion concludes!

[Sanjays2402]

Understood — I will leave this open while the team decides between the spot-check comment, dropping the test, or a broader type-hint check. The four signature fixes are intentionally scoped to this part of #1593; I will wait for that decision before changing the branch.

[Sevans711]

Understood — I will leave this open while the team decides between the spot-check comment, dropping the test, or a broader type-hint check. The four signature fixes are intentionally scoped to this part of #1593; I will wait for that decision before changing the branch.

Sounds good, also thank you for sending a reply here! This was a good reminder for me. I wanted to report back sooner but the discussion didn't lead to a final decision on how to move forward yet. Rather, it seems like the plan will be for @dylannelson to take point on how to address the original issue fully throughout the codebase, and to report back here about how to proceed with this PR after getting a chance to look into it further. Hopefully sometime soon, but it might also be a somewhat lower priority because it is isn't causing any crashes, just confusing type hints.