At the moment, https://docs.python.org/3.10/library/typing.html#typing.NoReturn simply says:

Special type indicating that a function never returns.

In practice, type checkers accept NoReturn as a bottom type in other positions too. We should document this behavior.

I agree.

Plus, I cannot refrain from saying that it is generally quite hard to teach what "NoReturn" is.

I start by explaining what bottom type and void is and then just say that in Python it is called NoReturn. I remember that there was a discussion about Never alias for it.

Jelle, will you please push it? :)

I also agree that documenting this is a great idea. It's already been adopted by large swathes of the typing community for use in this context. The value of having NoReturn act as a "bottom type" is evident. Time to make it official, in my opinion.

Based on feedback here and on typing-sig I'm now leaning towards adding typing.Never along with typing.assert_never. I'll submit a single patch for these as the documentation will be closely linked.

New changeset 243436f by Jelle Zijlstra in branch 'main':
bpo-46475: Add typing.Never and typing.assert_never (GH-30842)
243436f

What is the purpose of the required argument to assert_never()? Regardless of what I pass to this function, the raised exception is "AssertionError: Expected code to be unreachable"

@ptmcg it always throws at runtime; the point is that static typecheckers will verify that the code really is unreachable. See https://docs.python.org/3.11/library/typing.html#typing.assert_never and https://typing.readthedocs.io/en/latest/source/unreachable.html

IIUC the question is why does it have an argument and what effect does it have? (It seems to have none, then why is it required?)

Thank you @gvanrossum , that is what I was asking.

I see. Usually you'd use this function in a place where some variable gets narrowed down to Never. Making it an explicit argument makes it possible to implement the function without any special casing in type checkers, because they already know how to treat Never in an argument position.

We could add a similar function with no arguments that asserts a block is unreachable, but unlike assert_never() it would need to be special cased in type checkers.

We might want to revisit the fact that the error message is always the same. We did that on the basis of security concerns about str() on untrusted input, but I don't find those concerns that convincing, and it's useful to have some representation of the object in the error message.

Security concerns? That seems excessive. Millions of things in the stdlib print the repr() of the thing that unexpectedly failed some check.

Sending a PR shortly to add the asserted value to assert_never()'s error message, and also to link to https://typing.readthedocs.io/en/latest/source/unreachable.html while I'm at it.