Merge branch 'main' into extra

Author: JelleZijlstra

.github/workflows/ci.yml

@@ -62,7 +62,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           allow-prereleases: true
@@ -85,7 +85,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: "3"
           cache: "pip"
@@ -122,7 +122,7 @@ jobs:
       issues: write
 
     steps:
-      - uses: actions/github-script@v6
+      - uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |

.github/workflows/package.yml

@@ -23,7 +23,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: 3
 
@@ -53,7 +53,7 @@ jobs:
       - uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: 3
 

.github/workflows/third_party.yml

@@ -100,7 +100,7 @@ jobs:
         with:
           path: typing-extensions-latest
       - name: Setup Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install typing_inspect test dependencies
@@ -143,7 +143,7 @@ jobs:
         with:
           path: typing-extensions-latest
       - name: Setup Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           allow-prereleases: true
@@ -187,7 +187,7 @@ jobs:
         with:
           path: typing-extensions-latest
       - name: Setup Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           allow-prereleases: true
@@ -231,7 +231,7 @@ jobs:
         with:
           path: typing-extensions-latest
       - name: Setup Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Configure git for typed-argument-parser tests
@@ -282,7 +282,7 @@ jobs:
         with:
           path: typing-extensions-latest
       - name: Setup Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
           allow-prereleases: true
@@ -328,7 +328,7 @@ jobs:
         with:
           path: typing-extensions-latest
       - name: Setup Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install pdm for cattrs
@@ -377,7 +377,7 @@ jobs:
       issues: write
 
     steps:
-      - uses: actions/github-script@v6
+      - uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           script: |

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 - Add support for PEP 728, making `__extra__` a reserved key for TypedDict.
   Patch by Zixuan James Li.
+- Add support for PEP 742, adding `typing_extensions.TypeIs`. Patch
+  by Jelle Zijlstra.
+- Drop runtime error when a read-only `TypedDict` item overrides a mutable
+  one. Type checkers should still flag this as an error. Patch by Jelle
+  Zijlstra.
 - Speedup `issubclass()` checks against simple runtime-checkable protocols by
   around 6% (backporting https://github.com/python/cpython/pull/112717, by Alex
   Waygood).

doc/index.rst

@@ -350,6 +350,12 @@ Special typing primitives
 
    See :py:data:`typing.TypeGuard` and :pep:`647`. In ``typing`` since 3.10.
 
+.. data:: TypeIs
+
+   See :pep:`742`. Similar to :data:`TypeGuard`, but allows more type narrowing.
+
+   .. versionadded:: 4.10.0
+
 .. class:: TypedDict(dict, total=True)
 
    See :py:class:`typing.TypedDict` and :pep:`589`. In ``typing`` since 3.8.

src/test_typing_extensions.py

@@ -36,7 +36,7 @@
 from typing_extensions import TypeVarTuple, Unpack, dataclass_transform, reveal_type, Never, assert_never, LiteralString
 from typing_extensions import assert_type, get_type_hints, get_origin, get_args, get_original_bases
 from typing_extensions import clear_overloads, get_overloads, overload
-from typing_extensions import NamedTuple
+from typing_extensions import NamedTuple, TypeIs
 from typing_extensions import override, deprecated, Buffer, TypeAliasType, TypeVar, get_protocol_members, is_protocol
 from typing_extensions import Doc
 from _typed_dict_test_helper import Foo, FooGeneric, VeryAnnotated
@@ -3553,7 +3553,8 @@ def test_basics_functional_syntax(self):
     @skipIf(sys.version_info < (3, 13), "Change in behavior in 3.13")
     def test_keywords_syntax_raises_on_3_13(self):
         with self.assertRaises(TypeError):
-            Emp = TypedDict('Emp', name=str, id=int)
+            with self.assertWarns(DeprecationWarning):
+                Emp = TypedDict('Emp', name=str, id=int)
 
     @skipIf(sys.version_info >= (3, 13), "3.13 removes support for kwargs")
     def test_basics_keywords_syntax(self):
