Add typing_extensions.utils

.flake8

@@ -10,6 +10,7 @@ ignore =
  # consistency with mypy
  W504
 exclude =
+ .venv*,
  # tests have more relaxed formatting rules
  # and its own specific config in .flake8-tests
- src/test_typing_extensions.py,
+ src/test_typing_extensions,

.github/workflows/ci.yml

@@ -36,7 +36,7 @@ jobs:
  # Be wary of running `pip install` here, since it becomes easy for us to
  # accidentally pick up typing_extensions as installed by a dependency
  cd src
- python -m unittest test_typing_extensions.py
+ python -m unittest test_typing_extensions
 
  linting:
  name: Lint
@@ -61,4 +61,4 @@ jobs:
  run: flake8
 
  - name: Lint tests
- run: flake8 --config=.flake8-tests src/test_typing_extensions.py
+ run: flake8 --config=.flake8-tests src/test_typing_extensions

CHANGELOG.md

@@ -1,8 +1,24 @@
-# Unreleased
+# UNRELEASED
 
 - Add `typing_extensions.NamedTuple`, allowing for generic `NamedTuple`s on
  Python <3.11 (backport from python/cpython#92027, by Serhiy Storchaka). Patch
  by Alex Waygood (@AlexWaygood).
+- Add the `typing\_extensions.utils` module, which contains useful protocols
+ and type aliases that are not scheduled for inclusion in `typing`.
+ - `SupportsAnext`
+ - `SupportsDivMod`
+ - `SupportsGetItem`
+ - `SupportsNext`
+ - `SupportsRDivMod`
+ - `SupportsTrunc`
+ - `SupportsKeys`
+ - `SupportsItems`
+ - `SupportsKeysAndGetItem`
+ - `SupportsRead`
+ - `SupportsReadline`
+ - `SupportsWrite`
+ - `StrPath`
+ - `BytesPath`
 
 # Release 4.2.0 (April 17, 2022)
 

README.md

@@ -144,4 +144,4 @@ These types are only guaranteed to work for static type checking.
 ## Running tests
 
 To run tests, navigate into the appropriate source directory and run
-`test_typing_extensions.py`.
+`test_typing_extensions/__init__.py`.

src/test_typing_extensions.py → src/test_typing_extensions/__init__.py

@@ -30,6 +30,9 @@
 from typing_extensions import clear_overloads, get_overloads, overload
 from typing_extensions import NamedTuple
 
+# Importing so that the tests are run.
+from .utils import dummy # noqa F401
+
 # Flags used to mark tests that only apply after a specific
 # version of the typing module.
 TYPING_3_8_0 = sys.version_info[:3] >= (3, 8, 0)
@@ -2886,7 +2889,7 @@ def test_typing_extensions_defers_when_possible(self):
 
  def test_typing_extensions_compiles_with_opt(self):
  file_path = os.path.join(os.path.dirname(os.path.realpath(__file__)),
- 'typing_extensions.py')
+ '../typing_extensions/__init__.py')
  try:
  subprocess.check_output(f'{sys.executable} -OO {file_path}',
  stderr=subprocess.STDOUT,

src/test_typing_extensions/utils.py

@@ -0,0 +1,5 @@
+# We just import the utils module to check for syntax or import problems.
+import typing_extensions.utils # noqa F401
+
+def dummy():
+ pass

src/typing_extensions/utils.py

@@ -0,0 +1,99 @@
+"""
+Protocols and type aliases that are not scheduled for inclusion in typing.
+"""
+
+from os import PathLike
+from typing import AbstractSet, Awaitable, Iterable, Tuple, TypeVar, Union
+from typing_extensions import Protocol, TypeAlias
+
+_T_co = TypeVar("_T_co", covariant=True)
+_T_contra = TypeVar("_T_contra", contravariant=True)
+_KT = TypeVar("_KT")
+_KT_co = TypeVar("_KT_co", covariant=True)
+_KT_contra = TypeVar("_KT_contra", contravariant=True)
+_VT_co = TypeVar("_VT_co", covariant=True)
+
+#
+# Protocols for dunder methods
+#
+
+
+class SupportsAnext(Protocol[_T_co]):
+ def __anext__(self) -> Awaitable[_T_co]:
+ ...
+
+
+class SupportsDivMod(Protocol[_T_contra, _T_co]):
+ def __divmod__(self, __other: _T_contra) -> _T_co:
+ ...
+
+
+class SupportsGetItem(Protocol[_KT_contra, _VT_co]):
+ def __getitem__(self, __k: _KT_contra) -> _VT_co:
+ ...
+
+
+class SupportsNext(Protocol[_T_co]):
+ def __next__(self) -> _T_co:
+ ...
+
+
+class SupportsRDivMod(Protocol[_T_contra, _T_co]):
+ def __rdivmod__(self, __other: _T_contra) -> _T_co:
+ ...
+
+
+class SupportsTrunc(Protocol):
+ def __trunc__(self) -> int:
+ ...
+
+
+#
+# Mapping-like protocols
+#
+
+
+class SupportsKeys(Protocol[_KT_co]):
+ def keys(self) -> Iterable[_KT_co]:
+ ...
+
+
+class SupportsItems(Protocol[_KT_co, _VT_co]):
+ def items(self) -> AbstractSet[Tuple[_KT_co, _VT_co]]:
+ ...
+
+
+class SupportsKeysAndGetItem(Protocol[_KT, _VT_co]):
+ def keys(self) -> Iterable[_KT]:
+ ...
+
+ def __getitem__(self, __k: _KT) -> _VT_co:
+ ...
+
+
+#
+# I/O protocols
+#
+
+
+class SupportsRead(Protocol[_T_co]):
+ def read(self, __length: int = ...) -> _T_co:
+ ...
+
+
+class SupportsReadline(Protocol[_T_co]):
+ def readline(self, __length: int = ...) -> _T_co:
+ ...
+
+
+class SupportsWrite(Protocol[_T_contra]):
+ def write(self, __s: _T_contra) -> object:
+ ...
+
+
+#
+# Path aliases
+#
+
+StrPath: TypeAlias = Union[str, "PathLike[str]"]
+BytesPath: TypeAlias = Union[bytes, "PathLike[bytes]"]