Collection of library stubs for Python, with static types
Python Shell
Latest commit 59789b8 Feb 22, 2017 @lincolnq lincolnq committed with ambv Improve types for xml.etree.ElementTree (#930)
* Improve types for xml.etree.ElementTree

Update signatures to reflect the following peculiarities of the
ElementTree library:

- The elementtree library accepts unicode or bytes for most xml values
  in python2, and coerces everywhere -- but in python3, only str makes
- In python 2, the library produces str or unicode instances
  unpredictably, depending on whether the xml is decodeable as ascii or
  not. In python 3, it always produces str instances.
- The parser functions accept unicode or bytes in 2 and 3 -- again, will
  coerce individual instances so heterogeneous lists are ok.
- In python 3, the tostring functions produce bytes or str, depending on
  the value of the 'encoding' parameter.

* improve docs
* Improve ElementFactory type by specifying dict of 2nd arg



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

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 Please read it before submitting pull requests.


Each Python module is represented by a .pyi "stub". This is a normal Python file (i.e., it can be interpreted by Python 3), except all the methods are empty. Python function annotations (PEP 3107) are used to describe the types the function has.

See PEP 484 for the exact syntax of the stub files.

Syntax example

The below is an excerpt from the types for the datetime module.

MAXYEAR = ...  # type: int
MINYEAR = ...  # type: int

class date(object):
    def __init__(self, year: int, month: int, day: int) -> None: ...
    def fromtimestamp(cls, timestamp: int or float) -> date: ...
    def fromordinal(cls, ordinal: int) -> date: ...
    def today(self) -> date: ...
    def ctime(self) -> str: ...
    def weekday(self) -> int: ...

Directory structure


This contains stubs for modules the Python standard library -- which includes pure Python modules, dynamically loaded extension modules, hard-linked extension modules, and the builtins.


Modules that are not shipped with Python but have a type description in Python go into third_party. Since these modules can behave differently for different versions of Python, third_party has version subdirectories, just like stdlib.

NOTE: When you're contributing a new stub for a package that you did not develop, please obtain consent of the package owner (this is specified in PEP 484). The best way to obtain consent is to file an issue in the third-party package's tracker and include the link to a positive response in your PR for typeshed.

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


Please read before submitting pull requests.

Running the tests

The tests are automatically run by Travis CI on every PR and push to the repo. There are two separate sets of tests: tests/ runs tests against mypy, while tests/ runs tests against pytype. The script runs both sets of tests and flake8 over all .pyi files.

Both sets of tests are shallow -- they verify that all stubs can be imported but they don't check whether stubs match their implementation (in the Python standard library or a third-party package). Also note that each set of tests has a blacklist of modules that are not tested at all. The blacklists also live in the tests directory.

To manually run the mypy tests, you need to have Python 3.5 or higher. Run:

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

This will install mypy-lang, typed-ast, and flake8. You can then run mypy tests and flake8 tests by invoking:

(.venv3)$ python tests/
(.venv3)$ flake8

To run the pytype tests, you need a separate virtual environment with Python 2.7. Run:

$ virtualenv --python=python2.7 .venv2
$ source .venv2/bin/activate
(.venv2)$ pip install -r requirements-tests-py2.txt

This will install pytype from its GitHub repo. You can then run pytype tests by running:

(.venv2)$ python tests/

To be able to everything with, copy the pytype script from the Python 2 virtualenv to the Python 3 one:

$ cp .venv2/bin/pytype .venv3/bin/pytype
$ source .venv3/bin/activate
(.venv3)$ ./
running mypy --python-version 3.6 --strict-optional --fast-parser # with 479 files
running mypy --python-version 3.5 --strict-optional # with 469 files
running mypy --python-version 3.4 --strict-optional # with 469 files
running mypy --python-version 3.3 --strict-optional # with 454 files
running mypy --python-version 3.2 --strict-optional # with 453 files
running mypy --python-version 2.7 --strict-optional # with 502 files
Running pytype tests...
Ran pytype with 244 pyis, got 0 errors.
Running flake8...
flake8 run clean.

For mypy, 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/

You can mypy tests to a single version by passing -p2 or -p3.5 e.g.

$ PYTHONPATH=.. python3 tests/ -p3.5
running mypy --python-version 3.5 --strict-optional # with 342 files