Skip to content

CONTRIBUTING: Add @deprecated, other updates #11005

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 18, 2023
Merged

CONTRIBUTING: Add @deprecated, other updates #11005

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dc3b09a
CONTRIBUTING: Add @deprecated, other updates
JelleZijlstra Nov 10, 2023
635cff6
PEP 702 to partially supported; reword guidance on how to use it
JelleZijlstra Nov 18, 2023
8b7c0b6
Update CONTRIBUTING.md
JelleZijlstra Nov 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
72 changes: 51 additions & 21 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -285,21 +285,25 @@ Accepted features that *cannot* yet be used in typeshed include:
use argument names prefixed with `__` instead

The following features are partially supported:
- [PEP 585](https://www.python.org/dev/peps/pep-0585/) (builtin
generics): see [#4820](https://github.com/python/typeshed/issues/4820),
mostly supported but bugs remain for a few specific cases
- [PEP 612](https://www.python.org/dev/peps/pep-0612/) (ParamSpec):
see [#4827](https://github.com/python/typeshed/issues/4827),
supported in some contexts but requires `# type: ignore` comments
- [PEP 702](https://peps.python.org/pep-0702/) (`@deprecated()`)
- For now, cannot be used in combination with other decorators
(e.g., `@overload`, `@classmethod`, and `@property`) due to bugs in
[pytype](https://github.com/google/pytype/issues/1531) and
[stubtest](https://github.com/python/mypy/pull/16457).

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 604](https://www.python.org/dev/peps/pep-0604/) (`Foo | Bar` union syntax)
- [PEP 647](https://www.python.org/dev/peps/pep-0647/) (TypeGuard):
- [PEP 544](https://peps.python.org/pep-0544/) (Protocol)
- [PEP 585](https://peps.python.org/pep-0585/) (builtin generics)
- [PEP 586](https://peps.python.org/pep-0586/) (Literal)
- [PEP 591](https://peps.python.org/pep-0591/) (Final/@final)
- [PEP 589](https://peps.python.org/pep-0589/) (TypedDict)
- [PEP 604](https://peps.python.org/pep-0604/) (`Foo | Bar` union syntax)
- [PEP 612](https://peps.python.org/pep-0612/) (ParamSpec)
- [PEP 647](https://peps.python.org/pep-0647/) (TypeGuard):
see [#5406](https://github.com/python/typeshed/issues/5406)
- [PEP 655](https://peps.python.org/pep-0655/) (`Required` and `NotRequired`)
- [PEP 673](https://peps.python.org/pep-0673/) (`Self`)
- [PEP 675](https://peps.python.org/pep-0675/) (`LiteralString`)

Features from the `typing` module that are not present in all
supported Python 3 versions must be imported from `typing_extensions`
Expand All @@ -312,16 +316,20 @@ instead in typeshed stubs. This currently affects:
- `Concatenate` (new in Python 3.10)
- `ParamSpec` (new in Python 3.10)
- `TypeGuard` (new in Python 3.10)
- `Self` (new in Python 3.11)
- `LiteralString` (new in Python 3.11)
- `@deprecated` (new in Python 3.13; in the `warnings` module)

Two exceptions are `Protocol` and `runtime_checkable`: although
these were added in Python 3.8, they can be used in stubs regardless
of Python version.

[PEP 688](https://www.python.org/dev/peps/pep-0688/), which is
currently a draft, removes the implicit promotion of the
`bytearray` and `memoryview` classes to `bytes`.
Typeshed stubs should be written assuming that this proposal
is accepted, so a parameter that accepts either `bytes` or
Some type checkers implicitly promote the `bytearray` and
`memoryview` types to `bytes`.
[PEP 688](https://www.python.org/dev/peps/pep-0688/) removes
this implicit promotion.
Typeshed stubs should be written assuming that these promotions
do not happen, so a parameter that accepts either `bytes` or
`bytearray` should be typed as `bytes | bytearray`.
Often one of the aliases from `_typeshed`, such as
`_typeshed.ReadableBuffer`, can be used instead.
Expand Down Expand Up @@ -448,7 +456,7 @@ Some further tips for good type hints:
of importing them from `typing`.
* use `X | Y` instead of `Union[X, Y]` and `X | None`, instead of
`Optional[X]`;
* in Python 3 stubs, import collections (`Mapping`, `Iterable`, etc.)
* import collections (`Mapping`, `Iterable`, etc.)
from `collections.abc` instead of `typing`;
* avoid invariant collection types (`list`, `dict`) in argument
positions, in favor of covariant types like `Mapping` or `Sequence`;
Expand Down Expand Up @@ -485,9 +493,7 @@ a stub file. You can also use the name of the class within its own
body. Focus on making your stubs clear to the reader. Avoid using
string literals in type annotations.

Type variables and aliases you introduce purely for legibility reasons
should be prefixed with an underscore to make it obvious to the reader
they are not part of the stubbed API.
### Context managers

When adding type annotations for context manager classes, annotate
the return type of `__exit__` as bool only if the context manager
Expand All @@ -502,6 +508,12 @@ See https://github.com/python/mypy/issues/7214 for more details.
current class should be annotated with the `_typeshed.Self` type
variable ([example](https://github.com/python/typeshed/pull/5698)).

### Naming

Type variables and aliases you introduce purely for legibility reasons
should be prefixed with an underscore to make it obvious to the reader
they are not part of the stubbed API.

A few guidelines for protocol names below. In cases that don't fall
into any of those categories, use your best judgement.

Expand All @@ -512,6 +524,24 @@ into any of those categories, use your best judgement.
* Use `HasX` for protocols that have readable and/or writable attributes
or getter/setter methods (e.g. `HasItems`, `HasFileno`).

### `@deprecated`

Typeshed uses the `@typing_extensions.deprecated` decorator
(`@warnings.deprecated` since Python 3.13) to mark deprecated
functionality; see [PEP 702](https://peps.python.org/pep-0702/).

A few guidelines for how to use it:

* In the standard library, apply the decorator only in Python versions
Copy link
Collaborator

@hauntsaninja hauntsaninja Nov 10, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Commented in the issue, but I think it would be nice to be more aggressive in cases where an appropriate replacement already exists. (I couldn't quite tell if there was consensus in the issue, if there was then that's fine!)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree now, reworded the section to say we should apply it to versions where a good replacement exists.

where an appropriate replacement for the deprecated functionality
exists. If in doubt, apply the decorator only on versions where the
functionality has been explicitly deprecated, either through runtime
warnings or in the documentation. Use `if sys.version_info` checks to
apply the decorator only to some versions.
* Keep the deprecation message concise, but try to mention the projected
version when the functionality is to be removed, and a suggested
replacement.

### Incomplete annotations

When submitting new stubs, it is not necessary to annotate all arguments,
Expand Down