|
| 1 | +# Typing Extensions |
| 2 | + |
| 3 | +[](https://gitter.im/python/typing) |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +The `typing_extensions` module serves two related purposes: |
| 8 | + |
| 9 | +- Enable use of new type system features on older Python versions. For example, |
| 10 | + `typing.TypeGuard` is new in Python 3.10, but `typing_extensions` allows |
| 11 | + users on Python 3.6 through 3.9 to use it too. |
| 12 | +- Enable experimentation with new type system PEPs before they are accepted and |
| 13 | + added to the `typing` module. |
| 14 | + |
| 15 | +New features may be added to `typing_extensions` as soon as they are specified |
| 16 | +in a PEP that has been added to the [python/peps](https://github.com/python/peps) |
| 17 | +repository. If the PEP is accepted, the feature will then be added to `typing` |
| 18 | +for the next CPython release. No typing PEP has been rejected so far, so we |
| 19 | +haven't yet figured out how to deal with that possibility. |
| 20 | + |
| 21 | +Starting with version 4.0.0, `typing_extensions` uses |
| 22 | +[Semantic Versioning](https://semver.org/). The |
| 23 | +major version is incremented for all backwards-incompatible changes. |
| 24 | +Therefore, it's safe to depend |
| 25 | +on `typing_extensions` like this: `typing_extensions >=x.y, <(x+1)`, |
| 26 | +where `x.y` is the first version that includes all features you need. |
| 27 | + |
| 28 | +`typing_extensions` supports Python versions 3.7 and higher. In the future, |
| 29 | +support for older Python versions will be dropped some time after that version |
| 30 | +reaches end of life. |
| 31 | + |
| 32 | +## Included items |
| 33 | + |
| 34 | +This module currently contains the following: |
| 35 | + |
| 36 | +- Experimental features |
| 37 | + |
| 38 | + - `@dataclass_transform()` (see PEP 681) |
| 39 | + |
| 40 | +- In `typing` since Python 3.11 |
| 41 | + |
| 42 | + - `assert_never` |
| 43 | + - `assert_type` |
| 44 | + - `clear_overloads` |
| 45 | + - `get_overloads` |
| 46 | + - `LiteralString` (see PEP 675) |
| 47 | + - `Never` |
| 48 | + - `NotRequired` (see PEP 655) |
| 49 | + - `reveal_type` |
| 50 | + - `Required` (see PEP 655) |
| 51 | + - `Self` (see PEP 673) |
| 52 | + - `TypeVarTuple` (see PEP 646) |
| 53 | + - `Unpack` (see PEP 646) |
| 54 | + |
| 55 | +- In `typing` since Python 3.10 |
| 56 | + |
| 57 | + - `Concatenate` (see PEP 612) |
| 58 | + - `ParamSpec` (see PEP 612) |
| 59 | + - `ParamSpecArgs` (see PEP 612) |
| 60 | + - `ParamSpecKwargs` (see PEP 612) |
| 61 | + - `TypeAlias` (see PEP 613) |
| 62 | + - `TypeGuard` (see PEP 647) |
| 63 | + - `is_typeddict` |
| 64 | + |
| 65 | +- In `typing` since Python 3.9 |
| 66 | + |
| 67 | + - `Annotated` (see PEP 593) |
| 68 | + |
| 69 | +- In `typing` since Python 3.8 |
| 70 | + |
| 71 | + - `final` (see PEP 591) |
| 72 | + - `Final` (see PEP 591) |
| 73 | + - `Literal` (see PEP 586) |
| 74 | + - `Protocol` (see PEP 544) |
| 75 | + - `runtime_checkable` (see PEP 544) |
| 76 | + - `TypedDict` (see PEP 589) |
| 77 | + - `get_origin` (`typing_extensions` provides this function only in Python 3.7+) |
| 78 | + - `get_args` (`typing_extensions` provides this function only in Python 3.7+) |
| 79 | + |
| 80 | +- In `typing` since Python 3.7 |
| 81 | + |
| 82 | + - `OrderedDict` |
| 83 | + |
| 84 | +- In `typing` since Python 3.5 or 3.6 (see [the typing documentation](https://docs.python.org/3.10/library/typing.html) for details) |
| 85 | + |
| 86 | + - `AsyncContextManager` |
| 87 | + - `AsyncGenerator` |
| 88 | + - `AsyncIterable` |
| 89 | + - `AsyncIterator` |
| 90 | + - `Awaitable` |
| 91 | + - `ChainMap` |
| 92 | + - `ClassVar` (see PEP 526) |
| 93 | + - `ContextManager` |
| 94 | + - `Coroutine` |
| 95 | + - `Counter` |
| 96 | + - `DefaultDict` |
| 97 | + - `Deque` |
| 98 | + - `NewType` |
| 99 | + - `NoReturn` |
| 100 | + - `overload` |
| 101 | + - `Text` |
| 102 | + - `Type` |
| 103 | + - `TYPE_CHECKING` |
| 104 | + - `get_type_hints` |
| 105 | + |
| 106 | +# Other Notes and Limitations |
| 107 | + |
| 108 | +Certain objects were changed after they were added to `typing`, and |
| 109 | +`typing_extensions` provides a backport even on newer Python versions: |
| 110 | + |
| 111 | +- `TypedDict` does not store runtime information |
| 112 | + about which (if any) keys are non-required in Python 3.8, and does not |
| 113 | + honor the `total` keyword with old-style `TypedDict()` in Python |
| 114 | + 3.9.0 and 3.9.1. |
| 115 | +- `get_origin` and `get_args` lack support for `Annotated` in |
| 116 | + Python 3.8 and lack support for `ParamSpecArgs` and `ParamSpecKwargs` |
| 117 | + in 3.9. |
| 118 | +- `@final` was changed in Python 3.11 to set the `.__final__` attribute. |
| 119 | +- `@overload` was changed in Python 3.11 to make function overloads |
| 120 | + introspectable at runtime. In order to access overloads with |
| 121 | + `typing_extensions.get_overloads()`, you must use |
| 122 | + `@typing_extensions.overload`. |
| 123 | + |
| 124 | +There are a few types whose interface was modified between different |
| 125 | +versions of typing. For example, `typing.Sequence` was modified to |
| 126 | +subclass `typing.Reversible` as of Python 3.5.3. |
| 127 | + |
| 128 | +These changes are _not_ backported to prevent subtle compatibility |
| 129 | +issues when mixing the differing implementations of modified classes. |
| 130 | + |
| 131 | +Certain types have incorrect runtime behavior due to limitations of older |
| 132 | +versions of the typing module: |
| 133 | + |
| 134 | +- `ParamSpec` and `Concatenate` will not work with `get_args` and |
| 135 | + `get_origin`. Certain PEP 612 special cases in user-defined |
| 136 | + `Generic`s are also not available. |
| 137 | + |
| 138 | +These types are only guaranteed to work for static type checking. |
| 139 | + |
| 140 | +## Running tests |
| 141 | + |
| 142 | +To run tests, navigate into the appropriate source directory and run |
| 143 | +`test_typing_extensions.py`. |
0 commit comments