From 3adacd366f110ff76a3021e6c26b5598d45aff20 Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Mon, 13 Jul 2026 17:32:01 +0200 Subject: [PATCH 1/3] Add guidance for missing dependencies --- CONTRIBUTING.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 695874627a5d..c40e531f03b2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -233,6 +233,42 @@ distribution. The format of all `METADATA.toml` files can be checked by running `python3 ./tests/check_typeshed_structure.py`. +### Dependencies + +When a third-party stub package depends on another package, there are several +strategies available, depending on whether the other package is typed. + +1. If the other package is typed and includes a `py.typed` marker, add that + package to the `dependencies` key in `METADATA.toml. This might fail the + stub uploader checks, in which case you can ask the maintainers for help. +2. Otherwise, if a type package is available, add that package to the + `dependencies` key. If the type package originates from typeshed, the + stub uploader checks should succeed. +3. In case the dependency in untyped and no stubs are available, you may stub + the dependency in your type stubs. For example: + + ```python + from typing import Any + # from fruzzle import Frobnicator # won't work + + _Frobnicator: TypeAlias = Any # actually fruzzle.Frobnicator + ``` + + In more complex or advanced cases you may instead opt to add a stubs + is a separate helper package: + + ```python + # stubs/my-stubs/my_stubs/_fruzzle.pyi + + # Utility stubs for the untyped "fruzzle" package. + + from typing import Any, Protocol + + Frobnicator: TypeAlias = Any + + class Flubberer(Protocol): + def flubb_it(self, x: int, /) -> str: ... + ``` ## Making Changes From a94806d0494bf57e082f75c1d64d325f34902136 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 13 Jul 2026 15:34:24 +0000 Subject: [PATCH 2/3] [pre-commit.ci] auto fixes from pre-commit.com hooks --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c40e531f03b2..cbdfde131545 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -265,7 +265,7 @@ strategies available, depending on whether the other package is typed. from typing import Any, Protocol Frobnicator: TypeAlias = Any - + class Flubberer(Protocol): def flubb_it(self, x: int, /) -> str: ... ``` From 08c6814a63057e97b22757eb10e7fb9ca50c626e Mon Sep 17 00:00:00 2001 From: Sebastian Rittau Date: Mon, 13 Jul 2026 18:22:02 +0200 Subject: [PATCH 3/3] Fix formatting --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index cbdfde131545..910416aed6e2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -239,7 +239,7 @@ When a third-party stub package depends on another package, there are several strategies available, depending on whether the other package is typed. 1. If the other package is typed and includes a `py.typed` marker, add that - package to the `dependencies` key in `METADATA.toml. This might fail the + package to the `dependencies` key in `METADATA.toml`. This might fail the stub uploader checks, in which case you can ask the maintainers for help. 2. Otherwise, if a type package is available, add that package to the `dependencies` key. If the type package originates from typeshed, the