Add a _typeshed.pyi file and a PathLike alias

This PR only replaces a few potential places where this alias could be
used.

Closes: python#4131

stdlib/2and3/_typeshed.pyi

@@ -0,0 +1,29 @@
+# Utility types for typeshed
+
+# This module contains various common types to be used by typeshed. The
+# module and its types do not exist at runtime. You can use this module
+# outside of typeshed, but no API stability guarantees are made. To use
+# it in implementation (.py) files, the following construct must be used:
+#
+# from typing import TYPE_CHECKING
+# if TYPE_CHECKING:
+# from _typeshed import ...
+#
+# On Python versions < 3.10 and if "from __future__ import type_checking" 
+# is not used, types from this module must be quoted.
+
+import sys
+from typing import Text
+
+
+# PathType can be used in places where starting with Python 3.6 a path
+# can be used instead of a string. The alias is generic over the string
+# type and should be used as PathType[str], PathType[Text], or
+# PathType[bytes], where only on of these types is allowed, or as
+# PathType[Union[Text, bytes]], PathType[Union[str, bytes]], or
+# PathType[AnyStr] when both bytes and str (or unicode) are supported.
+if sys.version_info >= (3, 6):
+ from os import PathLike
+ PathType = Union[_T, PathLike[_T]]
+else:
+ PathType = _T

third_party/2and3/atomicwrites/__init__.pyi

@@ -1,11 +1,8 @@
 import sys
 from typing import Any, AnyStr, Callable, ContextManager, Generic, IO, Optional, Text, Type, Union
+from _typing import PathType
 
-if sys.version_info >= (3, 6):
- from os import PathLike
- _Path = Union[str, bytes, PathLike[str], PathLike[bytes]]
-else:
- _Path = Union[Text, bytes]
+_Path = PathType[Union[Text, bytes]]
 
 def replace_atomic(src: AnyStr, dst: AnyStr) -> None: ...
 def move_atomic(src: AnyStr, dst: AnyStr) -> None: ...

third_party/2and3/jinja2/utils.pyi

@@ -1,5 +1,6 @@
 import sys
 from typing import Any, Callable, IO, Iterable, Optional, Protocol, Text, TypeVar, Union
+from _typeshed import PathType
 
 from markupsafe import Markup as Markup, escape as escape, soft_unicode as soft_unicode
 
@@ -13,12 +14,6 @@ if sys.version_info >= (3, 8):
 else:
  _True = bool
 
-if sys.version_info >= (3, 6):
- from builtins import _PathLike
- _PathType = Union[bytes, Text, _PathLike]
-else:
- _PathType = Union[bytes, Text]
-
 _CallableT = TypeVar("_CallableT", bound=Callable[..., Any])
 
 class _ContextFunction(Protocol[_CallableT]):
@@ -42,7 +37,7 @@ def select_autoescape(enabled_extensions: Iterable[str] = ..., disabled_extensio
 def consume(iterable: Iterable[object]) -> None: ...
 def clear_caches() -> None: ...
 def import_string(import_name: str, silent: bool = ...) -> Any: ...
-def open_if_exists(filename: _PathType, mode: str = ...) -> Optional[IO[Any]]: ...
+def open_if_exists(filename: PathType[Union[Text, bytes]], mode: str = ...) -> Optional[IO[Any]]: ...
 def object_type_repr(obj: object) -> str: ...
 def pformat(obj: object, verbose: bool = ...) -> str: ...
 def urlize(text: Union[Markup, Text], trim_url_limit: Optional[int] = ..., rel: Optional[Union[Markup, Text]] = ..., target: Optional[Union[Markup, Text]] = ...) -> str: ...

third_party/2and3/toml.pyi

@@ -1,16 +1,13 @@
 from typing import Any, IO, List, Mapping, MutableMapping, Optional, Protocol, Text, Type, Union
+from _typeshed import PathType
 import datetime
 import sys
 
 if sys.version_info >= (3, 4):
  import pathlib
- if sys.version_info >= (3, 6):
- import os
- _PathLike = Union[Text, pathlib.PurePath, os.PathLike]
- else:
- _PathLike = Union[Text, pathlib.PurePath]
+ _PathLike = Union[PathType[str], pathlib.PurePath]
 else:
- _PathLike = Text
+ _PathLike = PathType[Text]
 
 class _Writable(Protocol):
  def write(self, obj: str) -> Any: ...