@@ -4142,13 +4143,18 @@ class Child2(Base2):
         self.assertEqual(Child1.__readonly_keys__, frozenset({'a'}))
         self.assertEqual(Child1.__mutable_keys__, frozenset({'b'}))
 
-    def test_cannot_make_mutable_key_readonly(self):
+    def test_make_mutable_key_readonly(self):
         class Base(TypedDict):
             a: int
 
-        with self.assertRaises(TypeError):
-            class Child(Base):
-                a: ReadOnly[int]
+        self.assertEqual(Base.__readonly_keys__, frozenset())
+        self.assertEqual(Base.__mutable_keys__, frozenset({'a'}))
+
+        class Child(Base):
+            a: ReadOnly[int]  # type checker error, but allowed at runtime
+
+        self.assertEqual(Child.__readonly_keys__, frozenset({'a'}))
+        self.assertEqual(Child.__mutable_keys__, frozenset())
 
     def test_can_make_readonly_key_mutable(self):
         class Base(TypedDict):
@@ -4811,6 +4817,50 @@ def test_no_isinstance(self):
             issubclass(int, TypeGuard)
 
 
+class TypeIsTests(BaseTestCase):
+    def test_basics(self):
+        TypeIs[int]  # OK
+        self.assertEqual(TypeIs[int], TypeIs[int])
+
+        def foo(arg) -> TypeIs[int]: ...
+        self.assertEqual(gth(foo), {'return': TypeIs[int]})
+
+    def test_repr(self):
+        if hasattr(typing, 'TypeIs'):
+            mod_name = 'typing'
+        else:
+            mod_name = 'typing_extensions'
+        self.assertEqual(repr(TypeIs), f'{mod_name}.TypeIs')
+        cv = TypeIs[int]
+        self.assertEqual(repr(cv), f'{mod_name}.TypeIs[int]')
+        cv = TypeIs[Employee]
+        self.assertEqual(repr(cv), f'{mod_name}.TypeIs[{__name__}.Employee]')
+        cv = TypeIs[Tuple[int]]
+        self.assertEqual(repr(cv), f'{mod_name}.TypeIs[typing.Tuple[int]]')
+
+    def test_cannot_subclass(self):
+        with self.assertRaises(TypeError):
+            class C(type(TypeIs)):
+                pass
+        with self.assertRaises(TypeError):
+            class C(type(TypeIs[int])):
+                pass
+
+    def test_cannot_init(self):
+        with self.assertRaises(TypeError):
+            TypeIs()
+        with self.assertRaises(TypeError):
+            type(TypeIs)()
+        with self.assertRaises(TypeError):
+            type(TypeIs[Optional[int]])()
+
+    def test_no_isinstance(self):
+        with self.assertRaises(TypeError):
+            isinstance(1, TypeIs[int])
+        with self.assertRaises(TypeError):
+            issubclass(int, TypeIs)
+
+
 class LiteralStringTests(BaseTestCase):
     def test_basics(self):
         class Foo:

src/typing_extensions.py

@@ -83,6 +83,7 @@
     'TypeAlias',
     'TypeAliasType',
     'TypeGuard',
+    'TypeIs',
     'TYPE_CHECKING',
     'Never',
     'NoReturn',
@@ -949,11 +950,7 @@ def __new__(cls, name, bases, ns, *, total=True):
                 else:
                     optional_keys.add(annotation_key)
                 if ReadOnly in qualifiers:
-                    if annotation_key in mutable_keys:
-                        raise TypeError(
-                            f"Cannot override mutable key {annotation_key!r}"
-                            " with read-only key"
-                        )
+                    mutable_keys.discard(annotation_key)
                     readonly_keys.add(annotation_key)
                 else:
                     mutable_keys.add(annotation_key)
