[pnuu]

I saw RtD builds failing on #759 and asked Claude to check the failures. Here's the fix.

hashlib._Hash only existed in typeshed stubs and is not available at runtime, so sphinx-autodoc-typehints could not resolve the forward references and emitted warnings that fail the Read the Docs build. Annotate with _hashlib.HASH, imported under TYPE_CHECKING, instead.

Also remove the ineffective autodoc_mock_imports entry for hashlib._Hash, as mocking only applies to modules, not attributes.

• Closes #xxxx
• Tests added
• Tests passed
• Fully documented

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.92%. Comparing base (4a46786) to head (c6103a9).
⚠️ Report is 17 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #760      +/-   ##
==========================================
+ Coverage   93.90%   93.92%   +0.02%     
==========================================
  Files          89       89              
  Lines       13924    13976      +52     
==========================================
+ Hits        13075    13127      +52     
  Misses        849      849              

Flag	Coverage Δ
unittests	93.92% <100.00%> (+0.02%)	⬆️

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

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[djhoese]

I could have sworn I fixed this already. Maybe it is in an unmerged PR or another package. The sphinx-autodoc-typehints package has seen a lot of changes around TYPE_CHECKING guards lately (see Satpy's previous documentation build failures) so I'm glad this works here now. The hashlib stuff...

Google says that hashlib._hashlib.HASH is the low level C object and should maybe be avoided for static type checking. The hashlib._Hash is the recommended way of doing this. Does moving the _Hash import into TYPE_CHECKING not work?

[djhoese]

https://stackoverflow.com/a/73638955

[pnuu]

I really don't understand how typing should work, so lets go with trial and error. The if TYPE_CHECKING block might be redundant because the same import is already done, but maybe there's some magic that still needs this so I left it.

Oh, but with this version the RtD build is failing again with the original error (warning):

/home/docs/checkouts/readthedocs.org/user_builds/pyresample/conda/760/lib/python3.12/site-packages/pyresample/future/resamplers/resampler.py:40: WARNING: Cannot resolve forward reference in type annotations of "pyresample.future.resamplers.resampler.hash_dict" (module pyresample.future.resamplers.resampler): module 'hashlib' has no attribute '_Hash' [sphinx_autodoc_typehints.forward_reference]

[pnuu]

With new try also a failure:

home/docs/checkouts/readthedocs.org/user_builds/pyresample/conda/760/lib/python3.12/site-packages/pyresample/geometry.py:0: WARNING: Failed guarded type import in 'pyresample.geometry': ModuleNotFoundError("No module named 'hashlib._Hash'; 'hashlib' is not a package") [sphinx_autodoc_typehints.guarded_import]
/home/docs/checkouts/readthedocs.org/user_builds/pyresample/conda/760/lib/python3.12/site-packages/pyresample/future/resamplers/resampler.py:176: WARNING: Failed guarded type import in 'pyresample.future.resamplers.resampler': ModuleNotFoundError("No module named 'hashlib._Hash'; 'hashlib' is not a package") [sphinx_autodoc_typehints.guarded_import]

Running mypy yresample/future/resamplers/resampler.py pyresample/geometry.py just complains about other things (why are these not failures?!):

pyresample/geometry.py:56: error: Cannot assign to a type  [misc]
pyresample/geometry.py:56: error: Incompatible types in assignment (expression has type "type[ndarray[_ShapeT_co, _DTypeT_co]]", variable has type "type[DataArray]")  [assignment]
pyresample/geometry.py:61: error: Incompatible types in assignment (expression has type "None", variable has type Module)  [assignment]
pyresample/future/resamplers/resampler.py:30: error: Incompatible types in assignment (expression has type "None", variable has type Module)  [assignment]
Found 4 errors in 2 files (checked 2 source files)

I'll go back to the first (wrong) iteration that Claude gave me and actually worked.

[djhoese]

So one thing is I think the "real" import is supposed to be hashlib._hashlib.HASH but it is all just old school CPython weirdness (hashlib.py imports _hashlib.*.so - a C extension). So maybe importing _hashlib isn't entirely wrong.

The other thing is I don't think sphinx-autodoc-typehints handles imports the same way as type checkers necessarily. I've been doing a lot of bug reporting to sphinx-autodoc-typehints for the last couple versions so it may be worth asking Claude to try the last couple releases of that extension and seeing how it changes the different approaches here. It is possible a recent change broke this.

[djhoese]

Oh there have been a ton of releases of sphinx-autodoc-typehints in the last month. Sounds like this might be a bug report if it works in an older version.