|
|
a4aba9f |
Mypy: Optional Static Typing for Python
|
|
|
a4aba9f |
=======================================
|
|
|
a4aba9f |
|
|
|
a4aba9f |
[![Build Status](https://travis-ci.org/python/mypy.svg)](https://travis-ci.org/python/mypy)
|
|
|
a4aba9f |
|
|
|
a4aba9f |
|
|
|
9878e9d |
Got a question? File an issue!
|
|
|
9878e9d |
------------------------------
|
|
|
9878e9d |
|
|
|
9878e9d |
We don't have a mailing list; but we are always happy to answer questions
|
|
|
9878e9d |
filed as issues in our [tracker](https://github.com/python/mypy/issues).
|
|
|
9878e9d |
|
|
|
9878e9d |
|
|
|
a4aba9f |
What is mypy?
|
|
|
a4aba9f |
-------------
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Mypy is an optional static type checker for Python. You can add type
|
|
|
fbd8101 |
hints to your Python programs using the standard for type
|
|
|
25462fb |
annotations introduced in Python 3.5 ([PEP 484](https://www.python.org/dev/peps/pep-0484/)), and use mypy to
|
|
|
a4aba9f |
type check them statically. Find bugs in your programs without even
|
|
|
a4aba9f |
running them!
|
|
|
a4aba9f |
|
|
|
fbd8101 |
The type annotation standard has also been backported to earlier
|
|
|
fbd8101 |
Python 3.x versions. Mypy supports Python 3.2 and later.
|
|
|
fbd8101 |
|
|
|
fbd8101 |
For Python 2.7, you can add annotations as comments (this is also
|
|
|
25462fb |
specified in [PEP 484](https://www.python.org/dev/peps/pep-0484/)).
|
|
|
a4aba9f |
|
|
|
a4aba9f |
You can mix dynamic and static typing in your programs. You can always
|
|
|
a4aba9f |
fall back to dynamic typing when static typing is not convenient, such
|
|
|
a4aba9f |
as for legacy code.
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Here is a small example to whet your appetite:
|
|
|
a4aba9f |
|
|
|
25462fb |
```python
|
|
|
a4aba9f |
from typing import Iterator
|
|
|
a4aba9f |
|
|
|
a4aba9f |
def fib(n: int) -> Iterator[int]:
|
|
|
a4aba9f |
a, b = 0, 1
|
|
|
a4aba9f |
while a < n:
|
|
|
a4aba9f |
yield a
|
|
|
a4aba9f |
a, b = b, a + b
|
|
|
a4aba9f |
```
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Mypy is in development; some features are missing and there are bugs.
|
|
|
a4aba9f |
See 'Development status' below.
|
|
|
a4aba9f |
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Requirements
|
|
|
a4aba9f |
------------
|
|
|
a4aba9f |
|
|
|
a4aba9f |
You need Python 3.2 or later to run mypy. You can have multiple Python
|
|
|
a4aba9f |
versions (2.x and 3.x) installed on the same system without problems.
|
|
|
a4aba9f |
|
|
|
a4aba9f |
In Ubuntu, Mint and Debian you can install Python 3 like this:
|
|
|
a4aba9f |
|
|
|
a4aba9f |
$ sudo apt-get install python3 python3-pip
|
|
|
a4aba9f |
|
|
|
a4aba9f |
For other Linux flavors, OS X and Windows, packages are available at
|
|
|
a4aba9f |
|
|
|
a4aba9f |
http://www.python.org/getit/
|
|
|
a4aba9f |
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Quick start
|
|
|
a4aba9f |
-----------
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Mypy can be installed using pip:
|
|
|
a4aba9f |
|
|
|
a4aba9f |
$ pip3 install mypy-lang
|
|
|
a4aba9f |
|
|
|
a4aba9f |
*Note that the package name is `mypy-lang`, not `mypy`.*
|
|
|
a4aba9f |
|
|
|
fbd8101 |
If you want to run the latest version of the code, you can install from git:
|
|
|
a4aba9f |
|
|
|
a4aba9f |
$ pip3 install git+git://github.com/python/mypy.git
|
|
|
a4aba9f |
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Now, if Python on your system is configured properly (else see
|
|
|
a4aba9f |
"Troubleshooting" below), you can type-check a program like this:
|
|
|
a4aba9f |
|
|
|
a4aba9f |
$ mypy PROGRAM
|
|
|
a4aba9f |
|
|
|
a4aba9f |
You can always use a Python interpreter to run your statically typed
|
|
|
a4aba9f |
programs, even if they have type errors:
|
|
|
a4aba9f |
|
|
|
a4aba9f |
$ python3 PROGRAM
|
|
|
a4aba9f |
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Web site and documentation
|
|
|
a4aba9f |
--------------------------
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Documentation and additional information is available at the web site:
|
|
|
a4aba9f |
|
|
|
a4aba9f |
http://www.mypy-lang.org/
|
|
|
a4aba9f |
|
|
|
fbd8101 |
Or you can jump straight to the documentation:
|
|
|
fbd8101 |
|
|
|
fbd8101 |
http://mypy.readthedocs.io/
|
|
|
fbd8101 |
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Troubleshooting
|
|
|
a4aba9f |
---------------
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Depending on your configuration, you may have to run `pip` like
|
|
|
a4aba9f |
this:
|
|
|
a4aba9f |
|
|
|
a4aba9f |
$ python3 -m pip install mypy-lang
|
|
|
a4aba9f |
|
|
|
a4aba9f |
If the `mypy` command isn't found after installation: After either
|
|
|
a4aba9f |
`pip3 install` or `setup.py install`, the `mypy` script and
|
|
|
a4aba9f |
dependencies, including the `typing` module, will be installed to
|
|
|
a4aba9f |
system-dependent locations. Sometimes the script directory will not
|
|
|
a4aba9f |
be in `PATH`, and you have to add the target directory to `PATH`
|
|
|
a4aba9f |
manually or create a symbolic link to the script. In particular, on
|
|
|
a4aba9f |
Mac OS X, the script may be installed under `/Library/Frameworks`:
|
|
|
a4aba9f |
|
|
|
a4aba9f |
/Library/Frameworks/Python.framework/Versions/<version>/bin
|
|
|
a4aba9f |
|
|
|
a4aba9f |
In Windows, the script is generally installed in
|
|
|
a4aba9f |
`\PythonNN\Scripts`. So, type check a program like this (replace
|
|
|
a4aba9f |
`\Python34` with your Python installation path):
|
|
|
a4aba9f |
|
|
|
a4aba9f |
C:\>\Python34\python \Python34\Scripts\mypy PROGRAM
|
|
|
a4aba9f |
|
|
|
25462fb |
### Working with `virtualenv`
|
|
|
25462fb |
|
|
|
25462fb |
If you are using [`virtualenv`](https://virtualenv.pypa.io/en/stable/),
|
|
|
25462fb |
make sure you are running a python3 environment. Installing via `pip3`
|
|
|
25462fb |
in a v2 environment will not configure the environment to run installed
|
|
|
25462fb |
modules from the command line.
|
|
|
25462fb |
|
|
|
25462fb |
$ python3 -m pip install virtualenv
|
|
|
25462fb |
$ python3 -m virtualenv env
|
|
|
25462fb |
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Quick start for contributing to mypy
|
|
|
a4aba9f |
------------------------------------
|
|
|
a4aba9f |
|
|
|
a4aba9f |
If you want to contribute, first clone the mypy git repository:
|
|
|
a4aba9f |
|
|
|
a4aba9f |
$ git clone --recurse-submodules https://github.com/python/mypy.git
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Run the supplied `setup.py` script to install mypy:
|
|
|
a4aba9f |
|
|
|
a4aba9f |
$ python3 setup.py install
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Replace `python3` with your Python 3 interpreter. You may have to do
|
|
|
a4aba9f |
the above as root. For example, in Ubuntu and Mac OS X:
|
|
|
a4aba9f |
|
|
|
a4aba9f |
$ sudo python3 setup.py install
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Now you can use the `mypy` program just as above. In case of trouble
|
|
|
a4aba9f |
see "Troubleshooting" above.
|
|
|
a4aba9f |
|
|
|
a4aba9f |
The mypy wiki contains some useful information for contributors:
|
|
|
a4aba9f |
|
|
|
fbd8101 |
https://github.com/python/mypy/wiki/Developer-Guides
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Working with the git version of mypy
|
|
|
a4aba9f |
------------------------------------
|
|
|
a4aba9f |
|
|
|
a4aba9f |
mypy contains a submodule, "typeshed". See http://github.com/python/typeshed.
|
|
|
a4aba9f |
This submodule contains types for the Python standard library.
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Due to the way git submodules work, you'll have to do
|
|
|
a4aba9f |
```
|
|
|
a4aba9f |
git submodule update typeshed
|
|
|
a4aba9f |
```
|
|
|
a4aba9f |
whenever you change branches, merge, rebase, or pull.
|
|
|
a4aba9f |
|
|
|
a4aba9f |
(It's possible to automate this: Search Google for "git hook update submodule")
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Running tests and linting
|
|
|
a4aba9f |
-------------------------
|
|
|
a4aba9f |
|
|
|
a4aba9f |
First install any additional dependencies needed for testing:
|
|
|
a4aba9f |
|
|
|
a4aba9f |
$ pip3 install -r test-requirements.txt
|
|
|
a4aba9f |
|
|
|
a4aba9f |
To run all tests, run the script `runtests.py` in the mypy repository:
|
|
|
a4aba9f |
|
|
|
a4aba9f |
$ ./runtests.py
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Note that some tests will be disabled for older python versions.
|
|
|
a4aba9f |
|
|
|
a4aba9f |
This will run all tests, including integration and regression tests,
|
|
|
a4aba9f |
and will type check mypy and verify that all stubs are valid. You can also
|
|
|
a4aba9f |
run unit tests only, which run pretty quickly:
|
|
|
a4aba9f |
|
|
|
a4aba9f |
$ ./runtests.py unit-test
|
|
|
a4aba9f |
|
|
|
a4aba9f |
You can run a subset of test suites by passing positive or negative
|
|
|
a4aba9f |
filters:
|
|
|
a4aba9f |
|
|
|
a4aba9f |
$ ./runtests.py lex parse -x lint -x stub
|
|
|
a4aba9f |
|
|
|
a4aba9f |
If you want to run individual unit tests, you can run `myunit` directly, or
|
|
|
a4aba9f |
pass inferior arguments via `-a`:
|
|
|
a4aba9f |
|
|
|
fbd8101 |
$ PYTHONPATH=$PWD scripts/myunit -m mypy.test.testlex -v '*backslash*'
|
|
|
a4aba9f |
$ ./runtests.py mypy.test.testlex -a -v -a '*backslash*'
|
|
|
a4aba9f |
|
|
|
a4aba9f |
You can also run the type checker for manual testing without
|
|
|
fbd8101 |
installing anything by setting up the Python module search path
|
|
|
fbd8101 |
suitably (the lib-typing/3.2 path entry is not needed for Python 3.5
|
|
|
fbd8101 |
or when you have manually installed the `typing` module):
|
|
|
a4aba9f |
|
|
|
a4aba9f |
$ export PYTHONPATH=$PWD:$PWD/lib-typing/3.2
|
|
|
a4aba9f |
$ python<version> -m mypy PROGRAM.py
|
|
|
a4aba9f |
|
|
|
a4aba9f |
You can add the entry scripts to PATH for a single python3 version:
|
|
|
a4aba9f |
|
|
|
a4aba9f |
$ export PATH=$PWD/scripts
|
|
|
a4aba9f |
$ mypy PROGRAM.py
|
|
|
a4aba9f |
|
|
|
a4aba9f |
You can check a module or string instead of a file:
|
|
|
a4aba9f |
|
|
|
a4aba9f |
$ mypy PROGRAM.py
|
|
|
a4aba9f |
$ mypy -m MODULE
|
|
|
a4aba9f |
$ mypy -c 'import MODULE'
|
|
|
a4aba9f |
|
|
|
a4aba9f |
To run the linter:
|
|
|
a4aba9f |
|
|
|
a4aba9f |
$ ./runtests.py lint
|
|
|
a4aba9f |
|
|
|
a4aba9f |
|
|
|
fbd8101 |
Coverage reports
|
|
|
fbd8101 |
----------------
|
|
|
fbd8101 |
|
|
|
fbd8101 |
There is an experimental feature to generate coverage reports. To use
|
|
|
fbd8101 |
this feature, you need to `pip install lxml`. This is an extension
|
|
|
fbd8101 |
module and requires various library headers to install; on a
|
|
|
fbd8101 |
Debian-derived system the command
|
|
|
fbd8101 |
apt-get install python3-dev libxml2-dev libxslt1-dev
|
|
|
fbd8101 |
may provide the necessary dependencies.
|
|
|
fbd8101 |
|
|
|
fbd8101 |
To use the feature, pass e.g. `--txt-report "$(mktemp -d)"`.
|
|
|
fbd8101 |
|
|
|
fbd8101 |
|
|
|
a4aba9f |
Development status
|
|
|
a4aba9f |
------------------
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Mypy is work in progress and is not yet production quality, though
|
|
|
a4aba9f |
mypy development has been done using mypy for a while!
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Here are some of the more significant Python features not supported
|
|
|
a4aba9f |
right now (but all of these will improve):
|
|
|
a4aba9f |
|
|
|
a4aba9f |
- Python 2.x support needs polish and documentation
|
|
|
a4aba9f |
- properties with setters not supported
|
|
|
a4aba9f |
- limited metaclass support
|
|
|
a4aba9f |
- only a subset of Python standard library modules are supported, and some
|
|
|
a4aba9f |
only partially
|
|
|
a4aba9f |
- 3rd party module support is limited
|
|
|
a4aba9f |
|
|
|
a4aba9f |
The current development focus is to have a good coverage of Python
|
|
|
a4aba9f |
features and the standard library (both 3.x and 2.7).
|
|
|
a4aba9f |
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Issue tracker
|
|
|
a4aba9f |
-------------
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Please report any bugs and enhancement ideas using the mypy issue
|
|
|
a4aba9f |
tracker:
|
|
|
a4aba9f |
|
|
|
a4aba9f |
https://github.com/python/mypy/issues
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Feel free to also ask questions on the tracker.
|
|
|
a4aba9f |
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Help wanted
|
|
|
a4aba9f |
-----------
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Any help in testing, development, documentation and other tasks is
|
|
|
a4aba9f |
highly appreciated and useful to the project. Contact the developers
|
|
|
a4aba9f |
to join the project, or just start coding and send pull requests!
|
|
|
a4aba9f |
There are tasks for contributors of all experience levels.
|
|
|
a4aba9f |
|
|
|
fbd8101 |
For more details, see the file [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
|
fbd8101 |
|
|
|
a4aba9f |
|
|
|
a4aba9f |
License
|
|
|
a4aba9f |
-------
|
|
|
a4aba9f |
|
|
|
a4aba9f |
Mypy is licensed under the terms of the MIT License (see the file
|
|
|
a4aba9f |
LICENSE).
|