Merge pull request #604 from Zac-HD/minor-doc-updates

Updates to docs, clarifying supported versions

docs/changes.rst

@@ -851,9 +851,9 @@ Bug fixes:
 
 Fix support for fixtures on Django 1.7.
 
------------------------------------------------------------------------
-`1.10.4 <https://hypothesis.readthedocs.io/en/1.10.4/>`_ - 2015-08-21
------------------------------------------------------------------------
+-------------------
+1.10.4 - 2015-08-21
+-------------------
 
 Tiny bug fix release:
 
@@ -982,9 +982,9 @@ Another small bugfix release:
   default alphabet. In particular produces a better distribution of ascii and
   whitespace in the alphabet.
 
----------------------------------------------------------------------
-`1.8.1 <https://hypothesis.readthedocs.io/en/1.8.1/>`_ - 2015-07-17
----------------------------------------------------------------------
+------------------
+1.8.1 - 2015-07-17
+------------------
 
 This is a small release that contains a workaround for people who have
 bad reprs returning non ascii text on Python 2.7. This is not a bug fix
@@ -1074,9 +1074,9 @@ Bug fixes:
   than min\_satisfying\_examples.
 
 
----------------------------------------------------------------------
-`1.6.2 <https://hypothesis.readthedocs.io/en/1.6.2/>`_ - 2015-06-08
----------------------------------------------------------------------
+------------------
+1.6.2 - 2015-06-08
+------------------
 
 This is just a few small bug fixes:
 
@@ -1089,9 +1089,9 @@ This is just a few small bug fixes:
   floating point interval so narrow there are only a handful of values in it,
   this will no longer cause an error when Hypothesis runs out of values.
 
----------------------------------------------------------------------
-`1.6.1 <https://hypothesis.readthedocs.io/en/1.6.1/>`_ - 2015-05-21
----------------------------------------------------------------------
+------------------
+1.6.1 - 2015-05-21
+------------------
 
 This is a small patch release that fixes a bug where 1.6.0 broke the use
 of flatmap with the deprecated API and assumed the passed in function returned

docs/community.rst

@@ -8,18 +8,11 @@ who can answer your questions and help you out. Please do join us.
 The two major places for community discussion are:
 
 * `The mailing list <https://groups.google.com/forum/#!forum/hypothesis-users>`_.
-* An IRC channel: #hypothesis on freenode.
+* An IRC channel, #hypothesis on freenode, which is more active than the mailing list.
 
 Feel free to use these to ask for help, provide feedback, or discuss anything remotely
 Hypothesis related at all.
 
-The IRC channel is the more active of the two. If you don't know how to use
-IRC, don't worry about it. Just `click here to sign up to IRCCloud and log in <https://www.irccloud.com/invite?hostname=irc.freenode.net&channel=%23hypothesis>`_
-(don't worry, it's free).
-
-(IRCCloud is made by friends of mine, but that's not why I'm recommending it. I'm
-recommending it because it's great).
-
 ---------------
 Code of conduct
 ---------------

docs/conf.py

@@ -37,6 +37,7 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.doctest',
+    'sphinx.ext.extlinks',
     'sphinx.ext.viewcode',
     'sphinx.ext.intersphinx',
 ]
