gh-117492: Clarify documentation of typing.Never

[nineteendo]

• Issue: typing.NoReturn and typing.Never are somewhat unclear #117492

---

📚 Documentation preview 📚: https://cpython-previews--117678.org.readthedocs.build/en/117678/library/typing.html#typing.Never

[AlexWaygood]

I'm definitely going to oppose deprecating NoReturn, sorry! Perhaps if we were inventing it from scratch we wouldn't give it that name, but I haven't seen anything that would justify the huge disruption for users that would be caused by a deprecation

[bedevere-app]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[nineteendo]

OK, but if we keep it, we should say that NoReturn is preferred for return types or that it's kept for backwards compatibility and won't be removed. But the latter kind of sounds like deprecation to me, which you don't want.

[nineteendo]

Alex, I have made the requested changes; please review again, but what do we do then instead? Opinions seem to be somewhat divided.

[bedevere-app]

Thanks for making the requested changes!

@AlexWaygood: please review the changes made to this pull request.

No longer proposes deprecation

[AlexWaygood]

I concur with Jelle

[nineteendo]

I've removed the style suggestion, but just to clarify, this still holds right?

NoReturn can also be used as a bottom type, a type that has no values. Starting in Python 3.11, the Never type should be used for this concept instead.

So, you shouldn't do this in 3.11 (if you're not aiming for backwards compatibility):

from typing import NoReturn

def never_call_me(arg: NoReturn) -> None:
    pass

[nineteendo]

Sorry for my impatience, but do we merge the documentation of Never & NoReturn or is it clear now?
I would like to finish this pull request.

[JelleZijlstra]

I'll take a look soon. I might indeed want to document the two together.

[wyattscarpenter]

By the way, @nineteendo, thanks for taking charge of this concern and making a pull request. I might have done it myself eventually, but concluded I wasn't yet up to the task given the ambiguous nature of the subject matter. So, thanks!

[nineteendo]

I am afraid it will take at least until May 16 for this to be reviewed (1 month before pinging the issue + 1 week waiting for a response). @JelleZijlstra seems to be quite busy. https://devguide.python.org/getting-started/pull-request-lifecycle/#reviewing

[JelleZijlstra]

I pushed some changes:

• There is (conceptually) only a single bottom type; Never and NoReturn both represent that single conceptual type.
• Mention the use as a return type case first, as it is by far more common in user code.
• Mention common examples of functions that would use Never in their annotations.
• Mention that the two are equivalent without unnecessary further verbiage.

I'll give other maintainers some time for a review.

[nineteendo]

Thanks for taking some time, this looks a lot cleaner.

[wyattscarpenter]

Thanks for your work, @JelleZijlstra; it looks great.

[miss-islington-app]

Thanks @nineteendo for the PR, and @JelleZijlstra for merging it 🌮🎉.. I'm working now to backport this PR to: 3.12.
🐍🍒⛏🤖

[bedevere-app]

GH-118547 is a backport of this pull request to the 3.12 branch.