Examples shouldn't use typing_extensions imports for stable typing features

[smheidrich]

Description

There are a few code examples in the docs which import things from typing_extensions that are by now available in Python's typing standard library module:

List

typing/docs/guides/unreachable.rst

Line 57 in 3149e8c

from typing_extensions import Never

typing/docs/reference/generics.rst

Line 655 in 3149e8c

from typing_extensions import ParamSpec

... and 4 more occurrences in reference/generics.rst.

typing/docs/reference/protocols.rst

Line 75 in 3149e8c

from typing_extensions import Protocol

... and 4 more occurrences in reference/protocols.rst.

typing/docs/reference/quality.rst

Line 43 in 3149e8c

from typing_extensions import assert_type

It probably makes sense to use typing imports for all of these instead, possibly with the typing_extensions alternative mentioned.

How to fix?

What is the policy for these? Should they just be replaced with bare typing imports or something more like

from typing import Protocol # or from typing_extensions for Python < 3.8

?
I haven't seen the latter in any of the other imports, which just import from typing without comment (EDIT: at least not in the code itself, but usually it is mentioned as an alternative for older versions somewhere around the code), but who knows...

[JelleZijlstra]

Maybe import them from typing_extensions until they're in typing in all supported versions (i.e., currently 3.9+)?

[smheidrich]

@JelleZijlstra Hmm that doesn't seem to be the current rule, at least not universally: E.g. the code examples in the Type Narrowing guide import TypeIs from typing despite it having been introduced in Python 3.13, same for Self (3.11) in the Generics reference.

But in both cases there is prose / an info box somewhere near the example to explain that it can be imported from typing_extensions in older Python versions, so maybe that's the rule?

[srittau]

Personally, I prefer to use typing in examples when a feature has been released in a stable version of Python, as that is the canonical location. Users should be smart enough to replace typing with typing_extensions when required.

[smheidrich]

So maybe the best of both worlds would be:

• Features available in all supported Python versions (3.9+) are just imported from typing and that's it.
• Features not yet available in all supported Python versions are imported from typing in the code examples but get an infobox (or some prose if it fits better) about needing to be imported from typing_extensions if the Python version is too old.

I've changed the PR accordingly.