Good ways to contribute

[hauntsaninja]

Welcome to typeshed! Like most projects, reading our CONTRIBUTING.md and scrolling through our issues is a good way to find things that need improvement. In fact, many of our issues should be fixable by beginners, even if not marked as such.

However, unlike many projects, there are other very easy ways to find improvements to be made, without relying on people running into and filing issues. Here are some things you can do (click on details for the details):

1) Use stubtest to find things missing from or problematic with stubs.

stubtest is a tool that comes bundled with mypy. It compares stubs to what it can deduce from importing and introspecting the library at runtime.

$ pip install mypy
# to find potential issues with the module sys
$ stubtest --custom-typeshed-dir ~/your_copy_of/typeshed sys --concise

We maintain a list of existing stubtest errors on the standard library and third party stubs, that we're looking to either fix or to add a comment explaining why stubtest should be ignored:
Allowlist of errors for the stdlib
Example of allowlist for a third party stub

These lists of existing errors do not include things that are missing entirely from the stubs, so running stubtest yourself (without --ignore-missing-stub) can be a good way to identify places where stubs are missing definitions entirely.

If you have an idea, you could even teach stubtest new tricks to find issues, like #3968

2) Use stricter mypy settings to identify issues with stubs.

mypy has a lot of different flags that could help identify improvements. For instance, I recommend using the following patch and re-running the test to find places where typeshed stubs are missing annotations:

diff --git a/tests/mypy_test.py b/tests/mypy_test.py
index f32da57f..e94e5a29 100755
--- a/tests/mypy_test.py
+++ b/tests/mypy_test.py
@@ -136,6 +136,8 @@ def main():
             flags.append('--no-implicit-optional')
             flags.append('--disallow-any-generics')
             flags.append('--disallow-subclassing-any')
+            flags.append('--disallow-incomplete-defs')
+            flags.append('--warn-incomplete-stub')
             if args.warn_unused_ignores:
                 flags.append('--warn-unused-ignores')
             if args.platform:

Similarly, we run checks against some stubs with looser pyright settings. By running with a more strict pyright setting, we can find issues.

3) Contribute stubs for a new library.

We've had requests for stubs for at least the following libraries:

zxcvbn
pyspark
psutil
pymongo
setuptools
python-future
pyzmq
pynput
z3
pony

Take a look at CONTRIBUTING.md for more guidance, but note that for larger libraries we accept partial / incomplete stubs. Note that you should check whether the library already provides (or is interested in providing) inline types or in-package stubs — types are typically best maintained by library authors.

4) Literally just grep for the words "incomplete" or "TODO"

As mentioned in point 3, we accept partial / incomplete stubs. As recommended by https://github.com/python/typeshed/blob/master/CONTRIBUTING.md#incomplete-stubs, these are marked with a comment that says # incomplete. They're waiting for you to complete them!

Another thing to search for is module level def __getattr__. stubtest is pretty good with helping point out ways to complete stubs.

5) Update third party stubs

We currently specify a specific version of a third party package our stubs are meant to describe in each stub's METADATA.toml file. Changing this version to the latest and seeing what stubtest has to say is a great way to help keep type information up to date.

Also note that several of the previous points apply, in particular, fixing existing errors in the stubtest allowlist for a third party package (allowlist can be found in the @tests directory)

(Other maintainers: feel free to edit the text of this issue as you see fit)

[Avasam]

A new way to easily find some low-hanging fruits, thanks to @AlexWaygood , is through https://alexwaygood.github.io/typeshed-stats/stats-csv/.
One can sort by unannotated_parameters to find stubs that are considered incomplete in pyright (and are not using the stricter checks).
Or by explicit_Incomplete_* to sort stubs by how many incomplete definitions there are left.
Or by stubtest_strictness to find stubs that are still missing definitions with MISSING_STUBS_IGNORED.

---

Something I've been doing as well, is looking at https://github.com/microsoft/python-type-stubs for stubs that can be merged / upstreamed to typeshed.

[JonathanPlasse]

We maintain a list of existing stubtest errors on the standard library and third party stubs, that we're looking to either fix or to add a comment explaining why stubtest should be ignored: Allowlist of errors for the stdlib Example of allowlist for a third party stub

The link of Allowlist of errors for the stdlib is dead.

[AlexWaygood]

The link of Allowlist of errors for the stdlib is dead.

We keep them here these days: https://github.com/python/typeshed/tree/main/stdlib/%40tests/stubtest_allowlists.

If you fancy helping out with updating our stubs for py313 in particular, I put together a guide for that specifically in #11990!