I can think of two downsides to using __annotations__ for this:

1) Obviously contextlib itself isn't going to add any kind of annotation in any versions before 3.7, but third-party projects might (like contextlib2, say). And these projects have been known to be used on Python versions that don't have __annotations__ support. At the moment I personally don't have to care about this because sphinxcontrib-trio doesn't support anything before 3.5, but I suspect this will eventually change. (E.g. sphinx has expressed some interest in having these changes upstreamed.) So this would mean that we'd still need some other ad hoc mechanism to use when running on old Pythons, and have to check for both that and the __annotations__. But that's probably doable, so eh. It'd be helpful if contextlib2 could join in on whatever protocol, though.

2) sphinxcontrib-trio actually interacts very poorly with __annotations__ right now [1]. But I mean, I need to figure out how to fix this anyway, so... not really your problem :-).

Neither of these downsides seems very compelling :-). So I guess contextlib should add some appropriate __annotations__, and *maybe* also add something like __returns_contextmanager__ = True if that's useful to maintain consistency with contextlib2 or similar?

(Wasn't there some discussion about keeping type hints out of the stdlib for now? is this likely to ruffle any figures on those grounds?)

[1] https://github.com/python-trio/sphinxcontrib-trio/issues/4