As the Python team, we are helping to ensure that packages have high-quality type annotations. In cases where this must be done through type stubs, we are contributing stubs to typeshed. This repository contains our “work in progress”. Once the stubs for a package meet the requirements of typeshed, we will contribute them to typeshed and delete them from this repository.
Microsoft's Python Language Server Pylance uses type information to implement useful features like autocompletion and type checking. For best results, type annotations must be provided for functions, methods and variables.
There are two ways type annotations can be provided — through inline type annotations
and through .pyi
type stub files,
which may be bundled with the package or installed separately from some other source such as typeshed or PyPI.
We believe that the best approach for package authors is to have explicit inline type annotations
that accurately and completely describe their public interface contract. This allows tools to validate
the types for the package authors themselves and reduces the maintenance burden of keeping two separate
API definitions in sync. In cases where inline type annotations are not possible (e.g. for compiled
libraries), packages should include stub files that describe those portions of the interface.
We recognize that there may be cases where type stubs are more appropriate, such as:
- Package authors who do not want to include type annotations, and
- Large, complex packages where adding type annotations can take time, and stubs may be an appropriate intermediate step.
The following libraries have been contributed upstream (to typeshed or the libraries themselves) and are no longer maintained here:
- aiofiles
- cachetools
- deprecated
- filelock
- freezegun
- markdown
- packaging
- pandas (see https://github.com/pandas-dev/pandas-stubs; please open pandas stub issues there)
- PIL
- retry
- slugify
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.