gh-132941: Soft deprecate various typing classes

[srittau]

Also use the newer type var syntax in a few places.

This PR does not deprecated TypeVar, ParamSpec, and TypeVarTuple
constructors, as it is sometimes necessary to create type vars using the
explicit syntax. (For example to create a shared type var like AnyStr or
to use it as a type form.)

Cc @JelleZijlstra

• Issue: typing docs: Use soft deprecation #132941

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33712809 | 📁 Comparing f867aeb against main (771abfe)

  🔍 Preview build  

8 files changed · ± 8 modified

± Modified

• deprecations/index.html
• deprecations/soft-deprecations.html
• library/csv.html
• library/types.html
• library/typing.html
• library/warnings.html
• whatsnew/3.15.html
• whatsnew/changelog.html

[sobolevn]

Great stuff!

[sobolevn]

Maybe we should suggest using |?

[JelleZijlstra]

The | syntax creates instances of typing.Union, which types.UnionType is now an alias for (as the line before indicates).

I think this is clear enough when combined with the previous line.

[srittau]

I think both would be beneficial:

Use the ``X | Y`` syntax to create ``Union`` instances and :class:typing.Union for all other purposes.

[JelleZijlstra]

I think when I tried to do this during the PEP 695 implementation it wasn't possible because Sphinx couldn't parse the syntax, definitely supportive of changing this.

[srittau]

This seems fine now:

• https://cpython-previews--154480.org.readthedocs.build/en/154480/library/typing.html#typing.Type
• https://cpython-previews--154480.org.readthedocs.build/en/154480/library/typing.html#typing.MutableSequence

Although I missed a few instances, which I will add.

[StanFromIreland]

Is it soft-deprecated or deprecated?

Suggested change

	.. deprecated:: 3.16
	.. soft-deprecated:: 3.16

If it's soft deprecated, also add them to the relevant file in the deprecations docs. If it's regular-deprecated, please schedule removal for a version.