Mention typing.Never used to type hint empty containers

[andresdelfino]

I saw this behavior from mypy, but I guessed it was safe to assume it is an intended semantic.

---

📚 Documentation preview 📚: https://cpython-previews--143876.org.readthedocs.build/

[AlexWaygood]

Hmm, why would a user ever want to create a list that must always remain empty? Isn't the whole point of a list, as opposed to a tuple, that lists are mutable? :-)

It's true that it's illegal to append anything to a list if the list has type list[Never]. But I'm not sure that it's worth taking up space in the typing-module docs to say that. If mypy has inferred an empty list as list[Never] and is then emitting diagnostics when you try to append items to the list, I'd say that it's mypy's responsibility there to improve their diagnostic, rather than something we should add to the typing-module docs.

[andresdelfino]

At least for me it's confusing to read about the different uses for Never and no mention of the one mypy is complaining about. I'd say documenting any semantic that is considered correct from the standard library POV is helpful, regardless of if a user will actually type hint anything with it. I'd agree that mypy should document this if list[Never] was a mypy-specific non-standard way for writing this.

[AlexWaygood]

I believe mypy is the only major type checker that infers Never by default for unannotated container literals (there was some recent discussion on this here). Having inferred list[Never] for an empty list, it is then correct to complain if you try to append anything to that list. But whether that is the most user-friendly type for mypy to infer in that situation is another question (and something you'd have to take up with mypy).

[JelleZijlstra]

This is if anything a very niche use case and I don't think it needs to be covered in the CPython documentation. It could be mentioned in a more in-depth guide on typing.python.org.

[AlexWaygood]

Thanks for the PR @andresdelfino but I think we'll decline this one. There's a lot of value in keeping these docs relatively concise, and it sounds like Jelle and I are aligned in thinking that this doesn't quite meet the bar :-)