@@ -79,6 +80,16 @@
 random.seed(0)
 '''
 
+# This config value must be a dictionary of external sites, mapping unique
+# short alias names to a base URL and a prefix.
+# See http://sphinx-doc.org/ext/extlinks.html
+extlinks = {
+    'commit': ('https://github.com/HypothesisWorks/hypothesis-python/commit/%s', 'commit '),
+    'gh-file': ('https://github.com/HypothesisWorks/hypothesis-python/blob/master/%s', ''),
+    'gh-link': ('https://github.com/HypothesisWorks/hypothesis-python/%s', ''),
+    'issue': ('https://github.com/HypothesisWorks/hypothesis-python/issues/%s', 'issue #'),
+    'pull': ('https://github.com/HypothesisWorks/hypothesis-python/pulls/%s', 'pull request #'),
+}
 
 # -- Options for HTML output ----------------------------------------------
 

docs/data.rst

@@ -66,15 +66,15 @@ types.
     >>> from hypothesis.types import Stream
     >>> x = Stream(iter(integers().example, None))
     >>> # Equivalent to `streaming(integers()).example()`, which is not supported
-    >>> x
+    >>> x  # doctest: -ELLIPSIS
     Stream(...)
     >>> x[2]
     131
-    >>> x
+    >>> x  # doctest: -ELLIPSIS
     Stream(-225, 50, 131, ...)
     >>> x[10]
     127
-    >>> x
+    >>> x  # doctest: -ELLIPSIS
     Stream(-225, 50, 131, 30781241791694610923869406150329382725, 89, 62248, 107, 35771, -113, 79, 127, ...)
 
 Think of a Stream as an infinite list where we've only evaluated as much as
@@ -102,13 +102,13 @@ bound then iter on those streams *will* terminate:
     >>> list(x[:5])
     [-225, 50, 131, 30781241791694610923869406150329382725, 89]
     >>> y = x[1::2]
-    >>> y
+    >>> y  # doctest: -ELLIPSIS
     Stream(...)
     >>> y[0]
     50
     >>> y[1]
     30781241791694610923869406150329382725
-    >>> y
+    >>> y  # doctest: -ELLIPSIS
     Stream(50, 30781241791694610923869406150329382725, ...)
 
 You can also apply a function to transform a stream:
@@ -121,9 +121,9 @@ You can also apply a function to transform a stream:
     -344
     >>> t[0]
     -172
-    >>> tm
+    >>> tm  # doctest: -ELLIPSIS
     Stream(-344, ...)
-    >>> t
+    >>> t  # doctest: -ELLIPSIS
     Stream(-172, ...)
 
 map creates a new stream where each element of the stream is the function

docs/development.rst

@@ -2,7 +2,7 @@
 Ongoing Hypothesis Development
 ==============================
 
-Hypothesis releases and development are managed by me, `David R. MacIver <http://www.drmaciver.com>`_.
+Hypothesis development is managed by me, `David R. MacIver <http://www.drmaciver.com>`_.
 I am the primary author of Hypothesis.
 
 *However*, I no longer do unpaid feature development on Hypothesis. My roles as leader of the project are:
@@ -14,17 +14,40 @@ I am the primary author of Hypothesis.
 5. Planning the general roadmap of the project
 6. Doing sponsored development on tasks that are too large or in depth for other people to take on
 
-So all new features must either be sponsored or implemented by someone else. That being said, I take a fairly active
-role in shepherding pull requests and helping people write a new feature (see `the
-contributing guidelines <https://github.com/HypothesisWorks/hypothesis-python/blob/master/CONTRIBUTING.rst>`_ for
-details and `this pull request
-<https://github.com/HypothesisWorks/hypothesis-python/pull/154>`_ for an example of how the process goes). This isn't
-"patches welcome", it's "I will help you write a patch".
+So all new features must either be sponsored or implemented by someone else.
+That being said, the maintenance team takes an active role in shepherding pull requests and
+helping people write a new feature (see :gh-file:`CONTRIBUTING.rst` for
+details and :pull:`154` for an example of how the process goes). This isn't
+"patches welcome", it's "we will help you write a patch".
 
-All enhancement tickets on GitHub are tagged with either `help-wanted <https://github.com/HypothesisWorks/hypothesis-python/labels/help-wanted>`_
-if I think they're viable for someone else to pick up or `for-a-modest-fee <https://github.com/HypothesisWorks/hypothesis-python/labels/for-a-modest-fee>`_ if
-I think they are not and that if you want them you should probably talk to me about paid development.
 
-You are of course entirely welcome to ask for paid development on something that is marked help-wanted,
-or indeed to try to tackle something marked for-a-modest-fee yourself if you're feeling ambitious. These labels
-are very much intended as guidelines rather than rules.
+.. _release-policy:
+
+Release Policy
+==============
+
+Hypothesis releases follow `semantic versioning <http://semver.org/>`_.
+
+We maintain backwards-compatibility wherever possible, and use deprecation
+warnings to mark features that have been superseded by a newer alternative.
+If you want to detect this, the :py:meth:`strict setting <hypothesis.settings.strict>`
+upgrades all Hypothesis warnings to errors.
+
+We use continuous deployment to ensure that you can always use our newest and
+shiniest features - every change to the source tree is automatically built and
+published on PyPI as soon as it's merged onto master, after code review and
+passing our extensive test suite.
+
+
+Project Roadmap
+===============
+
+Hypothesis does not have a long-term release plan.  However some visibility
+into our plans for future :doc:`compatibility <supported>` may be useful:
+
+- We value compatibility, and maintain it as far as practical.  This generally
+  excludes things which are end-of-life upstream, or have an unstable API.
+- We would like to drop Python 2 support when it it reaches end of life in
+  2020.  Ongoing support is likely to depend on commercial funding.
+- We intend to support PyPy3 as soon as it supports a recent enough version of
+  Python 3.  See :issue:`602`.

docs/endorsements.rst

@@ -1,16 +1,16 @@
-========================
-Who is using Hypothesis?
-========================
+============
+Testimonials
+============
 
 This is a page for listing people who are using Hypothesis and how excited they
 are about that. If that's you and your name is not on the list, `this file is in
 Git <https://github.com/HypothesisWorks/hypothesis-python/blob/master/docs/endorsements.rst>`_
 and I'd love it if you sent me a pull request to fix that.
 
 
---------------------------------------------------------------------------------------
-Kristian Glass - Director of Technology at `LaterPay GmbH <http://www.laterpay.net/>`_
---------------------------------------------------------------------------------------
+---------------------------------------------------------------------------------------
+Kristian Glass - Director of Technology at `LaterPay GmbH <https://www.laterpay.net/>`_
+---------------------------------------------------------------------------------------
 
 Hypothesis has been brilliant for expanding the coverage of our test cases,
 and also for making them much easier to read and understand,
@@ -98,7 +98,7 @@ Thank you, David, for the great testing tool.
 Hypothesis is the single most powerful tool in my toolbox for working with
 algorithmic code, or any software that produces predictable output from a wide
 range of sources. When using it with
-`Priority <http://python-hyper.org/priority/>`_, Hypothesis consistently found
+`Priority <https://python-hyper.org/priority/en/latest/>`_, Hypothesis consistently found
 errors in my assumptions and extremely subtle bugs that would have taken months
 of real-world use to locate. In some cases, Hypothesis found subtle deviations
 from the correct output of the algorithm that may never have been noticed at

docs/examples.rst

@@ -480,5 +480,5 @@ then use the result and go on to do other things are definitely also possible.
     if __name__ == '__main__':
         unittest.main()
 
-.. _py.test: http://pytest.org/
-.. _nose: https://nose.readthedocs.io/
+.. _py.test: https://docs.pytest.org/en/latest/
+.. _nose: https://nose.readthedocs.io/en/latest/

docs/packaging.rst

@@ -21,8 +21,8 @@ some information you might find useful.
 Release tarballs
 ----------------
 
-These are available from `the GitHub releases page <https://github.com/HypothesisWorks/hypothesis-python/releases>`_. The
-tarballs on pypi are intended for installation from a Python tool such as pip or easy_install and should not
+These are available from :gh-link:`the GitHub releases page <releases>`. The
+tarballs on pypi are intended for installation from a Python tool such as pip and should not
 be considered complete releases. Requests to include additional files in them will not be granted. Their absence
 is not a bug.
 
@@ -53,9 +53,9 @@ Other Python libraries
 Hypothesis has *optional* dependencies on the following libraries:
 
 * pytz (almost any version should work)
-* fake-factory (0.5.2 or 0.5.3)
-* Django, 1.7 through 1.9 (This requires fake-factory to be installed)
-* numpy, 1.10.x (earlier versions will probably work fine)
+* faker, version 0.7
+* Django, all supported versions
+* numpy, 1.10 or later (earlier versions will probably work fine)
 * py.test (2.7.0 or greater). This is a mandatory dependency for testing Hypothesis itself but optional for users.
 
 The way this works when installing Hypothesis normally is that these features become available if the relevant
@@ -88,7 +88,7 @@ An example invocation for running the coverage subset of these tests:
 
 .. code-block:: bash
 
-  python setup.py install
+  pip install -e .
   pip install pytest # you will probably want to use your own packaging here
   python -m pytest tests/cover
 

docs/quickstart.rst

@@ -10,7 +10,7 @@ An example
 ----------
 
 Suppose we've written a `run length encoding
-<http://en.wikipedia.org/wiki/Run-length_encoding>`_ system and we want to test
+<https://en.wikipedia.org/wiki/Run-length_encoding>`_ system and we want to test
 it out.
 
 We have the following code which I took straight from the
@@ -177,18 +177,12 @@ Hypothesis is `available on pypi as "hypothesis"
 
   pip install hypothesis
 
-or
-
-.. code:: bash
-
-  easy_install hypothesis
-
 If you want to install directly from the source code (e.g. because you want to
 make changes and install the changed version) you can do this with:
 
 .. code:: bash
 
-  python setup.py install
+  pip install -e .
 
 You should probably run the tests first to make sure nothing is broken. You can
 do this with:

docs/support.rst

@@ -7,10 +7,13 @@ friendly place where I or others will be more than happy to help you out. You're
 ask questions on Stack Overflow. If you do, please tag them with 'python-hypothesis' so someone
 sees them.
 
-For bugs and enhancements, please file an issue on the `GitHub issue tracker <https://github.com/HypothesisWorks/hypothesis-python/issues>`_.
+For bugs and enhancements, please file an issue on the :issue:`GitHub issue tracker <>`.
 Note that as per the :doc:`development policy <development>`, enhancements will probably not get
 implemented unless you're willing to pay for development or implement them yourself (with assistance from me). Bugs
 will tend to get fixed reasonably promptly, though it is of course on a best effort basis.
 
+To see the versions of Python, optional dependencies, test runners, and operating systems Hypothesis
+supports (meaning incompatibility is treated as a bug), see :doc:`supported`.
+
 If you need to ask questions privately or want more of a guarantee of bugs being fixed promptly, please contact me on
 [email protected] to talk about availability of support contracts.

docs/supported.rst

@@ -11,19 +11,13 @@ for the details.
 Python versions
 ---------------
 
-Hypothesis is supported and tested on python 2.7
-and python 3.3+. Python 3.0 through 3.2 are unsupported and definitely don't work.
-It's not infeasible to make them work but would need a very good reason.
+Hypothesis is supported and tested on CPython 2.7 and CPython 3.4+.
 
-Python 2.6 and 3.3 are supported on a "best effort" basis. They probably work,
-and bugs that affect them *might* get fixed.
-
-Hypothesis also supports PyPy (PyPy3 does not work because it only runs 3.2 compatible
-code, but if and when there's a 3.3 compatible version it will be supported), and
-should support 32-bit and narrow builds, though this is currently only tested on Windows.
-
-Hypothesis does not currently work on Jython (it requires sqlite), though could feasibly
-be made to do so. IronPython might work but hasn't been tested.
+Hypothesis also supports PyPy2, and will support PyPy3 when there is a stable
+release supporting Python 3.4+.  Hypothesis does not currently work on Jython
+(it requires sqlite), though could feasibly be made to do so. IronPython might
+work but hasn't been tested.  32-bit and narrow builds should work, though
+this is currently only tested on Windows.
 
 In general Hypothesis does not officially support anything except the latest
 patch release of any version of Python it supports. Earlier releases should work
@@ -93,3 +87,11 @@ with `Travis <https://travis-ci.org/HypothesisWorks/hypothesis-python>`_ and
 `Appveyor <https://ci.appveyor.com/project/DRMacIver/hypothesis-python/>`_
 and goes green before a release happens, so when I say they're supported I
 really mean it.
+
+-------------------
+Hypothesis versions
+-------------------
+
+Backwards compatibility is better than backporting fixes, so we use
+:ref:`semantic versioning <release-policy>` and only support the most recent
+version of Hypothesis.  See :doc:`support` for more information.

docs/usage.rst

@@ -18,7 +18,7 @@ then it should be available on pypi.
 * `fastnumbers <https://github.com/SethMMorton/fastnumbers>`_
 * `flocker <https://github.com/ClusterHQ/flocker>`_
 * `flownetpy <https://github.com/debsankha/flownetpy>`_
-* `funsize <https://github.com/mozilla/funsize>`_
+* `funsize <https://github.com/mozilla-releng/funsize>`_
 * `fusion-index <https://github.com/fusionapp/fusion-index>`_
 * `hyper-h2 <https://github.com/python-hyper/hyper-h2>`_
 * `into-dbus-python <https://github.com/stratis-storage/into-dbus-python>`_
@@ -33,13 +33,13 @@ then it should be available on pypi.
 * `PyPy <http://pypy.org>`_
 * `pyrsistent <https://github.com/tobgu/pyrsistent>`_
 * `pyudev <https://github.com/pyudev/pyudev>`_
-* `qutebrowser <https://github.com/The-Compiler/qutebrowser>`_
+* `qutebrowser <https://github.com/qutebrowser/qutebrowser>`_
 * `RubyMarshal <https://github.com/d9pouces/RubyMarshal>`_
 * `Segpy <https://github.com/sixty-north/segpy>`_
 * `simoa <https://github.com/andsor/pysimoa>`_
 * `srt <https://github.com/cdown/srt>`_
 * `tchannel <https://github.com/uber/tchannel-python>`_
-* `vdirsyncer <https://github.com/untitaker/vdirsyncer>`_
+* `vdirsyncer <https://github.com/pimutils/vdirsyncer>`_
 * `wcag-contrast-ratio <https://github.com/gsnedders/wcag-contrast-ratio>`_
 * `yacluster <https://github.com/KrzysiekJ/yacluster>`_
 * `yturl <https://github.com/cdown/yturl>`_

setup.py

@@ -74,6 +74,7 @@ def local_file(name):
     zip_safe=False,
     extras_require=extras,
     install_requires=install_requires,
+    python_requires='>=2.7, !=3.0.*, !=3.1.*, !=3.2.*',
     classifiers=[
         'Development Status :: 5 - Production/Stable',
         'Intended Audience :: Developers',