1.. module:: typing_extensions 2 3Welcome to typing_extensions's documentation! 4============================================= 5 6``typing_extensions`` complements the standard-library :py:mod:`typing` module, 7providing runtime support for type hints as specified by :pep:`484` and subsequent 8PEPs. The module serves two related purposes: 9 10- Enable use of new type system features on older Python versions. For example, 11 :py:data:`typing.TypeGuard` is new in Python 3.10, but ``typing_extensions`` allows 12 users on previous Python versions to use it too. 13- Enable experimentation with type system features proposed in new PEPs before they are accepted and 14 added to the :py:mod:`typing` module. 15 16New features may be added to ``typing_extensions`` as soon as they are specified 17in a PEP that has been added to the `python/peps <https://github.com/python/peps>`_ 18repository. If the PEP is accepted, the feature will then be added to the 19:py:mod:`typing` module for the next CPython release. No typing PEP that 20affected ``typing_extensions`` has been rejected so far, so we haven't yet 21figured out how to deal with that possibility. 22 23Bugfixes and new typing features that don't require a PEP may be added to 24``typing_extensions`` once they are merged into CPython's main branch. 25 26``typing_extensions`` also re-exports all names from the :py:mod:`typing` module, 27including those that have always been present in the module. This allows users to 28import names from ``typing_extensions`` without having to remember exactly when 29each object was added to :py:mod:`typing`. There are a few exceptions: 30:py:class:`typing.ByteString`, which is deprecated and due to be removed in Python 313.14, is not re-exported. Similarly, the ``typing.io`` and ``typing.re`` submodules, 32which are removed in Python 3.13, are excluded. 33 34Versioning and backwards compatibility 35-------------------------------------- 36 37Starting with version 4.0.0, ``typing_extensions`` uses 38`Semantic Versioning <https://semver.org>`_. A changelog is 39maintained `on GitHub <https://github.com/python/typing_extensions/blob/main/CHANGELOG.md>`_. 40 41The major version is incremented for all backwards-incompatible changes. 42Therefore, it's safe to depend 43on ``typing_extensions`` like this: ``typing_extensions >=x.y, <(x+1)``, 44where ``x.y`` is the first version that includes all features you need. 45In view of the wide usage of ``typing_extensions`` across the ecosystem, 46we are highly hesitant to break backwards compatibility, and we do not 47expect to increase the major version number in the foreseeable future. 48 49Feature releases, with version numbers of the form 4.N.0, are made at 50irregular intervals when enough new features accumulate. Before a 51feature release, at least one release candidate (with a version number 52of the form 4.N.0rc1) should be released to give downstream users time 53to test. After at least a week of testing, the new feature version 54may then be released. If necessary, additional release candidates can 55be added. 56 57Bugfix releases, with version numbers of the form 4.N.1 or higher, 58may be made if bugs are discovered after a feature release. 59 60We provide no backward compatibility guarantees for prereleases (e.g., 61release candidates) and for unreleased code in our Git repository. 62 63Before version 4.0.0, the versioning scheme loosely followed the Python 64version from which features were backported; for example, 65``typing_extensions`` 3.10.0.0 was meant to reflect ``typing`` as of 66Python 3.10.0. During this period, no changelog was maintained. 67 68Runtime use of types 69~~~~~~~~~~~~~~~~~~~~ 70 71We aim for complete backwards compatibility in terms of the names we export: 72code like ``from typing_extensions import X`` that works on one 73typing-extensions release will continue to work on the next. 74It is more difficult to maintain compatibility for users that introspect 75types at runtime, as almost any detail can potentially break compatibility. 76Users who introspect types should follow these guidelines to minimize 77the risk of compatibility issues: 78 79- Always check for both the :mod:`typing` and ``typing_extensions`` versions 80 of objects, even if they are currently the same on some Python version. 81 Future ``typing_extensions`` releases may re-export a separate version of 82 the object to backport some new feature or bugfix. 83- Use public APIs like :func:`get_origin` and :func:`get_original_bases` to 84 access internal information about types, instead of accessing private 85 attributes directly. If some information is not available through a public 86 attribute, consider opening an issue in CPython to add such an API. 87 88Here is an example recipe for a general-purpose function that could be used for 89reasonably performant runtime introspection of typing objects. The function 90will be resilient against any potential changes in ``typing_extensions`` that 91alter whether an object is reimplemented in ``typing_extensions``, rather than 92simply being re-exported from the :mod:`typing` module:: 93 94 import functools 95 import typing 96 import typing_extensions 97 from typing import Tuple, Any 98 99 # Use an unbounded cache for this function, for optimal performance 100 @functools.lru_cache(maxsize=None) 101 def get_typing_objects_by_name_of(name: str) -> Tuple[Any, ...]: 102 result = tuple( 103 getattr(module, name) 104 # You could potentially also include mypy_extensions here, 105 # if your library supports mypy_extensions 106 for module in (typing, typing_extensions) 107 if hasattr(module, name) 108 ) 109 if not result: 110 raise ValueError( 111 f"Neither typing nor typing_extensions has an object called {name!r}" 112 ) 113 return result 114 115 116 # Use a cache here as well, but make it a bounded cache 117 # (the default cache size is 128) 118 @functools.lru_cache() 119 def is_typing_name(obj: object, name: str) -> bool: 120 return any(obj is thing for thing in get_typing_objects_by_name_of(name)) 121 122Example usage:: 123 124 >>> import typing, typing_extensions 125 >>> from functools import partial 126 >>> from typing_extensions import get_origin 127 >>> is_literal = partial(is_typing_name, name="Literal") 128 >>> is_literal(typing.Literal) 129 True 130 >>> is_literal(typing_extensions.Literal) 131 True 132 >>> is_literal(typing.Any) 133 False 134 >>> is_literal(get_origin(typing.Literal[42])) 135 True 136 >>> is_literal(get_origin(typing_extensions.Final[42])) 137 False 138 139Python version support 140---------------------- 141 142``typing_extensions`` currently supports Python versions 3.8 and higher. In the future, 143support for older Python versions will be dropped some time after that version 144reaches end of life. 145 146Module contents 147--------------- 148 149As most of the features in ``typing_extensions`` exist in :py:mod:`typing` 150in newer versions of Python, the documentation here is brief and focuses 151on aspects that are specific to ``typing_extensions``, such as limitations 152on specific Python versions. 153 154Special typing primitives 155~~~~~~~~~~~~~~~~~~~~~~~~~ 156 157.. data:: Annotated 158 159 See :py:data:`typing.Annotated` and :pep:`593`. In ``typing`` since 3.9. 160 161 .. versionchanged:: 4.1.0 162 163 ``Annotated`` can now wrap :data:`ClassVar` and :data:`Final`. 164 165.. data:: Any 166 167 See :py:data:`typing.Any`. 168 169 Since Python 3.11, ``typing.Any`` can be used as a base class. 170 ``typing_extensions.Any`` supports this feature on older versions. 171 172 .. versionadded:: 4.4.0 173 174 Added to support inheritance from ``Any``. 175 176.. data:: Concatenate 177 178 See :py:data:`typing.Concatenate` and :pep:`612`. In ``typing`` since 3.10. 179 180 The backport does not support certain operations involving ``...`` as 181 a parameter; see :issue:`48` and :issue:`110` for details. 182 183.. data:: Final 184 185 See :py:data:`typing.Final` and :pep:`591`. In ``typing`` since 3.8. 186 187.. data:: Literal 188 189 See :py:data:`typing.Literal` and :pep:`586`. In ``typing`` since 3.8. 190 191 :py:data:`typing.Literal` does not flatten or deduplicate parameters on Python <3.9.1, and a 192 caching bug was fixed in 3.10.1/3.9.8. The ``typing_extensions`` version 193 flattens and deduplicates parameters on all Python versions, and the caching 194 bug is also fixed on all versions. 195 196 .. versionchanged:: 4.6.0 197 198 Backported the bug fixes from :pr-cpy:`29334`, :pr-cpy:`23294`, and :pr-cpy:`23383`. 199 200.. data:: LiteralString 201 202 See :py:data:`typing.LiteralString` and :pep:`675`. In ``typing`` since 3.11. 203 204 .. versionadded:: 4.1.0 205 206.. class:: NamedTuple 207 208 See :py:class:`typing.NamedTuple`. 209 210 ``typing_extensions`` backports several changes 211 to ``NamedTuple`` on Python 3.11 and lower: in 3.11, 212 support for generic ``NamedTuple``\ s was added, and 213 in 3.12, the ``__orig_bases__`` attribute was added. 214 215 .. versionadded:: 4.3.0 216 217 Added to provide support for generic ``NamedTuple``\ s. 218 219 .. versionchanged:: 4.6.0 220 221 Support for the ``__orig_bases__`` attribute was added. 222 223 .. versionchanged:: 4.7.0 224 225 The undocumented keyword argument syntax for creating NamedTuple classes 226 (``NT = NamedTuple("NT", x=int)``) is deprecated, and will be disallowed 227 in Python 3.15. Use the class-based syntax or the functional syntax instead. 228 229 .. versionchanged:: 4.7.0 230 231 When using the functional syntax to create a NamedTuple class, failing to 232 pass a value to the 'fields' parameter (``NT = NamedTuple("NT")``) is 233 deprecated. Passing ``None`` to the 'fields' parameter 234 (``NT = NamedTuple("NT", None)``) is also deprecated. Both will be 235 disallowed in Python 3.15. To create a NamedTuple class with zero fields, 236 use ``class NT(NamedTuple): pass`` or ``NT = NamedTuple("NT", [])``. 237 238 239.. data:: Never 240 241 See :py:data:`typing.Never`. In ``typing`` since 3.11. 242 243 .. versionadded:: 4.1.0 244 245.. class:: NewType(name, tp) 246 247 See :py:class:`typing.NewType`. In ``typing`` since 3.5.2. 248 249 Instances of ``NewType`` were made picklable in 3.10 and an error message was 250 improved in 3.11; ``typing_extensions`` backports these changes. 251 252 .. versionchanged:: 4.6.0 253 254 The improvements from Python 3.10 and 3.11 were backported. 255 256.. data:: NoDefault 257 258 See :py:class:`typing.NoDefault`. In ``typing`` since 3.13.0. 259 260 .. versionadded:: 4.12.0 261 262.. data:: NotRequired 263 264 See :py:data:`typing.NotRequired` and :pep:`655`. In ``typing`` since 3.11. 265 266 .. versionadded:: 4.0.0 267 268.. class:: ParamSpec(name, *, default=NoDefault) 269 270 See :py:class:`typing.ParamSpec` and :pep:`612`. In ``typing`` since 3.10. 271 272 The ``typing_extensions`` version adds support for the 273 ``default=`` argument from :pep:`696`. 274 275 On older Python versions, ``typing_extensions.ParamSpec`` may not work 276 correctly with introspection tools like :func:`get_args` and 277 :func:`get_origin`. Certain special cases in user-defined 278 :py:class:`typing.Generic`\ s are also not available (e.g., see :issue:`126`). 279 280 .. versionchanged:: 4.4.0 281 282 Added support for the ``default=`` argument. 283 284 .. versionchanged:: 4.6.0 285 286 The implementation was changed for compatibility with Python 3.12. 287 288 .. versionchanged:: 4.8.0 289 290 Passing an ellipsis literal (``...``) to *default* now works on Python 291 3.10 and lower. 292 293 .. versionchanged:: 4.12.0 294 295 The :attr:`!__default__` attribute is now set to ``None`` if 296 ``default=None`` is passed, and to :data:`NoDefault` if no value is passed. 297 298 Previously, passing ``None`` would result in :attr:`!__default__` being set 299 to :py:class:`types.NoneType`, and passing no value for the parameter would 300 result in :attr:`!__default__` being set to ``None``. 301 302 .. versionchanged:: 4.12.0 303 304 ParamSpecs now have a ``has_default()`` method, for compatibility 305 with :py:class:`typing.ParamSpec` on Python 3.13+. 306 307.. class:: ParamSpecArgs 308 309.. class:: ParamSpecKwargs 310 311 See :py:class:`typing.ParamSpecArgs` and :py:class:`typing.ParamSpecKwargs`. 312 In ``typing`` since 3.10. 313 314.. class:: Protocol 315 316 See :py:class:`typing.Protocol` and :pep:`544`. In ``typing`` since 3.8. 317 318 Python 3.12 improves the performance of runtime-checkable protocols; 319 ``typing_extensions`` backports this improvement. 320 321 .. versionchanged:: 4.6.0 322 323 Backported the ability to define ``__init__`` methods on Protocol classes. 324 325 .. versionchanged:: 4.6.0 326 327 Backported changes to runtime-checkable protocols from Python 3.12, 328 including :pr-cpy:`103034` and :pr-cpy:`26067`. 329 330 .. versionchanged:: 4.7.0 331 332 Classes can now inherit from both :py:class:`typing.Protocol` and 333 ``typing_extensions.Protocol`` simultaneously. Previously, this led to 334 :py:exc:`TypeError` being raised due to a metaclass conflict. 335 336 It is recommended to avoid doing this if possible. Not all features and 337 bugfixes that ``typing_extensions.Protocol`` backports from newer Python 338 versions are guaranteed to work if :py:class:`typing.Protocol` is also 339 present in a protocol class's :py:term:`method resolution order`. See 340 :issue:`245` for some examples. 341 342.. data:: ReadOnly 343 344 See :pep:`705`. Indicates that a :class:`TypedDict` item may not be modified. 345 346 .. versionadded:: 4.9.0 347 348.. data:: Required 349 350 See :py:data:`typing.Required` and :pep:`655`. In ``typing`` since 3.11. 351 352 .. versionadded:: 4.0.0 353 354.. data:: Self 355 356 See :py:data:`typing.Self` and :pep:`673`. In ``typing`` since 3.11. 357 358 .. versionadded:: 4.0.0 359 360.. data:: TypeAlias 361 362 See :py:data:`typing.TypeAlias` and :pep:`613`. In ``typing`` since 3.10. 363 364.. class:: TypeAliasType(name, value, *, type_params=()) 365 366 See :py:class:`typing.TypeAliasType` and :pep:`695`. In ``typing`` since 3.12. 367 368 .. versionadded:: 4.6.0 369 370.. data:: TypeGuard 371 372 See :py:data:`typing.TypeGuard` and :pep:`647`. In ``typing`` since 3.10. 373 374.. data:: TypeIs 375 376 See :pep:`742`. Similar to :data:`TypeGuard`, but allows more type narrowing. 377 378 .. versionadded:: 4.10.0 379 380.. class:: TypedDict(dict, total=True) 381 382 See :py:class:`typing.TypedDict` and :pep:`589`. In ``typing`` since 3.8. 383 384 ``typing_extensions`` backports various bug fixes and improvements 385 to ``TypedDict`` on Python 3.11 and lower. 386 :py:class:`TypedDict` does not store runtime information 387 about which (if any) keys are non-required in Python 3.8, and does not 388 honor the ``total`` keyword with old-style ``TypedDict()`` in Python 389 3.9.0 and 3.9.1. :py:class:`typing.TypedDict` also does not support multiple inheritance 390 with :py:class:`typing.Generic` on Python <3.11, and :py:class:`typing.TypedDict` classes do not 391 consistently have the ``__orig_bases__`` attribute on Python <3.12. The 392 ``typing_extensions`` backport provides all of these features and bugfixes on 393 all Python versions. 394 395 Historically, ``TypedDict`` has supported an alternative creation syntax 396 where the fields are supplied as keyword arguments (e.g., 397 ``TypedDict("TD", a=int, b=str)``). In CPython, this feature was deprecated 398 in Python 3.11 and removed in Python 3.13. ``typing_extensions.TypedDict`` 399 raises a :py:exc:`DeprecationWarning` when this syntax is used in Python 3.12 400 or lower and fails with a :py:exc:`TypeError` in Python 3.13 and higher. 401 402 ``typing_extensions`` supports the experimental :data:`ReadOnly` qualifier 403 proposed by :pep:`705`. It is reflected in the following attributes: 404 405 .. attribute:: __readonly_keys__ 406 407 A :py:class:`frozenset` containing the names of all read-only keys. Keys 408 are read-only if they carry the :data:`ReadOnly` qualifier. 409 410 .. versionadded:: 4.9.0 411 412 .. attribute:: __mutable_keys__ 413 414 A :py:class:`frozenset` containing the names of all mutable keys. Keys 415 are mutable if they do not carry the :data:`ReadOnly` qualifier. 416 417 .. versionadded:: 4.9.0 418 419 The experimental ``closed`` keyword argument and the special key 420 ``__extra_items__`` proposed in :pep:`728` are supported. 421 422 When ``closed`` is unspecified or ``closed=False`` is given, 423 ``__extra_items__`` behaves like a regular key. Otherwise, this becomes a 424 special key that does not show up in ``__readonly_keys__``, 425 ``__mutable_keys__``, ``__required_keys__``, ``__optional_keys``, or 426 ``__annotations__``. 427 428 For runtime introspection, two attributes can be looked at: 429 430 .. attribute:: __closed__ 431 432 A boolean flag indicating whether the current ``TypedDict`` is 433 considered closed. This is not inherited by the ``TypedDict``'s 434 subclasses. 435 436 .. versionadded:: 4.10.0 437 438 .. attribute:: __extra_items__ 439 440 The type annotation of the extra items allowed on the ``TypedDict``. 441 This attribute defaults to ``None`` on a TypedDict that has itself and 442 all its bases non-closed. This default is different from ``type(None)`` 443 that represents ``__extra_items__: None`` defined on a closed 444 ``TypedDict``. 445 446 If ``__extra_items__`` is not defined or inherited on a closed 447 ``TypedDict``, this defaults to ``Never``. 448 449 .. versionadded:: 4.10.0 450 451 .. versionchanged:: 4.3.0 452 453 Added support for generic ``TypedDict``\ s. 454 455 .. versionchanged:: 4.6.0 456 457 A :py:exc:`DeprecationWarning` is now emitted when a call-based 458 ``TypedDict`` is constructed using keyword arguments. 459 460 .. versionchanged:: 4.6.0 461 462 Support for the ``__orig_bases__`` attribute was added. 463 464 .. versionchanged:: 4.7.0 465 466 ``TypedDict`` is now a function rather than a class. 467 This brings ``typing_extensions.TypedDict`` closer to the implementation 468 of :py:mod:`typing.TypedDict` on Python 3.9 and higher. 469 470 .. versionchanged:: 4.7.0 471 472 When using the functional syntax to create a TypedDict class, failing to 473 pass a value to the 'fields' parameter (``TD = TypedDict("TD")``) is 474 deprecated. Passing ``None`` to the 'fields' parameter 475 (``TD = TypedDict("TD", None)``) is also deprecated. Both will be 476 disallowed in Python 3.15. To create a TypedDict class with 0 fields, 477 use ``class TD(TypedDict): pass`` or ``TD = TypedDict("TD", {})``. 478 479 .. versionchanged:: 4.9.0 480 481 Support for the :data:`ReadOnly` qualifier was added. 482 483 .. versionchanged:: 4.10.0 484 485 The keyword argument ``closed`` and the special key ``__extra_items__`` 486 when ``closed=True`` is given were supported. 487 488.. class:: TypeVar(name, *constraints, bound=None, covariant=False, 489 contravariant=False, infer_variance=False, default=NoDefault) 490 491 See :py:class:`typing.TypeVar`. 492 493 The ``typing_extensions`` version adds support for the 494 ``default=`` argument from :pep:`696`, as well as the 495 ``infer_variance=`` argument from :pep:`695` (also available 496 in Python 3.12). 497 498 .. versionadded:: 4.4.0 499 500 Added in order to support the new ``default=`` and 501 ``infer_variance=`` arguments. 502 503 .. versionchanged:: 4.6.0 504 505 The implementation was changed for compatibility with Python 3.12. 506 507 .. versionchanged:: 4.12.0 508 509 The :attr:`!__default__` attribute is now set to ``None`` if 510 ``default=None`` is passed, and to :data:`NoDefault` if no value is passed. 511 512 Previously, passing ``None`` would result in :attr:`!__default__` being set 513 to :py:class:`types.NoneType`, and passing no value for the parameter would 514 result in :attr:`!__default__` being set to ``None``. 515 516 .. versionchanged:: 4.12.0 517 518 TypeVars now have a ``has_default()`` method, for compatibility 519 with :py:class:`typing.TypeVar` on Python 3.13+. 520 521.. class:: TypeVarTuple(name, *, default=NoDefault) 522 523 See :py:class:`typing.TypeVarTuple` and :pep:`646`. In ``typing`` since 3.11. 524 525 The ``typing_extensions`` version adds support for the 526 ``default=`` argument from :pep:`696`. 527 528 .. versionadded:: 4.1.0 529 530 .. versionchanged:: 4.4.0 531 532 Added support for the ``default=`` argument. 533 534 .. versionchanged:: 4.6.0 535 536 The implementation was changed for compatibility with Python 3.12. 537 538 .. versionchanged:: 4.12.0 539 540 The :attr:`!__default__` attribute is now set to ``None`` if 541 ``default=None`` is passed, and to :data:`NoDefault` if no value is passed. 542 543 Previously, passing ``None`` would result in :attr:`!__default__` being set 544 to :py:class:`types.NoneType`, and passing no value for the parameter would 545 result in :attr:`!__default__` being set to ``None``. 546 547 .. versionchanged:: 4.12.0 548 549 TypeVarTuples now have a ``has_default()`` method, for compatibility 550 with :py:class:`typing.TypeVarTuple` on Python 3.13+. 551 552 .. versionchanged:: 4.12.0 553 554 It is now disallowed to use a `TypeVar` with a default value after a 555 `TypeVarTuple` in a type parameter list. This matches the CPython 556 implementation of PEP 696 on Python 3.13+. 557 558.. data:: Unpack 559 560 See :py:data:`typing.Unpack` and :pep:`646`. In ``typing`` since 3.11. 561 562 In Python 3.12, the ``repr()`` was changed as a result of :pep:`692`. 563 ``typing_extensions`` backports this change. 564 565 Generic type aliases involving ``Unpack`` may not work correctly on 566 Python 3.10 and lower; see :issue:`103` for details. 567 568 .. versionadded:: 4.1.0 569 570 .. versionchanged:: 4.6.0 571 572 Backport ``repr()`` changes from Python 3.12. 573 574Abstract Base Classes 575~~~~~~~~~~~~~~~~~~~~~ 576 577.. class:: Buffer 578 579 See :py:class:`collections.abc.Buffer`. Added to the standard library 580 in Python 3.12. 581 582 .. versionadded:: 4.6.0 583 584Protocols 585~~~~~~~~~ 586 587.. class:: SupportsAbs 588 589 See :py:class:`typing.SupportsAbs`. 590 591 ``typing_extensions`` backports a more performant version of this 592 protocol on Python 3.11 and lower. 593 594 .. versionadded:: 4.6.0 595 596.. class:: SupportsBytes 597 598 See :py:class:`typing.SupportsBytes`. 599 600 ``typing_extensions`` backports a more performant version of this 601 protocol on Python 3.11 and lower. 602 603 .. versionadded:: 4.6.0 604 605.. class:: SupportsComplex 606 607 See :py:class:`typing.SupportsComplex`. 608 609 ``typing_extensions`` backports a more performant version of this 610 protocol on Python 3.11 and lower. 611 612 .. versionadded:: 4.6.0 613 614.. class:: SupportsFloat 615 616 See :py:class:`typing.SupportsFloat`. 617 618 ``typing_extensions`` backports a more performant version of this 619 protocol on Python 3.11 and lower. 620 621 .. versionadded:: 4.6.0 622 623.. class:: SupportsIndex 624 625 See :py:class:`typing.SupportsIndex`. In ``typing`` since 3.8. 626 627 ``typing_extensions`` backports a more performant version of this 628 protocol on Python 3.11 and lower. 629 630 .. versionchanged:: 4.6.0 631 632 Backported the performance improvements from Python 3.12. 633 634.. class:: SupportsInt 635 636 See :py:class:`typing.SupportsInt`. 637 638 ``typing_extensions`` backports a more performant version of this 639 protocol on Python 3.11 and lower. 640 641 .. versionadded:: 4.6.0 642 643.. class:: SupportsRound 644 645 See :py:class:`typing.SupportsRound`. 646 647 ``typing_extensions`` backports a more performant version of this 648 protocol on Python 3.11 and lower. 649 650 .. versionadded:: 4.6.0 651 652Decorators 653~~~~~~~~~~ 654 655.. decorator:: dataclass_transform(*, eq_default=False, order_default=False, 656 kw_only_default=False, frozen_default=False, 657 field_specifiers=(), **kwargs) 658 659 See :py:func:`typing.dataclass_transform` and :pep:`681`. In ``typing`` since 3.11. 660 661 Python 3.12 adds the ``frozen_default`` parameter; ``typing_extensions`` 662 backports this parameter. 663 664 .. versionadded:: 4.1.0 665 666 .. versionchanged:: 4.2.0 667 668 The ``field_descriptors`` parameter was renamed to ``field_specifiers``. 669 For compatibility, the decorator now accepts arbitrary keyword arguments. 670 671 .. versionchanged:: 4.5.0 672 673 The ``frozen_default`` parameter was added. 674 675.. decorator:: deprecated(msg, *, category=DeprecationWarning, stacklevel=1) 676 677 See :pep:`702`. In the :mod:`warnings` module since Python 3.13. 678 679 .. versionadded:: 4.5.0 680 681 .. versionchanged:: 4.9.0 682 683 Inheriting from a deprecated class now also raises a runtime 684 :py:exc:`DeprecationWarning`. 685 686.. decorator:: final 687 688 See :py:func:`typing.final` and :pep:`591`. In ``typing`` since 3.8. 689 690 Since Python 3.11, this decorator supports runtime introspection 691 by setting the ``__final__`` attribute wherever possible; ``typing_extensions.final`` 692 backports this feature. 693 694 .. versionchanged:: 4.1.0 695 696 The decorator now attempts to set the ``__final__`` attribute on decorated objects. 697 698.. decorator:: overload 699 700 See :py:func:`typing.overload`. 701 702 Since Python 3.11, this decorator supports runtime introspection 703 through :func:`get_overloads`; ``typing_extensions.overload`` 704 backports this feature. 705 706 .. versionchanged:: 4.2.0 707 708 Introspection support via :func:`get_overloads` was added. 709 710.. decorator:: override 711 712 See :py:func:`typing.override` and :pep:`698`. In ``typing`` since 3.12. 713 714 .. versionadded:: 4.4.0 715 716 .. versionchanged:: 4.5.0 717 718 The decorator now attempts to set the ``__override__`` attribute on the decorated 719 object. 720 721.. decorator:: runtime_checkable 722 723 See :py:func:`typing.runtime_checkable`. In ``typing`` since 3.8. 724 725 In Python 3.12, the performance of runtime-checkable protocols was 726 improved, and ``typing_extensions`` backports these performance 727 improvements. 728 729Functions 730~~~~~~~~~ 731 732.. function:: assert_never(arg) 733 734 See :py:func:`typing.assert_never`. In ``typing`` since 3.11. 735 736 .. versionadded:: 4.1.0 737 738.. function:: assert_type(val, typ) 739 740 See :py:func:`typing.assert_type`. In ``typing`` since 3.11. 741 742 .. versionadded:: 4.2.0 743 744.. function:: clear_overloads() 745 746 See :py:func:`typing.clear_overloads`. In ``typing`` since 3.11. 747 748 .. versionadded:: 4.2.0 749 750.. function:: get_args(tp) 751 752 See :py:func:`typing.get_args`. In ``typing`` since 3.8. 753 754 This function was changed in 3.9 and 3.10 to deal with :data:`Annotated` 755 and :class:`ParamSpec` correctly; ``typing_extensions`` backports these 756 fixes. 757 758.. function:: get_origin(tp) 759 760 See :py:func:`typing.get_origin`. In ``typing`` since 3.8. 761 762 This function was changed in 3.9 and 3.10 to deal with :data:`Annotated` 763 and :class:`ParamSpec` correctly; ``typing_extensions`` backports these 764 fixes. 765 766.. function:: get_original_bases(cls) 767 768 See :py:func:`types.get_original_bases`. Added to the standard library 769 in Python 3.12. 770 771 This function should always produce correct results when called on classes 772 constructed using features from ``typing_extensions``. However, it may 773 produce incorrect results when called on some :py:class:`NamedTuple` or 774 :py:class:`TypedDict` classes on Python <=3.11. 775 776 .. versionadded:: 4.6.0 777 778.. function:: get_overloads(func) 779 780 See :py:func:`typing.get_overloads`. In ``typing`` since 3.11. 781 782 Before Python 3.11, this works only with overloads created through 783 :func:`overload`, not with :py:func:`typing.overload`. 784 785 .. versionadded:: 4.2.0 786 787.. function:: get_protocol_members(tp) 788 789 Return the set of members defined in a :class:`Protocol`. This works with protocols 790 defined using either :class:`typing.Protocol` or :class:`typing_extensions.Protocol`. 791 792 :: 793 794 >>> from typing_extensions import Protocol, get_protocol_members 795 >>> class P(Protocol): 796 ... def a(self) -> str: ... 797 ... b: int 798 >>> get_protocol_members(P) 799 frozenset({'a', 'b'}) 800 801 Raise :py:exc:`TypeError` for arguments that are not Protocols. 802 803 .. versionadded:: 4.7.0 804 805.. function:: get_type_hints(obj, globalns=None, localns=None, include_extras=False) 806 807 See :py:func:`typing.get_type_hints`. 808 809 In Python 3.11, this function was changed to support the new 810 :py:data:`typing.Required` and :py:data:`typing.NotRequired`. 811 ``typing_extensions`` backports these fixes. 812 813 .. versionchanged:: 4.1.0 814 815 Interaction with :data:`Required` and :data:`NotRequired`. 816 817 .. versionchanged:: 4.11.0 818 819 When ``include_extra=False``, ``get_type_hints()`` now strips 820 :data:`ReadOnly` from the annotation. 821 822.. function:: is_protocol(tp) 823 824 Determine if a type is a :class:`Protocol`. This works with protocols 825 defined using either :py:class:`typing.Protocol` or :class:`typing_extensions.Protocol`. 826 827 For example:: 828 829 class P(Protocol): 830 def a(self) -> str: ... 831 b: int 832 833 is_protocol(P) # => True 834 is_protocol(int) # => False 835 836 .. versionadded:: 4.7.0 837 838.. function:: is_typeddict(tp) 839 840 See :py:func:`typing.is_typeddict`. In ``typing`` since 3.10. 841 842 On versions where :class:`TypedDict` is not the same as 843 :py:class:`typing.TypedDict`, this function recognizes 844 ``TypedDict`` classes created through either mechanism. 845 846 .. versionadded:: 4.1.0 847 848 .. versionchanged:: 4.7.0 849 850 :func:`is_typeddict` now returns ``False`` when called with 851 :data:`TypedDict` itself as the argument, consistent with the 852 behavior of :py:func:`typing.is_typeddict`. 853 854.. function:: reveal_type(obj) 855 856 See :py:func:`typing.reveal_type`. In ``typing`` since 3.11. 857 858 .. versionadded:: 4.1.0 859 860 861Annotation metadata 862~~~~~~~~~~~~~~~~~~~ 863 864.. class:: Doc(documentation, /) 865 866 Define the documentation of a type annotation using :data:`Annotated`, to be 867 used in class attributes, function and method parameters, return values, 868 and variables. 869 870 The value should be a positional-only string literal to allow static tools 871 like editors and documentation generators to use it. 872 873 This complements docstrings. 874 875 The string value passed is available in the attribute ``documentation``. 876 877 Example:: 878 879 >>> from typing_extensions import Annotated, Doc 880 >>> def hi(to: Annotated[str, Doc("Who to say hi to")]) -> None: ... 881 882 .. versionadded:: 4.8.0 883 884 See :pep:`727`. 885 886 .. attribute:: documentation 887 888 The documentation string passed to :class:`Doc`. 889 890 891Capsule objects 892~~~~~~~~~~~~~~~ 893 894.. class:: CapsuleType 895 896 The type of :py:ref:`capsule objects <capsules>`. 897 See :py:class:`types.CapsuleType`, where it has existed since Python 3.13. 898 899 Note that this may not exist on all implementations of Python; it is only 900 guaranteed to exist on CPython. 901 902 .. versionadded:: 4.12.0 903 904 905Pure aliases 906~~~~~~~~~~~~ 907 908Most of these are simply re-exported from the :mod:`typing` module on all supported 909versions of Python, but all are listed here for completeness. 910 911.. class:: AbstractSet 912 913 See :py:class:`typing.AbstractSet`. 914 915 .. versionadded:: 4.7.0 916 917.. data:: AnyStr 918 919 See :py:data:`typing.AnyStr`. 920 921 .. versionadded:: 4.7.0 922 923.. class:: AsyncContextManager 924 925 See :py:class:`typing.AsyncContextManager`. In ``typing`` since 3.5.4 and 3.6.2. 926 927 .. versionchanged:: 4.12.0 928 929 ``AsyncContextManager`` now has an optional second parameter, defaulting to 930 ``Optional[bool]``, signifying the return type of the ``__aexit__`` method. 931 932.. class:: AsyncGenerator 933 934 See :py:class:`typing.AsyncGenerator`. In ``typing`` since 3.6.1. 935 936 .. versionchanged:: 4.12.0 937 938 The second type parameter is now optional (it defaults to ``None``). 939 940.. class:: AsyncIterable 941 942 See :py:class:`typing.AsyncIterable`. In ``typing`` since 3.5.2. 943 944.. class:: AsyncIterator 945 946 See :py:class:`typing.AsyncIterator`. In ``typing`` since 3.5.2. 947 948.. class:: Awaitable 949 950 See :py:class:`typing.Awaitable`. In ``typing`` since 3.5.2. 951 952.. class:: BinaryIO 953 954 See :py:class:`typing.BinaryIO`. 955 956 .. versionadded:: 4.7.0 957 958.. data:: Callable 959 960 See :py:data:`typing.Callable`. 961 962 .. versionadded:: 4.7.0 963 964.. class:: ChainMap 965 966 See :py:class:`typing.ChainMap`. In ``typing`` since 3.5.4 and 3.6.1. 967 968.. data:: ClassVar 969 970 See :py:data:`typing.ClassVar` and :pep:`526`. In ``typing`` since 3.5.3. 971 972.. class:: Collection 973 974 See :py:class:`typing.Collection`. 975 976 .. versionadded:: 4.7.0 977 978.. class:: Container 979 980 See :py:class:`typing.Container`. 981 982 .. versionadded:: 4.7.0 983 984.. class:: ContextManager 985 986 See :py:class:`typing.ContextManager`. In ``typing`` since 3.5.4. 987 988 .. versionchanged:: 4.12.0 989 990 ``ContextManager`` now has an optional second parameter, defaulting to 991 ``Optional[bool]``, signifying the return type of the ``__exit__`` method. 992 993.. class:: Coroutine 994 995 See :py:class:`typing.Coroutine`. In ``typing`` since 3.5.3. 996 997.. class:: Counter 998 999 See :py:class:`typing.Counter`. In ``typing`` since 3.5.4 and 3.6.1. 1000 1001.. class:: DefaultDict 1002 1003 See :py:class:`typing.DefaultDict`. In ``typing`` since 3.5.2. 1004 1005.. class:: Deque 1006 1007 See :py:class:`typing.Deque`. In ``typing`` since 3.5.4 and 3.6.1. 1008 1009.. class:: Dict 1010 1011 See :py:class:`typing.Dict`. 1012 1013 .. versionadded:: 4.7.0 1014 1015.. class:: ForwardRef 1016 1017 See :py:class:`typing.ForwardRef`. 1018 1019 .. versionadded:: 4.7.0 1020 1021.. class:: FrozenSet 1022 1023 See :py:class:`typing.FrozenSet`. 1024 1025 .. versionadded:: 4.7.0 1026 1027.. class:: Generator 1028 1029 See :py:class:`typing.Generator`. 1030 1031 .. versionadded:: 4.7.0 1032 1033 .. versionchanged:: 4.12.0 1034 1035 The second type and third type parameters are now optional 1036 (they both default to ``None``). 1037 1038.. class:: Generic 1039 1040 See :py:class:`typing.Generic`. 1041 1042 .. versionadded:: 4.7.0 1043 1044.. class:: Hashable 1045 1046 See :py:class:`typing.Hashable`. 1047 1048 .. versionadded:: 4.7.0 1049 1050.. class:: IO 1051 1052 See :py:class:`typing.IO`. 1053 1054 .. versionadded:: 4.7.0 1055 1056.. class:: ItemsView 1057 1058 See :py:class:`typing.ItemsView`. 1059 1060 .. versionadded:: 4.7.0 1061 1062.. class:: Iterable 1063 1064 See :py:class:`typing.Iterable`. 1065 1066 .. versionadded:: 4.7.0 1067 1068.. class:: Iterator 1069 1070 See :py:class:`typing.Iterator`. 1071 1072 .. versionadded:: 4.7.0 1073 1074.. class:: KeysView 1075 1076 See :py:class:`typing.KeysView`. 1077 1078 .. versionadded:: 4.7.0 1079 1080.. class:: List 1081 1082 See :py:class:`typing.List`. 1083 1084 .. versionadded:: 4.7.0 1085 1086.. class:: Mapping 1087 1088 See :py:class:`typing.Mapping`. 1089 1090 .. versionadded:: 4.7.0 1091 1092.. class:: MappingView 1093 1094 See :py:class:`typing.MappingView`. 1095 1096 .. versionadded:: 4.7.0 1097 1098.. class:: Match 1099 1100 See :py:class:`typing.Match`. 1101 1102 .. versionadded:: 4.7.0 1103 1104.. class:: MutableMapping 1105 1106 See :py:class:`typing.MutableMapping`. 1107 1108 .. versionadded:: 4.7.0 1109 1110.. class:: MutableSequence 1111 1112 See :py:class:`typing.MutableSequence`. 1113 1114 .. versionadded:: 4.7.0 1115 1116.. class:: MutableSet 1117 1118 See :py:class:`typing.MutableSet`. 1119 1120 .. versionadded:: 4.7.0 1121 1122.. data:: NoReturn 1123 1124 See :py:data:`typing.NoReturn`. In ``typing`` since 3.5.4 and 3.6.2. 1125 1126.. data:: Optional 1127 1128 See :py:data:`typing.Optional`. 1129 1130 .. versionadded:: 4.7.0 1131 1132.. class:: OrderedDict 1133 1134 See :py:class:`typing.OrderedDict`. In ``typing`` since 3.7.2. 1135 1136.. class:: Pattern 1137 1138 See :py:class:`typing.Pattern`. 1139 1140 .. versionadded:: 4.7.0 1141 1142.. class:: Reversible 1143 1144 See :py:class:`typing.Reversible`. 1145 1146 .. versionadded:: 4.7.0 1147 1148.. class:: Sequence 1149 1150 See :py:class:`typing.Sequence`. 1151 1152 .. versionadded:: 4.7.0 1153 1154.. class:: Set 1155 1156 See :py:class:`typing.Set`. 1157 1158 .. versionadded:: 4.7.0 1159 1160.. class:: Sized 1161 1162 See :py:class:`typing.Sized`. 1163 1164 .. versionadded:: 4.7.0 1165 1166.. class:: Text 1167 1168 See :py:class:`typing.Text`. In ``typing`` since 3.5.2. 1169 1170.. class:: TextIO 1171 1172 See :py:class:`typing.TextIO`. 1173 1174 .. versionadded:: 4.7.0 1175 1176.. data:: Tuple 1177 1178 See :py:data:`typing.Tuple`. 1179 1180 .. versionadded:: 4.7.0 1181 1182.. class:: Type 1183 1184 See :py:class:`typing.Type`. In ``typing`` since 3.5.2. 1185 1186.. data:: TYPE_CHECKING 1187 1188 See :py:data:`typing.TYPE_CHECKING`. In ``typing`` since 3.5.2. 1189 1190.. data:: Union 1191 1192 See :py:data:`typing.Union`. 1193 1194 .. versionadded:: 4.7.0 1195 1196.. class:: ValuesView 1197 1198 See :py:class:`typing.ValuesView`. 1199 1200 .. versionadded:: 4.7.0 1201 1202.. function:: cast 1203 1204 See :py:func:`typing.cast`. 1205 1206 .. versionadded:: 4.7.0 1207 1208.. decorator:: no_type_check 1209 1210 See :py:func:`typing.no_type_check`. 1211 1212 .. versionadded:: 4.7.0 1213 1214.. decorator:: no_type_check_decorator 1215 1216 See :py:func:`typing.no_type_check_decorator`. 1217 1218 .. versionadded:: 4.7.0 1219 1220Security 1221-------- 1222 1223``typing_extensions`` is among the most widely used packages in the 1224Python ecosystem. Therefore, we take security seriously and strive 1225to use a transparent, secure release process. 1226 1227We commit to the following in order to keep the package secure in the 1228future: 1229 1230* ``typing_extensions`` will never include any native extensions, only 1231 pure Python code. 1232* ``typing_extensions`` will not have any third-party dependencies. 1233* We will follow best practices for a secure release process. 1234 1235If you have any feedback on our security process, please `open an issue 1236<https://github.com/python/typing_extensions/issues/new>`__. To report 1237an issue privately, use `GitHub's private reporting feature 1238<https://github.com/python/typing_extensions/security>`__. 1239