Collection of library stubs for Python, with static types

Overview

typeshed

Build status Chat at https://gitter.im/python/typing Pull Requests Welcome

About

Typeshed contains external type annotations for the Python standard library and Python builtins, as well as third party packages as contributed by people external to those projects.

This data can e.g. be used for static analysis, type checking or type inference.

For information on how to use typeshed, read below. Information for contributors can be found in CONTRIBUTING.md. Please read it before submitting pull requests; do not report issues with annotations to the project the stubs are for, but instead report them here to typeshed.

Typeshed supports Python versions 2.7 and 3.6 and up.

Using

If you're just using mypy (or pytype or PyCharm), as opposed to developing it, you don't need to interact with the typeshed repo at all: a copy of standard library part of typeshed is bundled with mypy. And type stubs for third party packages and modules you are using can be installed from PyPI. For example, if you are using six and requests, you can install the type stubs using

$ pip install types-six types-requests

These PyPI packages follow PEP 561 and are automatically generated by typeshed internal machinery. Also starting from version 0.900 mypy will provide an option to automatically install missing type stub packages (if found on PyPI).

PyCharm, pytype etc. work in a similar way, for more details see documentation for the type-checking tool you are using.

Format

Each Python module is represented by a .pyi "stub file". This is a syntactically valid Python file, although it usually cannot be run by Python 3 (since forward references don't require string quotes). All the methods are empty.

Python function annotations (PEP 3107) are used to describe the signature of each function or method.

See PEP 484 for the exact syntax of the stub files and CONTRIBUTING.md for the coding style used in typeshed.

Directory structure

stdlib

This contains stubs for modules in the Python standard library -- which includes pure Python modules, dynamically loaded extension modules, hard-linked extension modules, and the builtins. VERSIONS file lists the oldest supported Python version where the module is available. In the stdlib/@python2 subdirectory you can find Python 2 versions of the stub files that must be kept different for Python 2 and 3, like builtins.pyi.

stubs

Modules that are not shipped with Python but have a type description in Python go into stubs. Each subdirectory there represents a PyPI distribution, and contains the following:

  • METADATA.toml that specifies oldest version of the source library for which the stubs are applicable, supported Python versions (Python 3 defaults to True, Python 2 defaults to False), and dependency on other type stub packages.
  • Stubs (i.e. *.pyi files) for packages and modules that are shipped in the source distribution. Similar to standard library, if the Python 2 version of the stubs must be kept separate, it can be put in a @python subdirectory.
  • (Rarely) some docs specific to a given type stub package in README file.

No other files are allowed in stdlib and stubs. When a third party stub is modified, an updated version of the corresponding distribution will be automatically uploaded to PyPI shortly (within few hours).

For more information on directory structure and stub versioning, see the relevant section of CONTRIBUTING.md.

Third-party packages are generally removed from typeshed when one of the following criteria is met:

  • The upstream package ships a py.typed file for at least 6-12 months, or
  • the package does not support any of the Python versions supported by typeshed.

Contributing

Please read CONTRIBUTING.md before submitting pull requests. If you have questions related to contributing, drop by the typing Gitter.

Running the tests

The tests are automatically run on every PR and push to the repo.

There are several tests:

  • tests/mypy_test.py tests typeshed with mypy
  • tests/pytype_test.py tests typeshed with pytype.
  • tests/mypy_self_check.py checks mypy's code base using this version of typeshed.
  • tests/mypy_test_suite.py runs a subset of mypy's test suite using this version of typeshed.
  • tests/check_consistent.py checks certain files in typeshed remain consistent with each other.
  • tests/stubtest_test.py checks stubs against the objects at runtime.
  • flake8 enforces a style guide.

Setup

Run:

$ python3.6 -m venv .venv3
$ source .venv3/bin/activate
(.venv3)$ pip install -U pip
(.venv3)$ pip install -r requirements-tests-py3.txt

This will install mypy (you need the latest master branch from GitHub), typed-ast, flake8 (and plugins), pytype, black and isort.

mypy_test.py

This test requires Python 3.6 or higher; Python 3.6.1 or higher is recommended. Run using:(.venv3)$ python3 tests/mypy_test.py

This test is shallow — it verifies that all stubs can be imported but doesn't check whether stubs match their implementation (in the Python standard library or a third-party package). It has an exclude list of modules that are not tested at all, which also lives in the tests directory.

If you are in the typeshed repo that is submodule of the mypy repo (so .. refers to the mypy repo), there's a shortcut to run the mypy tests that avoids installing mypy:

$ PYTHONPATH=../.. python3 tests/mypy_test.py

You can restrict mypy tests to a single version by passing -p2 or -p3.9:

$ PYTHONPATH=../.. python3 tests/mypy_test.py -p3.9
running mypy --python-version 3.9 --strict-optional # with 342 files

pytype_test.py

This test requires Python 2.7 and Python 3.6. Pytype will find these automatically if they're in PATH, but otherwise you must point to them with the --python27-exe and --python36-exe arguments, respectively. Run using: (.venv3)$ python3 tests/pytype_test.py

This test works similarly to mypy_test.py, except it uses pytype.

mypy_self_check.py

This test requires Python 3.6 or higher; Python 3.6.1 or higher is recommended. Run using: (.venv3)$ python3 tests/mypy_self_check.py

This test checks mypy's code base using mypy and typeshed code in this repo.

mypy_test_suite.py

This test requires Python 3.5 or higher; Python 3.6.1 or higher is recommended. Run using: (.venv3)$ python3 tests/mypy_test_suite.py

This test runs mypy's own test suite using the typeshed code in your repo. This will sometimes catch issues with incorrectly typed stubs, but is much slower than the other tests.

check_consistent.py

Run using: python3 tests/check_consistent.py

stubtest_test.py

This test requires Python 3.6 or higher. Run using (.venv3)$ python3 tests/stubtest_test.py

This test compares the stdlib stubs against the objects at runtime. Because of this, the output depends on which version of Python and on what kind of system it is run. Thus the easiest way to run this test is via Github Actions on your fork; if you run it locally, it'll likely complain about system-specific differences (in e.g, socket) that the type system cannot capture. If you need a specific version of Python to repro a CI failure, pyenv can help.

Due to its dynamic nature, you may run into false positives. In this case, you can add to the whitelists for each affected Python version in tests/stubtest_whitelists. Please file issues for stubtest false positives at mypy.

To run stubtest against third party stubs, it's easiest to use stubtest directly, with (.venv3)$ python3 -m mypy.stubtest --custom-typeshed-dir <path-to-typeshed> <third-party-module>. stubtest can also help you find things missing from the stubs.

flake8

flake8 requires Python 3.6 or higher. Run using: (.venv3)$ flake8

Note typeshed uses the flake8-pyi and flake8-bugbear plugins.

Owner
Python
Repositories related to the Python Programming language
Python
ticktock is a minimalist library to profile Python code

ticktock is a minimalist library to profile Python code: it periodically displays timing of running code.

Victor Benichoux 30 Sep 28, 2022
Alarmer is a tool focus on error reporting for your application.

alarmer Alarmer is a tool focus on error reporting for your application. Installation pip install alarmer Usage It's simple to integrate alarmer in yo

long2ice 20 Jul 03, 2022
Typical: Fast, simple, & correct data-validation using Python 3 typing.

typical: Python's Typing Toolkit Introduction Typical is a library devoted to runtime analysis, inference, validation, and enforcement of Python types

Sean 170 Dec 26, 2022
The strictest and most opinionated python linter ever!

wemake-python-styleguide Welcome to the strictest and most opinionated python linter ever. wemake-python-styleguide is actually a flake8 plugin with s

wemake.services 2.1k Jan 05, 2023
Collects all accepted (partial and full scored) codes submitted within the given timeframe and saves them locally for plagiarism check.

Collects all accepted (partial and full scored) codes submitted within the given timeframe of any contest.

ARITRA BELEL 2 Dec 28, 2021
A bytecode vm written in python.

CHex A bytecode vm written in python. hex command meaning note: the first two hex values of a CHex program are the magic number 0x01 (offset in memory

1 Aug 26, 2022
Collection of library stubs for Python, with static types

typeshed About Typeshed contains external type annotations for the Python standard library and Python builtins, as well as third party packages as con

Python 3.3k Jan 02, 2023
🦔 PostHog is developer-friendly, open-source product analytics.

PostHog provides open-source product analytics, built for developers. Automate the collection of every event on your website or app, with no need to send data to 3rd parties. With just 1 click you ca

PostHog 10.3k Jan 01, 2023
An interpreter for the X1 bytecode.

X1 Bytecode Interpreter The X1 Bytecode is bytecode designed for simplicity in programming design and compilation. Bytecode Instructions push

Thanasis Tzimas 1 Jan 15, 2022
Inspects Python source files and provides information about type and location of classes, methods etc

prospector About Prospector is a tool to analyse Python code and output information about errors, potential problems, convention violations and comple

Python Code Quality Authority 1.7k Dec 31, 2022
Checkov is a static code analysis tool for infrastructure-as-code.

Checkov - Prevent cloud misconfigurations during build-time for Terraform, Cloudformation, Kubernetes, Serverless framework and other infrastructure-as-code-languages with Checkov by Bridgecrew.

Bridgecrew 5.1k Jan 03, 2023
A very minimalistic python module that lets you track the time your code snippets take to run.

Clock Keeper A very minimalistic python module that lets you track the time your code snippets take to run. This package is available on PyPI! Run the

Rajdeep Biswas 1 Jan 19, 2022
A formatter for Python files

YAPF Introduction Most of the current formatters for Python --- e.g., autopep8, and pep8ify --- are made to remove lint errors from code. This has som

Google 13k Dec 31, 2022
Performant type-checking for python.

Pyre is a performant type checker for Python compliant with PEP 484. Pyre can analyze codebases with millions of lines of code incrementally – providi

Facebook 6.2k Jan 07, 2023
A Python utility / library to sort imports.

Read Latest Documentation - Browse GitHub Code Repository isort your imports, so you don't have to. isort is a Python utility / library to sort import

Python Code Quality Authority 5.5k Jan 06, 2023
An app to show the total number of lines of code written by an user.

Lines of code Have you ever wondered how many lines of code you wrote in github? This tool will calculate it for you! To calculate the total number of

B.Jothin kumar 10 Jan 26, 2022
Python package to parse and generate C/C++ code as context aware preprocessor.

Devana Devana is a python tool that make it easy to parsing, format, transform and generate C++ (or C) code. This tool uses libclang to parse the code

5 Dec 28, 2022
Turn your Python and Javascript code into DOT flowcharts

Notes from 2017 This is an older project which I am no longer working on. It was built before ES6 existed and before Python 3 had much usage. While it

Scott Rogowski 3k Jan 09, 2023
Typing-toolbox for Python 3 _and_ 2.7 w.r.t. PEP 484.

Welcome to the pytypes project pytypes is a typing toolbox w.r.t. PEP 484 (PEP 526 on the road map, later also 544 if it gets accepted). Its main feat

Stefan Richthofer 188 Dec 29, 2022
Run-time type checker for Python

This library provides run-time type checking for functions defined with PEP 484 argument (and return) type annotations. Four principal ways to do type

Alex Grönholm 1.1k Dec 19, 2022