Document and distribute type hints

hypothesis-python/RELEASE.rst

@@ -0,0 +1,9 @@
+RELEASE_TYPE: minor
+
+This release adds :PEP:`484` type hints to Hypothesis on a provisional
+basis, using the comment-based syntax for Python 2 compatibility.  You
+can :ref:`read more about our type hints here <our-type-hints>`.
+
+It *also* adds the ``py.typed`` marker specified in :PEP:`561`.
+Having installed Hypothesis, :pypi:`mypy` 0.590 or later will
+therefore type-check your use of our public interface!

hypothesis-python/docs/details.rst

@@ -543,3 +543,65 @@ changes between Python 3.5.0 and 3.6.1, including at minor versions.  These
 are all supported on a best-effort basis, but you may encounter problems with
 an old version of the module.  Please report them to us, and consider
 updating to a newer version of Python as a workaround.
+
+
+.. _our-type-hints:
+
+------------------------------
+Type Annotations in Hypothesis
+------------------------------
+
+If you install Hypothesis and use :pypi:`mypy` 0.590+, or another
+:PEP:`561`-compatible tool, the type checker should automatically pick
+up our type hints.
+
+.. note::
+    Hypothesis' type hints may make breaking changes between minor releases.
+
+Upstream tools and conventions about type hints remain in flux - for
+example the :mod:`python:typing` module itself is provisional, and Mypy
+has not yet reached version 1.0 - and we plan to support the latest
+version of this ecosystem, as well as older versions where practical.
+
+We may also find more precise ways to describe the type of various
+interfaces, or change their type and runtime behaviour togther in a way
+which is otherwise backwards-compatible.  Type hints may not support
+deprecated features or arguments, as an additional form of warning.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Writing downstream type hints
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Projects that :doc:`provide Hypothesis strategies <strategies>` and use
+type hints may wish to annotate their strategies too.  This *is* a
+supported use-case, again on a best-effort provisional basis.  For example:
+
+.. code:: python
+
+    def foo_strategy() -> SearchStrategy[Foo]: ...
+
+:class:`~hypothesis.strategies.SearchStrategy` is the type of all strategy
+objects.  It is a generic type, and covariant in the type of the examples
+it creates.  For example:
+
+.. doctest::
+
+    >>> from hypothesis.strategies import SearchStrategy
+    >>> isinstance(integers(), SearchStrategy)
+    True
+
+- ``integers()`` is of type ``SearchStrategy[int]``.
+- ``lists(integers())`` is of type ``SearchStrategy[List[int]]``.
+- ``SearchStrategy[bool]`` is a subtype of ``SearchStrategy[int]``,
+  because ``bool`` is a subtype of ``int``.
+
+.. warning::
+    :class:`~hypothesis.strategies.SearchStrategy` **should only be used
+    in type hints.**  The only supported way to construct objects of this
+    type is to use the functions provided by the :mod:`hypothesis.strategies`
+    module!
+
+Please do not inherit from, compare to, or otherwise use the
+:class:`~hypothesis.strategies.SearchStrategy` in any way outside of type
+hints.  This is a private, internal interface that is *only* available for
+type checking, and may be changed or removed in any minor release.

hypothesis-python/setup.py

@@ -85,7 +85,7 @@ def local_file(name):
     author_email='david@drmaciver.com',
     packages=setuptools.find_packages(SOURCE),
     package_dir={'': SOURCE},
-    # package_data={'': ['py.typed']},  # un-comment to release type hints
+    package_data={'': ['py.typed']},
     url=(
         'https://github.com/HypothesisWorks/hypothesis/'
         'tree/master/hypothesis-python'