Python Type Stubs

Introduction

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.

Our Use of Type Stubs

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.

Trademarks

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.