From 6d38f5a2e8fb479f838268333053050c3f21995f Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 16 May 2021 19:03:55 -0700 Subject: [PATCH 1/5] Add section on supported type-system features To help contributors keep track of which features can be used in stubs. --- CONTRIBUTING.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ff1809904ff6..757401f304bc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -126,6 +126,31 @@ See [PEP 484](http://www.python.org/dev/peps/pep-0484/) for the exact syntax of the stub files and [below](#stub-file-coding-style) for the coding style used in typeshed. +### Supported type system features + +Since PEP 484 was accepted, there have been many other PEPs that added +new features to the Python type system. In general, new features can +be used in typeshed as soon as the PEP has been accepted and implemented +and most type checkers support the new feature. + +Accepted features that cannot yet be used in typeshed include: +- [PEP 570](https://www.python.org/dev/peps/pep-0570/) (positional-only + arguments): see [#4972](https://github.com/python/typeshed/issues/4972), + use argument names prefixed with `__` instead +- [PEP 585](https://www.python.org/dev/peps/pep-0585/) (builtin + generics): see [#4820](https://github.com/python/typeshed/issues/4820), + mostly supported bug bugs remain for a few specific cases +- [PEP 604](https://www.python.org/dev/peps/pep-0604/) (Union + pipe operator): see [#4819](https://github.com/python/typeshed/issues/4819) +- [PEP 612](https://www.python.org/dev/peps/pep-0612/) (ParamSpec): + see [#4827](https://github.com/python/typeshed/issues/4827) +- [PEP 613](https://www.python.org/dev/peps/pep-0613/) (TypeAlias): + see [#4913](https://github.com/python/typeshed/issues/4913) + +Features for which support was recently added include: +- [PEP 647](https://www.python.org/dev/peps/pep-0647/) (TypeGuard): + see [#5406](https://github.com/python/typeshed/issues/5406) + ### What to include Stubs should include the complete interface (classes, functions, From a0694d75650e7345353362a09dd7f22099c68ba2 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 16 May 2021 19:04:41 -0700 Subject: [PATCH 2/5] emphasis --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 757401f304bc..a006ed05ec84 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -133,7 +133,7 @@ new features to the Python type system. In general, new features can be used in typeshed as soon as the PEP has been accepted and implemented and most type checkers support the new feature. -Accepted features that cannot yet be used in typeshed include: +Accepted features that *cannot* yet be used in typeshed include: - [PEP 570](https://www.python.org/dev/peps/pep-0570/) (positional-only arguments): see [#4972](https://github.com/python/typeshed/issues/4972), use argument names prefixed with `__` instead From 3386a5fc5b30078b394738ab01144784ab956a75 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 16 May 2021 19:48:03 -0700 Subject: [PATCH 3/5] say that you need to use `typing_extension` --- CONTRIBUTING.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a006ed05ec84..f9ad4f0416b5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -151,6 +151,19 @@ Features for which support was recently added include: - [PEP 647](https://www.python.org/dev/peps/pep-0647/) (TypeGuard): see [#5406](https://github.com/python/typeshed/issues/5406) +Features from the `typing` module that are not present in all +supported Python 3 versions must be imported from `typing_extensions` +instead in typeshed stubs. This currently affects: + +- `Final` and `@final` (new in Python 3.8) +- `Literal` (new in Python 3.8) +- `SupportsIndex` (new in Python 3.8) +- `TypedDict` (new in Python 3.8) +- `TypeGuard` (new in Python 3.10) + +An exception is `Protocol`: although it was added in Python 3.8, it +can be used in stubs regardless of Python version. + ### What to include Stubs should include the complete interface (classes, functions, From 66311ba1b5d59729a2f89362f60ff4a49bdce10c Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 16 May 2021 19:56:34 -0700 Subject: [PATCH 4/5] list other supported features --- CONTRIBUTING.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f9ad4f0416b5..cab652cd6a7d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -147,7 +147,11 @@ Accepted features that *cannot* yet be used in typeshed include: - [PEP 613](https://www.python.org/dev/peps/pep-0613/) (TypeAlias): see [#4913](https://github.com/python/typeshed/issues/4913) -Features for which support was recently added include: +Supported features include: +- [PEP 544](https://www.python.org/dev/peps/pep-0544/) (Protocol) +- [PEP 586](https://www.python.org/dev/peps/pep-0586/) (Literal) +- [PEP 591](https://www.python.org/dev/peps/pep-0591/) (Final/@final) +- [PEP 589](https://www.python.org/dev/peps/pep-0589/) (TypedDict) - [PEP 647](https://www.python.org/dev/peps/pep-0647/) (TypeGuard): see [#5406](https://github.com/python/typeshed/issues/5406) From 6da36dc9e191b8a4d2015ce5ab1ffad9dcc72ef8 Mon Sep 17 00:00:00 2001 From: Jelle Zijlstra Date: Sun, 16 May 2021 20:03:38 -0700 Subject: [PATCH 5/5] bug bug --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cab652cd6a7d..648b5d8328ea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -139,7 +139,7 @@ Accepted features that *cannot* yet be used in typeshed include: use argument names prefixed with `__` instead - [PEP 585](https://www.python.org/dev/peps/pep-0585/) (builtin generics): see [#4820](https://github.com/python/typeshed/issues/4820), - mostly supported bug bugs remain for a few specific cases + mostly supported but bugs remain for a few specific cases - [PEP 604](https://www.python.org/dev/peps/pep-0604/) (Union pipe operator): see [#4819](https://github.com/python/typeshed/issues/4819) - [PEP 612](https://www.python.org/dev/peps/pep-0612/) (ParamSpec):