Allow py310 style annotations (PEP563) when using from __future__ import annotations

[basnijholt]

This allows one to annotate in Python 3.10 style (PEP563) when from __future__ import annotations is used.

e.g.:

from __future__ import annotations

def f(x: int | None) -> int: pass

will work

[basnijholt]

@agronholm, what do you think about this?

This is relevant for all projects that use pyupgrade and future annotations, where it (for example) updates all Optional[str] to str | None.

[agronholm]

Sure, I will take a look later. I will need this for my own projects too.

[agronholm]

This PR isn't going to work as-is because Python 3.6 is still supported and that future import doesn't work there.

[basnijholt]

Do you have any ideas/suggestions to make it work?

Dropping 3.6 is one solution. Many packages in the scientific Python community follow NEP 29. Even though a package might still support 3.6, I imagine no actively developed package still used 3.6 to build their docs.

[agronholm]

Even though a package might still support 3.6, I imagine no actively developed package still used 3.6 to build their docs.

The PyPI statistics don't support that supposition.

An extra "dummy module" for 3.7+ only could work.

[basnijholt]

Good suggestion, I will try that tomorrow!

[basnijholt]

@agronholm, I have added a dummy module that is tested only for Python ≥ 3.7.

[agronholm]

Maybe you should first make sure the linting checks pass locally?

[basnijholt]

Done. I have also renamed pre-commit-config.sample.yaml -> .pre-commit-config.yaml to make pre-commit work.

Not sure how it would have worked before.

[agronholm]

Done. I have also renamed pre-commit-config.sample.yaml -> .pre-commit-config.yaml to make pre-commit work.

Not sure how it would have worked before.

The idea was that anyone wishing to use pre-commit would have a template, but would not be required to use the exact versions there.

[agronholm]

Umm, yes, it does. It says so in PEP 563 and I have a project that depends on that.

[basnijholt]

The CI is now failing exactly like master is failing.

I can make the appropriate changes to make it pass (if the generated output is OK).

[agronholm]

Please do – although I would like to understand why it failed before this is merged. The same code in master passed some time before, so this is likely due to changes in Sphinx itself.

[basnijholt]

@agronholm, 5065d94 contains the changes required to make the tests pass. Unfortunately, I don't have time to figure out what changed in Sphinx to cause this change.

[basnijholt]

Python 3.10 is still failing in many places, except not in the test I added test_sphinx_output_future_annotations.

[agronholm]

Python 3.10 is still failing in many places, except not in the test I added test_sphinx_output_future_annotations.

Those failures seem to have a singular cause – something involving Union or Optional.

[basnijholt]

I have locally tested my latest changes on Python 3.10, and now it seems like all CI jobs should pass.
In the future, we can probably use some regex to fix some of those changes, but I believe it is good enough now.

[basnijholt]

Because I seem to need approval to run the CI every single time, I have set it up on my fork: https://github.com/basnijholt/sphinx-autodoc-typehints/actions/runs/1345088994.

It now all passes.

[basnijholt]

Ping @agronholm 😃

[agronholm]

Yeah, sorry, I've been meaning to get back to this. I'll take another look tonight.

[agronholm]

Some change requests, some questions.

[gaborbernat]

@basnijholt I've rebased on main, can you please fix the CI, thanks!

[basnijholt]

I'll be AFK for more than a month. @agronholm wanted to check out the remaining failure cases I believe.

[basnijholt]

Thanks for merging this and fixing the tests 🎉😃😄

[gaborbernat]

Yeah, interestingly the future annotation has an extra zero at the end in 3.8 or later, see python/cpython@5055c27#diff-eb46a68cfb368cc943fe36ad91dba3692682ab4454221fefd6abab8757682ab0