@@ -1834,6 +1831,98 @@ def is_str(val: Union[str, float]):
         PEP 647 (User-Defined Type Guards).
         """)
 
+# 3.13+
+if hasattr(typing, 'TypeIs'):
+    TypeIs = typing.TypeIs
+# 3.9
+elif sys.version_info[:2] >= (3, 9):
+    @_ExtensionsSpecialForm
+    def TypeIs(self, parameters):
+        """Special typing form used to annotate the return type of a user-defined
+        type narrower function.  ``TypeIs`` only accepts a single type argument.
+        At runtime, functions marked this way should return a boolean.
+
+        ``TypeIs`` aims to benefit *type narrowing* -- a technique used by static
+        type checkers to determine a more precise type of an expression within a
+        program's code flow.  Usually type narrowing is done by analyzing
+        conditional code flow and applying the narrowing to a block of code.  The
+        conditional expression here is sometimes referred to as a "type guard".
+
+        Sometimes it would be convenient to use a user-defined boolean function
+        as a type guard.  Such a function should use ``TypeIs[...]`` as its
+        return type to alert static type checkers to this intention.
+
+        Using  ``-> TypeIs`` tells the static type checker that for a given
+        function:
+
+        1. The return value is a boolean.
+        2. If the return value is ``True``, the type of its argument
+        is the intersection of the type inside ``TypeGuard`` and the argument's
+        previously known type.
+
+        For example::
+
+            def is_awaitable(val: object) -> TypeIs[Awaitable[Any]]:
+                return hasattr(val, '__await__')
+
+            def f(val: Union[int, Awaitable[int]]) -> int:
+                if is_awaitable(val):
+                    assert_type(val, Awaitable[int])
+                else:
+                    assert_type(val, int)
+
+        ``TypeIs`` also works with type variables.  For more information, see
+        PEP 742 (Narrowing types with TypeIs).
+        """
+        item = typing._type_check(parameters, f'{self} accepts only a single type.')
+        return typing._GenericAlias(self, (item,))
+# 3.8
+else:
+    class _TypeIsForm(_ExtensionsSpecialForm, _root=True):
+        def __getitem__(self, parameters):
+            item = typing._type_check(parameters,
+                                      f'{self._name} accepts only a single type')
+            return typing._GenericAlias(self, (item,))
+
+    TypeIs = _TypeIsForm(
+        'TypeIs',
+        doc="""Special typing form used to annotate the return type of a user-defined
+        type narrower function.  ``TypeIs`` only accepts a single type argument.
+        At runtime, functions marked this way should return a boolean.
+
+        ``TypeIs`` aims to benefit *type narrowing* -- a technique used by static
+        type checkers to determine a more precise type of an expression within a
+        program's code flow.  Usually type narrowing is done by analyzing
+        conditional code flow and applying the narrowing to a block of code.  The
+        conditional expression here is sometimes referred to as a "type guard".
+
+        Sometimes it would be convenient to use a user-defined boolean function
+        as a type guard.  Such a function should use ``TypeIs[...]`` as its
+        return type to alert static type checkers to this intention.
+
+        Using  ``-> TypeIs`` tells the static type checker that for a given
+        function:
+
+        1. The return value is a boolean.
+        2. If the return value is ``True``, the type of its argument
+        is the intersection of the type inside ``TypeGuard`` and the argument's
+        previously known type.
+
+        For example::
+
+            def is_awaitable(val: object) -> TypeIs[Awaitable[Any]]:
+                return hasattr(val, '__await__')
+
+            def f(val: Union[int, Awaitable[int]]) -> int:
+                if is_awaitable(val):
+                    assert_type(val, Awaitable[int])
+                else:
+                    assert_type(val, int)
+
+        ``TypeIs`` also works with type variables.  For more information, see
+        PEP 742 (Narrowing types with TypeIs).
+        """)
+
 
 # Vendored from cpython typing._SpecialFrom
 class _SpecialForm(typing._Final, _root=True):