Reorganization of internal utilities and adding type hints for internal utils

[freemansw1]

As part of my proposed efforts to add in type hints as a step toward xarray support (see my comment here: #143 (comment)), I've gone through and added type hints to the internal utility functions.

I've also gone through and reorganized/cleaned up the internal utilities, breaking them into multiple different files, including specifically breaking off the Iris utilities into their own file for future deprecation/removal.

Holding as a draft until 1.5.1 is released.

• Have you followed our guidelines in CONTRIBUTING.md?
• Have you self-reviewed your code and corrected any misspellings?
• Have you written documentation that is easy to understand?
• Have you written descriptive commit messages?
• Have you added NumPy docstrings for newly added functions?
• Have you formatted your code using black?
• If you have introduced a new functionality, have you added adequate unit tests?
• Have all tests passed in your local clone?
• If you have introduced a new functionality, have you added an example notebook?
• Have you kept your pull request small and limited so that it is easy to review?
• Have the newest changes from this branch been merged?

[codecov]

Codecov Report

Attention: 14 lines in your changes are missing coverage. Please review.

Comparison is base (85f8f3a) 56.35% compared to head (689e862) 56.55%.

Additional details and impacted files

@@              Coverage Diff              @@
##           RC_v1.5.x     #341      +/-   ##
=============================================
+ Coverage      56.35%   56.55%   +0.20%     
=============================================
  Files             16       19       +3     
  Lines           3384     3416      +32     
=============================================
+ Hits            1907     1932      +25     
- Misses          1477     1484       +7     

Flag	Coverage Δ
unittests	56.55% <85.56%> (+0.20%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files	Coverage Δ
tobac/utils/internal/__init__.py	100.00% <100.00%> (ø)
tobac/utils/internal/basic.py	87.23% <87.50%> (ø)
tobac/utils/internal/xarray_utils.py	71.42% <71.42%> (ø)
tobac/utils/internal/iris_utils.py	88.00% <88.00%> (ø)

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[w-k-jones]

Looks like the readthedocs build is failing due to using collections.Callable rather than collections.abc.Callable. Personally I've used typing.Callable before, but I have no preference for which is best

[freemansw1]

Looks like the readthedocs build is failing due to using collections.Callable rather than collections.abc.Callable. Personally I've used typing.Callable before, but I have no preference for which is best

I was already using typing.Callable and not collections.Callable. I've switched to explicitly using typing.Callable instead of from typing import Callable to see if that fixes things.

I'm not entirely sure why readthedocs required me to update the .readthedocs.yml in the first place, given that it otherwise works on our other PRs.

[w-k-jones]

Looks like the readthedocs build is failing due to using collections.Callable rather than collections.abc.Callable. Personally I've used typing.Callable before, but I have no preference for which is best

I was already using typing.Callable and not collections.Callable. I've switched to explicitly using typing.Callable instead of from typing import Callable to see if that fixes things.

I'm not entirely sure why readthedocs required me to update the .readthedocs.yml in the first place, given that it otherwise works on our other PRs.

Oh, I see the issue now. It's not in our code, but in sphinx. python 3.10 moved collections.Callble to collections.abc.Callable. Maybe for now setting the config to use python 3.9 will allow the docs to build while we figure out a better solution

[w-k-jones]

having utils.general and utils.internal.general_internal is a little confusing, but I can't think of anything better to call it...

[JuliaKukulies]

Maybe utils.internal.basic or utils.internal.basic ?

[freemansw1]

Agreed. I've renamed this now.

[freemansw1]

@JuliaKukulies @w-k-jones I've renamed general_internal.py to basic.py; let me know if that works for you, and we can get this merged.

[JuliaKukulies]

@JuliaKukulies @w-k-jones I've renamed general_internal.py to basic.py; let me know if that works for you, and we can get this merged.

Perfect, happy for this to be merged!