1Code in this repository should follow CPython's style guidelines and
2contributors need to sign the PSF Contributor Agreement.
3
4# typing\_extensions
5
6The `typing_extensions` module provides a way to access new features from the standard
7library `typing` module in older versions of Python. For example, Python 3.10 adds
8`typing.TypeGuard`, but users of older versions of Python can use `typing_extensions` to
9use `TypeGuard` in their code even if they are unable to upgrade to Python 3.10.
10
11If you contribute the runtime implementation of a new `typing` feature to CPython, you
12are encouraged to also implement the feature in `typing_extensions`. Because the runtime
13implementation of much of the infrastructure in the `typing` module has changed over
14time, this may require different code for some older Python versions.
15
16`typing_extensions` may also include experimental features that are not yet part of the
17standard library, so that users can experiment with them before they are added to the
18standard library. Such features should already be specified in a PEP or merged into
19CPython's `main` branch.
20
21# Versioning scheme
22
23Starting with version 4.0.0, `typing_extensions` uses
24[Semantic Versioning](https://semver.org/). See the documentation
25for more detail.
26
27# Type stubs
28
29A stub file for `typing_extensions` is maintained
30[in typeshed](https://github.com/python/typeshed/blob/main/stdlib/typing_extensions.pyi).
31Because of the special status that `typing_extensions` holds in the typing ecosystem,
32the stubs are placed in the standard library in typeshed and distributed as
33part of the stubs bundled with individual type checkers.
34
35# Running tests
36
37Testing `typing_extensions` can be tricky because many development tools depend on
38`typing_extensions`, so you may end up testing some installed version of the library,
39rather than your local code.
40
41The simplest way to run the tests locally is:
42
43- `cd src/`
44- `python test_typing_extensions.py`
45
46Alternatively, you can invoke `unittest` explicitly:
47
48- `python -m unittest test_typing_extensions.py`
49
50Running these commands in the `src/` directory ensures that the local file
51`typing_extensions.py` is used, instead of any other version of the library you
52may have installed.
53
54# Workflow for PyPI releases
55
56- Make sure you follow the versioning policy in the documentation
57  (e.g., release candidates before any feature release)
58
59- Ensure that GitHub Actions reports no errors.
60
61- Update the version number in `typing_extensions/pyproject.toml` and in
62  `typing_extensions/CHANGELOG.md`.
63
64- Create a new GitHub release at https://github.com/python/typing_extensions/releases/new.
65  Details:
66  - The tag should be just the version number, e.g. `4.1.1`.
67  - Copy the release notes from `CHANGELOG.md`.
68
69- Release automation will finish the release. You'll have to manually
70  approve the last step before upload.
71