Skip to content

Commit ac31da9

Browse files
authored
Rework the "Supported Type System Features" section (#16490)
- Rename to "Unsupported ...". - Remove list of supported features. - Instead add a note that everything is supported, unless noted otherwise. - Add generics syntax and type statements as unsupported. - List `TypeForm` in `typing_extensions` import list. - Move the section about `bytes` promotions to a separate section and reword slightly.
1 parent 3b003a6 commit ac31da9

1 file changed

Lines changed: 23 additions & 31 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 23 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -366,6 +366,16 @@ documentation. Whenever you find them disagreeing, model the type
366366
information after the actual implementation and file an issue on the
367367
project's tracker to fix their documentation.
368368

369+
### Byte Types
370+
371+
[PEP 688](https://www.python.org/dev/peps/pep-0688/) removes
372+
th implicit promotion from `bytearray` and `memoryview` to `bytes`.
373+
Typeshed stubs should be written assuming that these promotions
374+
do not happen, so a parameter that accepts either `bytes` or
375+
`bytearray` should be typed as `bytes | bytearray`.
376+
Often one of the aliases from `_typeshed`, such as
377+
`_typeshed.ReadableBuffer`, can be used instead.
378+
369379
### Deprecations (using the `@deprecated` decorator)
370380

371381
Generally deprecactions using the `@deprecated` decorator are added more
@@ -410,27 +420,18 @@ When the script has finished running, it will print instructions telling you wha
410420
If it has been a while since you set up the virtualenv, make sure you have
411421
the latest mypy (`pip install -r requirements-tests.txt`) before running the script.
412422

413-
### Supported type system features
414-
415-
Since [PEP 484](https://peps.python.org/pep-0484/) was accepted, there have been
416-
many other PEPs that added new features to the Python type system. In general,
417-
new features can be used in typeshed as soon as the PEP has been accepted and
418-
implemented and most type checkers support the new feature.
419-
420-
Supported features include:
421-
- [PEP 544](https://peps.python.org/pep-0544/) (`Protocol`)
422-
- [PEP 585](https://peps.python.org/pep-0585/) (builtin generics)
423-
- [PEP 586](https://peps.python.org/pep-0586/) (`Literal`)
424-
- [PEP 591](https://peps.python.org/pep-0591/) (`Final`/`@final`)
425-
- [PEP 589](https://peps.python.org/pep-0589/) (`TypedDict`)
426-
- [PEP 604](https://peps.python.org/pep-0604/) (`Foo | Bar` union syntax)
427-
- [PEP 612](https://peps.python.org/pep-0612/) (`ParamSpec`)
428-
- [PEP 647](https://peps.python.org/pep-0647/) (`TypeGuard`):
429-
see [#5406](https://github.com/python/typeshed/issues/5406)
430-
- [PEP 655](https://peps.python.org/pep-0655/) (`Required` and `NotRequired`)
431-
- [PEP 673](https://peps.python.org/pep-0673/) (`Self`)
432-
- [PEP 675](https://peps.python.org/pep-0675/) (`LiteralString`)
433-
- [PEP 702](https://peps.python.org/pep-0702/) (`@deprecated()`)
423+
### Unsupported Type System Features
424+
425+
Unless listed here, all type system features that have been added to the
426+
[Python typing specification](https://typing.python.org/en/latest/spec/)
427+
can be used. The following features are *not* supported:
428+
429+
- [PEP 695](https://peps.python.org/pep-0695/) type parameter syntax.
430+
(See [issue #10869](https://github.com/python/typeshed/issues/10869).) Use
431+
explicit `TypeVar` definitions.
432+
- [PEP 695](https://peps.python.org/pep-0695/) type statement for aliases.
433+
(See [issue #10870](https://github.com/python/typeshed/issues/10870).) Use
434+
`TypeAlias` annotations.
434435

435436
Features from the `typing` module that are not present in all
436437
supported Python versions must be imported from `typing_extensions`
@@ -443,16 +444,7 @@ instead in typeshed stubs. This currently affects:
443444
- `Required` and `NotRequired` (new in Python 3.11)
444445
- `Buffer` (new in Python 3.12; in the `collections.abc` module)
445446
- `@deprecated` (new in Python 3.13; in the `warnings` module)
446-
447-
Some type checkers implicitly promote the `bytearray` and
448-
`memoryview` types to `bytes`.
449-
[PEP 688](https://www.python.org/dev/peps/pep-0688/) removes
450-
this implicit promotion.
451-
Typeshed stubs should be written assuming that these promotions
452-
do not happen, so a parameter that accepts either `bytes` or
453-
`bytearray` should be typed as `bytes | bytearray`.
454-
Often one of the aliases from `_typeshed`, such as
455-
`_typeshed.ReadableBuffer`, can be used instead.
447+
- `TypeForm` (new in Python 3.15)
456448

457449
## Submitting Changes
458450

0 commit comments

Comments
 (0)