Implement PEP 561 searching

docs/source/command_line.rst

@@ -8,17 +8,21 @@ summary of command line flags can always be printed using the ``-h``
 flag (or its long form ``--help``)::
 
  $ mypy -h
- usage: mypy [-h] [-v] [-V] [--python-version x.y] [--platform PLATFORM] [-2]
- [--ignore-missing-imports]
+ usage: mypy [-h] [-v] [-V] [--python-version x.y]
+ [--python-executable PYTHON_EXECUTABLE] [--platform PLATFORM] [-2]
+ [--ignore-missing-imports] [--no-site-packages]
  [--follow-imports {normal,silent,skip,error}]
- [--disallow-any-{unimported,expr,decorated,explicit,generics}]
- [--disallow-untyped-calls] [--disallow-untyped-defs]
+ [--disallow-any-unimported] [--disallow-any-expr]
+ [--disallow-any-decorated] [--disallow-any-explicit]
+ [--disallow-any-generics] [--disallow-untyped-calls]
+ [--disallow-untyped-defs] [--disallow-incomplete-defs]
  [--check-untyped-defs] [--disallow-subclassing-any]
- [--warn-incomplete-stub] [--warn-redundant-casts]
- [--no-warn-no-return] [--warn-return-any] [--warn-unused-ignores]
+ [--warn-incomplete-stub] [--disallow-untyped-decorators]
+ [--warn-redundant-casts] [--no-warn-no-return] [--warn-return-any]
+ [--warn-unused-ignores] [--warn-unused-configs]
  [--show-error-context] [--no-implicit-optional] [-i]
- [--quick-and-dirty] [--cache-dir DIR] [--skip-version-check]
- [--strict-optional]
+ [--quick-and-dirty] [--cache-dir DIR] [--cache-fine-grained]
+ [--skip-version-check] [--strict-optional]
  [--strict-optional-whitelist [GLOB [GLOB ...]]]
  [--junit-xml JUNIT_XML] [--pdb] [--show-traceback] [--stats]
  [--inferstats] [--custom-typing MODULE]
@@ -28,9 +32,9 @@ flag (or its long form ``--help``)::
  [--shadow-file SOURCE_FILE SHADOW_FILE] [--any-exprs-report DIR]
  [--cobertura-xml-report DIR] [--html-report DIR]
  [--linecount-report DIR] [--linecoverage-report DIR]
- [--memory-xml-report DIR]
- [--txt-report DIR] [--xml-report DIR] [--xslt-html-report DIR]
- [--xslt-txt-report DIR] [-m MODULE] [-c PROGRAM_TEXT] [-p PACKAGE]
+ [--memory-xml-report DIR] [--txt-report DIR] [--xml-report DIR]
+ [--xslt-html-report DIR] [--xslt-txt-report DIR] [-m MODULE]
+ [-c PROGRAM_TEXT] [-p PACKAGE]
  [files [files ...]]
 
  (etc., too long to show everything here)
@@ -366,11 +370,29 @@ Here are some more useful flags:
  updates the cache, but regular incremental mode ignores cache files
  written by quick mode.
 
+- ``--python-executable EXECUTABLE`` will have mypy collect type information
+ from `PEP 561`_ compliant
+ packages installed for the Python executable ``EXECUTABLE``. If not provided,
+ mypy will use PEP 561 compliant packages installed for the Python executable
+ running mypy. See :ref:`installed-packages` for more on making PEP 561
+ compliant packages. This flag will attempt to set ``--python-version`` if not
+ already set.
+
 - ``--python-version X.Y`` will make mypy typecheck your code as if it were
  run under Python version X.Y. Without this option, mypy will default to using
  whatever version of Python is running mypy. Note that the ``-2`` and
  ``--py2`` flags are aliases for ``--python-version 2.7``. See
