Typing Feature Flags

This idea is similar to stricter stubs idea, but a bit more general and focused more on new typing features. Typing features are produced at pretty quick pace. We're currently producing several typing peps each year. Paramspec, dataclasses, variadic, literal string, positional only, and so on. It looks like pace of a couple typing peps will continue for awhile.

We currently have multiple major type checkers. As new typing features are proposed, support for those features will appear in each type checker at different times. For typeshed and libraries that want to be typed and could gain type safety from using newer features, there's a problem of using too new feature may cause some user's experience to worsen if the type checker they use lacks support for that feature. So currently it looks like typeshed has a checklist of PEP accepted + support by each major type checker.

My proposal is intruding feature flags corresponding to major new typing features. We could have several bool constants like,

class TypingFeatures:
  PARAMSPEC_SUPPORTED = ...
  VARIADIC_SUPPORTED = ...
  LITERAL_STRING_SUPPORTED = ...

in typing.py/typing_extensions.py and then both stubs/libraries could use,

if TypingFeatures.PARAMSPEC_SUPPORTED:
  def contextmanager(func: Callable[_P, Iterator[_T]]) -> Callable[_P, ContextManager[_T]]: ...
else:
  def contextmanager(func: Callable[..., Iterator[_T]]) -> Callable[..., ContextManager[_T]]: ...

shortly after PEP/typing feature is accepted. The semantics of TypingFeatures.PARAMSPEC_SUPPORTED would be like TYPE_CHECKING except each type checker will define each feature as True/False.

I think this mainly applies to typing features that allow additional safety/make system more powerful. Features that only improve readability while important would not have value with a feature flag because while,

alias1 = int | str

is better then,

alias1 = Union[int, str]

but using a feature flag here makes it even less readable for no gain,

if TypingFeatures.UNION_OPERATOR:
  alias1 = int | str
else:
  alias1 = Union[int, str]

I'm mostly thinking of this for new/recent PEPs. The one other feature I'd be interested in a flag for is recursive types as it's very popular requested feature that different type checkers have different support for.

Start by reading this proposal alongside the linked stricter stubs issue, then inspect how typing.py and typing_extensions.py currently expose feature-related constants such as TYPE_CHECKING. The issue needs a settled design for feature flags and their semantics before implementation can be considered complete.