CONTRIBUTING.md - third_party/github.com/python/typing_extensions - Git at Google


            
            Code in this repository should follow CPython's style guidelines and

            
            contributors need to sign the PSF Contributor Agreement.


            # typing\_extensions


            The `typing_extensions` module provides a way to access new features from the standard

            
            library `typing` module in older versions of Python. For example, Python 3.10 adds

            
            `typing.TypeGuard`, but users of older versions of Python can use `typing_extensions` to

            
            use `TypeGuard` in their code even if they are unable to upgrade to Python 3.10.


            If you contribute the runtime implementation of a new `typing` feature to CPython, you

            
            are encouraged to also implement the feature in `typing_extensions`. Because the runtime

            
            implementation of much of the infrastructure in the `typing` module has changed over

            
            time, this may require different code for some older Python versions.


            `typing_extensions` may also include experimental features that are not yet part of the

            
            standard library, so that users can experiment with them before they are added to the

            
            standard library. Such features should already be specified in a PEP or merged into

            
            CPython's `main` branch.


            # Versioning scheme


            Starting with version 4.0.0, `typing_extensions` uses

            
            [Semantic Versioning](https://semver.org/). [See the documentation](https://typing-extensions.readthedocs.io/en/latest/#versioning-and-backwards-compatibility)

            
            for more detail.


            # Type stubs


            A stub file for `typing_extensions` is maintained

            
            [in typeshed](https://github.com/python/typeshed/blob/main/stdlib/typing_extensions.pyi).

            
            Because of the special status that `typing_extensions` holds in the typing ecosystem,

            
            the stubs are placed in the standard library in typeshed and distributed as

            
            part of the stubs bundled with individual type checkers.


            # Running tests


            Testing `typing_extensions` can be tricky because many development tools depend on

            
            `typing_extensions`, so you may end up testing some installed version of the library,

            
            rather than your local code.


            The simplest way to run the tests locally is:


            - `cd src/`

            
            - `python test_typing_extensions.py`


            Alternatively, you can invoke `unittest` explicitly:


            - `python -m unittest test_typing_extensions.py`


            Running these commands in the `src/` directory ensures that the local file

            
            `typing_extensions.py` is used, instead of any other version of the library you

            
            may have installed.


            # Building the documentation


            To build the documentation in nitpicky mode and treat warnings as errors, run:


            ```

            
            uvx --from sphinx sphinx-build -n -W -b html doc doc/_build/html

            
            ```


            The generated HTML documentation is written to `doc/_build/html`.


            # Linting


            Linting is done via pre-commit. We recommend running pre-commit via a tool such

            
            as [uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/stable/) so

            
            that pre-commit and its dependencies are installed into an isolated environment

            
            located outside your `typing_extensions` clone. Running pre-commit this way

            
            ensures that you don't accidentally install a version of `typing_extensions`

            
            from PyPI into a virtual environment inside your `typing_extensions` clone,

            
            which could easily happen if pre-commit depended (directly or indirectly) on

            
            `typing_extensions`. If a version of `typing_extensions` from PyPI *was*

            
            installed into a project-local virtual environment, it could lead to

            
            unpredictable results when running `typing_extensions` tests locally.


            To run the linters using uv:


            ```

            
            uvx pre-commit run -a

            
            ```


            Or using pipx:


            ```

            
            pipx run pre-commit run -a

            
            ```


            # Workflow for PyPI releases


            - Make sure that the version in `pyproject.toml` and `CHANGELOG.md` follows the versioning policy outlined in

            
              [the documentation](https://typing-extensions.readthedocs.io/en/latest/#versioning-and-backwards-compatibility).


            - Ensure that GitHub Actions reports no errors.


            - Check that `CHANGELOG.md` accurately reflects all important changes committed to `main` since the previous release.


            - Update the version number in `typing_extensions/pyproject.toml` and in

            
              `typing_extensions/CHANGELOG.md` by removing `.dev0` and potentially adding the `rcX` suffix:

            
              - `4.1.0.dev0` → `4.1.0rc1` for the initial release candidate

            
              - `4.1.0rc2.dev0` → `4.1.0rc2` or `4.1.0`, depending on whether the release is a second release candidate or a full release

            
              - `4.1.1.dev0` → `4.1.1` when making a hotfix release


            - Create a new GitHub release at https://github.com/python/typing_extensions/releases/new.

            
              Details:

            
              - The tag should be just the version number, e.g. `4.1.1`.

            
              - Copy the release notes from `CHANGELOG.md`.


            - Release automation will finish the release. You'll have to manually

            
              approve the last step before upload.


            - After the release has been published on PyPI upgrade the patch or rc version number in [pyproject.toml](/pyproject.toml) and append `.dev0`. For example:

            
                - `4.1.1` → `4.1.2.dev0`

            
                - `4.1.0rc1` → `4.1.0rc2.dev0`
	Code in this repository should follow CPython's style guidelines and
	contributors need to sign the PSF Contributor Agreement.

	# typing\_extensions

	The `typing_extensions` module provides a way to access new features from the standard
	library `typing` module in older versions of Python. For example, Python 3.10 adds
	`typing.TypeGuard`, but users of older versions of Python can use `typing_extensions` to
	use `TypeGuard` in their code even if they are unable to upgrade to Python 3.10.

	If you contribute the runtime implementation of a new `typing` feature to CPython, you
	are encouraged to also implement the feature in `typing_extensions`. Because the runtime
	implementation of much of the infrastructure in the `typing` module has changed over
	time, this may require different code for some older Python versions.

	`typing_extensions` may also include experimental features that are not yet part of the
	standard library, so that users can experiment with them before they are added to the
	standard library. Such features should already be specified in a PEP or merged into
	CPython's `main` branch.

	# Versioning scheme

	Starting with version 4.0.0, `typing_extensions` uses
	[Semantic Versioning](https://semver.org/). [See the documentation](https://typing-extensions.readthedocs.io/en/latest/#versioning-and-backwards-compatibility)
	for more detail.

	# Type stubs

	A stub file for `typing_extensions` is maintained
	[in typeshed](https://github.com/python/typeshed/blob/main/stdlib/typing_extensions.pyi).
	Because of the special status that `typing_extensions` holds in the typing ecosystem,
	the stubs are placed in the standard library in typeshed and distributed as
	part of the stubs bundled with individual type checkers.

	# Running tests

	Testing `typing_extensions` can be tricky because many development tools depend on
	`typing_extensions`, so you may end up testing some installed version of the library,
	rather than your local code.

	The simplest way to run the tests locally is:

	- `cd src/`
	- `python test_typing_extensions.py`

	Alternatively, you can invoke `unittest` explicitly:

	- `python -m unittest test_typing_extensions.py`

	Running these commands in the `src/` directory ensures that the local file
	`typing_extensions.py` is used, instead of any other version of the library you
	may have installed.

	# Building the documentation

	To build the documentation in nitpicky mode and treat warnings as errors, run:

	```
	uvx --from sphinx sphinx-build -n -W -b html doc doc/_build/html
	```

	The generated HTML documentation is written to `doc/_build/html`.

	# Linting

	Linting is done via pre-commit. We recommend running pre-commit via a tool such
	as [uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/stable/) so
	that pre-commit and its dependencies are installed into an isolated environment
	located outside your `typing_extensions` clone. Running pre-commit this way
	ensures that you don't accidentally install a version of `typing_extensions`
	from PyPI into a virtual environment inside your `typing_extensions` clone,
	which could easily happen if pre-commit depended (directly or indirectly) on
	`typing_extensions`. If a version of `typing_extensions` from PyPI was
	installed into a project-local virtual environment, it could lead to
	unpredictable results when running `typing_extensions` tests locally.

	To run the linters using uv:

	```
	uvx pre-commit run -a
	```

	Or using pipx:

	```
	pipx run pre-commit run -a
	```

	# Workflow for PyPI releases

	- Make sure that the version in `pyproject.toml` and `CHANGELOG.md` follows the versioning policy outlined in
	[the documentation](https://typing-extensions.readthedocs.io/en/latest/#versioning-and-backwards-compatibility).

	- Ensure that GitHub Actions reports no errors.

	- Check that `CHANGELOG.md` accurately reflects all important changes committed to `main` since the previous release.

	- Update the version number in `typing_extensions/pyproject.toml` and in
	`typing_extensions/CHANGELOG.md` by removing `.dev0` and potentially adding the `rcX` suffix:
	- `4.1.0.dev0` → `4.1.0rc1` for the initial release candidate
	- `4.1.0rc2.dev0` → `4.1.0rc2` or `4.1.0`, depending on whether the release is a second release candidate or a full release
	- `4.1.1.dev0` → `4.1.1` when making a hotfix release

	- Create a new GitHub release at https://github.com/python/typing_extensions/releases/new.
	Details:
	- The tag should be just the version number, e.g. `4.1.1`.
	- Copy the release notes from `CHANGELOG.md`.

	- Release automation will finish the release. You'll have to manually
	approve the last step before upload.

	- After the release has been published on PyPI upgrade the patch or rc version number in [pyproject.toml](/pyproject.toml) and append `.dev0`. For example:
	- `4.1.1` → `4.1.2.dev0`
	- `4.1.0rc1` → `4.1.0rc2.dev0`