- :ref:`version_and_platform_checks` for more about this feature.
+ :ref:`version_and_platform_checks` for more about this feature. This flag
+ will attempt to find a Python executable of the corresponding version to
+ search for `PEP 561`_ compliant
+ packages. If you'd like to disable this, see ``--no-site-packages`` below.
+
+- ``--no-site-packages`` will disable searching for 
+ `PEP 561`_ compliant packages.
+ This will also disable searching for a usable Python executable. Use this
+ flag if mypy cannot find a Python executable for the version of Python being
+ checked, and you don't need to use PEP 561 typed packages. Otherwise, use
+ ``--python-executable``.
 
 - ``--platform PLATFORM`` will make mypy typecheck your code as if it were
  run under the the given operating system. Without this option, mypy will
@@ -453,6 +475,9 @@ For the remaining flags you can read the full ``mypy -h`` output.
 
  Command line flags are liable to change between releases.
 
+
+.. _PEP 561: https://www.python.org/dev/peps/pep-0561/
+
 .. _integrating-mypy:
 
 Integrating mypy into another Python application

docs/source/index.rst

@@ -30,6 +30,7 @@ Mypy is a static type checker for Python.
  command_line
  config_file
  python36
+ installed_packages
  faq
  cheat_sheet
  cheat_sheet_py3

docs/source/installed_packages.rst

@@ -0,0 +1,114 @@
+.. _installed-packages:
+
+Using Installed Packages
+========================
+
+`PEP 561 <https://www.python.org/dev/peps/pep-0561/>`_ specifies how to mark
+a package as supporting type checking. Below is a summary of how to create
+PEP 561 compatible packages and have mypy use them in type checking.
+
+Making PEP 561 compatible packages
+**********************************
+
+Packages that must be imported at runtime and supply type information should
+put a ``py.typed`` in their package directory. For example, with a directory
+structure as follows:
+
+.. code-block:: text
+
+ setup.py
+ package_a/
+ __init__.py
+ lib.py
+ py.typed
+
+the setup.py might look like:
+
+.. code-block:: python
+
+ from distutils.core import setup
+
+ setup(
+ name="SuperPackageA",
+ author="Me",
+ version="0.1",
+ package_data={"package_a": ["py.typed"]},
+ packages=["package_a"]
+ )
+
+Some packages have a mix of stub files and runtime files. These packages also require
+a ``py.typed`` file. An example can be seen below:
+
+.. code-block:: text
+
+ setup.py
+ package_b/
+ __init__.py
+ lib.py
+ lib.pyi
+ py.typed
+
+the setup.py might look like:
+
+.. code-block:: python
+
+ from distutils.core import setup
+
+ setup(
+ name="SuperPackageB",
+ author="Me",
+ version="0.1",
+ package_data={"package_b": ["py.typed", "lib.pyi"]},
+ packages=["package_b"]
+ )
+
+In this example, both ``lib.py`` and ``lib.pyi`` exist. At runtime, ``lib.py``
+will be used, however mypy will use ``lib.pyi``.
+
+If the package is stub-only (not imported at runtime), the package should have
+a prefix of the runtime package name and a suffix of ``-stubs``.
+A ``py.typed`` file is not needed for stub-only packages. For example, if we
+had stubs for ``package_c``, we might do the following:
+
+.. code-block:: text
+
+ setup.py
+ package_c-stubs/
+ __init__.pyi
+ lib.pyi
+
+the setup.py might look like:
+
+.. code-block:: python
+
+ from distutils.core import setup
+
+ setup(
+ name="SuperPackageC",
+ author="Me",
+ version="0.1",
+ package_data={"package_c-stubs": ["__init__.pyi", "lib.pyi"]},
+ packages=["package_c-stubs"]
+ )
+
+Using PEP 561 compatible packages with mypy
+*******************************************
+
+Generally, you do not need to do anything to use installed packages for the
+Python executable used to run mypy. They should be automatically picked up by
+mypy and used for type checking.
+
+By default, mypy searches for packages installed for the Python executable
+running mypy. It is highly unlikely you want this situation if you have
+installed typed packages in another Python's package directory.
+
+Generally, you can use the ``--python-version`` flag and mypy will try to find
+the correct package directory. If that fails, you can use the
+``--python-executable`` flag to point to the exact executable, and mypy will
+find packages installed for that Python executable.
+
+Note that mypy does not support some more advanced import features, such as zip
+imports, namespace packages, and custom import hooks.
+
+If you do not want to use typed packages, use the ``--no-site-packages`` flag
+to disable searching.