Merge branch 'master' into constants-speedup

Author: tybug

hypothesis-python/docs/changelog.rst

@@ -18,6 +18,22 @@ Hypothesis 6.x
 
     .. include:: ../RELEASE.rst
 
+.. _v6.131.5:
+
+--------------------
+6.131.5 - 2025-04-18
+--------------------
+
+Fix a rare case where database entries were kept after they were no longer needed when using |Phase.target|.
+
+.. _v6.131.4:
+
+--------------------
+6.131.4 - 2025-04-18
+--------------------
+
+Internal refactoring of the |@settings| object, with no user-visible change.
+
 .. _v6.131.3:
 
 --------------------
@@ -336,7 +352,7 @@ Fix a type-hinting regression from :ref:`version 6.125.1 <v6.125.1>`, where we w
 6.127.6 - 2025-03-04
 --------------------
 
-This patch tweaks the performance of the :ref:`target phase <phases>`, avoiding aborting some test cases when it would be better to finish generating them.
+This patch tweaks the performance of |Phase.target|, avoiding aborting some test cases when it would be better to finish generating them.
 
 .. _v6.127.5:
 
@@ -559,7 +575,7 @@ Improves one of our shrinking passes for integers which require a constant relat
 6.123.14 - 2025-01-11
 ---------------------
 
-Avoid realizing symbolic values from :ref:`alternative-backends` when :obj:`~hypothesis.settings.verbosity` is ``verbose`` or higher.
+Avoid realizing symbolic values from :ref:`alternative-backends` when |Verbosity| is ``verbose`` or higher.
 
 .. _v6.123.13:
 
@@ -800,7 +816,7 @@ This patch fixes a bug since :ref:`v6.99.13` where only interactively-generated
 6.119.3 - 2024-11-17
 --------------------
 
-Hypothesis collects coverage information during the ``shrink`` and ``explain`` :ref:`phases <phases>` in order to show a more informative error message. On 3.12+, this uses :mod:`sys.monitoring`. This patch improves the performance of coverage collection on 3.12+ by disabling events we don't need.
+Hypothesis collects coverage information during the |Phase.shrink| and |Phase.explain| phases in order to show a more informative error message. On 3.12+, this uses :mod:`sys.monitoring`. This patch improves the performance of coverage collection on 3.12+ by disabling events we don't need.
 
 .. _v6.119.2:
 
@@ -893,7 +909,7 @@ This patch adds more type hints to internal Hypothesis code.
 6.118.2 - 2024-11-09
 --------------------
 
-This patch migrates the :obj:`~hypothesis.Phase.explain` :ref:`phase <phases>` to our IR layer (:issue:`3921`). This should improve both its speed and precision.
+This patch migrates the |Phase.explain| phase to our IR layer (:issue:`3921`). This should improve both its speed and precision.
 
 .. _v6.118.1:
 
@@ -1957,7 +1973,7 @@ as well continue running the test!
 Because we now finish running a few more examples for affected tests, this
 might be a slight slowdown - but correspondingly more likely to find a bug.
 
-We've also applied similar tricks to the :ref:`target phase <phases>`, where
+We've also applied similar tricks to the |Phase.target| phase, where
 they are a pure performance improvement for affected tests.
 
 .. _v6.97.1:
@@ -2425,7 +2441,7 @@ one provided by an xfailed example.
 6.86.0 - 2023-09-17
 -------------------
 
-This release enables the :obj:`~hypothesis.Phase.explain` :ref:`phase <phases>`
+This release enables the |Phase.explain| phase
 by default.  We hope it helps you to understand *why* your failing tests have
 failed!
 
@@ -2925,9 +2941,9 @@ with versions before 1.20, which were broken by a mistake in Hypothesis 6.72.4
 6.73.0 - 2023-04-25
 -------------------
 
-This release upgrades the :ref:`explain phase <phases>` (:issue:`3411`).
+This release upgrades the |Phase.explain| phase (:issue:`3411`).
 
-* Following the first failure, Hypothesis will (:ref:`usually <phases>`) track which
+* Following the first failure, Hypothesis will (usually, depending on the enabled |Phase|) track which
   lines of code were executed by passing and failing examples, and report where they
   diverged - with some heuristics to drop unhelpful reports.  This is an existing
   feature, now upgraded and newly enabled by default.
@@ -3461,7 +3477,7 @@ This patch updates our autoformatting tools, improving our code style without an
 -------------------
 
 This patch fixes some type annotations for Python 3.9 and earlier (:issue:`3397`),
-and teaches :ref:`explain mode <phases>` about certain locations it should not
+and teaches the |Phase.explain| phase about certain locations it should not
 bother reporting (:issue:`3439`).
 
 .. _v6.54.3:
@@ -4980,7 +4996,7 @@ There is no user-visible change.
 6.14.0 - 2021-06-09
 -------------------
 
-The :ref:`explain phase <phases>` now requires shrinking to be enabled,
+The |Phase.explain| phase now requires shrinking to be enabled,
 and will be automatically skipped for deadline-exceeded errors.
 
 .. _v6.13.14:
@@ -5413,7 +5429,7 @@ meant to be allowed (:issue:`2681`).
 6.5.0 - 2021-03-07
 ------------------
 
-This release adds :ref:`the explain phase <phases>`, in which Hypothesis
+This release adds |Phase.explain|, in which Hypothesis
 attempts to explain *why* your test failed by pointing to suspicious lines
 of code (i.e. those which were always, and only, run on failing inputs).
 We plan to include "generalising" failing examples in this phase in a
@@ -11849,7 +11865,7 @@ documentation, by explaining that example shrinking is tracked at the level
 of the underlying bytestream rather than the output value.
 
 The output from ``find()`` in verbose mode has also been
-adjusted - see :ref:`the example session <verbose-output>` - to avoid
+adjusted - see the example session for |Verbosity| - to avoid
 duplicating lines when the example repr is constant, even if the underlying
 representation has been shrunken.
 
@@ -13601,7 +13617,7 @@ Thanks to Alex Willmer for these.
 3.17.0 - 2017-08-07
 -------------------
 
-This release documents :ref:`the previously undocumented phases feature <phases>`,
+This release documents the previously undocumented phases feature in |Phase|,
 making it part of the public API. It also updates how the example
 database is used. Principally:
 

hypothesis-python/docs/conf.py

@@ -194,13 +194,15 @@ def setup(app):
 <hypothesis.HealthCheck.differing_executors>`
 .. |HealthCheck| replace:: :obj:`~hypothesis.HealthCheck`
 
+.. |Phase| replace:: :obj:`Phase <hypothesis.Phase>`
 .. |Phase.explicit| replace:: :obj:`Phase.explicit <hypothesis.Phase.explicit>`
 .. |Phase.reuse| replace:: :obj:`Phase.reuse <hypothesis.Phase.reuse>`
 .. |Phase.generate| replace:: :obj:`Phase.generate <hypothesis.Phase.generate>`
 .. |Phase.target| replace:: :obj:`Phase.target <hypothesis.Phase.target>`
 .. |Phase.shrink| replace:: :obj:`Phase.shrink <hypothesis.Phase.shrink>`
 .. |Phase.explain| replace:: :obj:`Phase.explain <hypothesis.Phase.explain>`
 
+.. |Verbosity| replace:: :obj:`~hypothesis.Verbosity`
 .. |Verbosity.verbose| replace:: :obj:`Verbosity.verbose <hypothesis.Verbosity.verbose>`
 .. |Verbosity.debug| replace:: :obj:`Verbosity.debug <hypothesis.Verbosity.debug>`
 .. |Verbosity.normal| replace:: :obj:`Verbosity.normal <hypothesis.Verbosity.normal>`
@@ -248,6 +250,8 @@ def setup(app):
 .. |strategy.map| replace:: :func:`.map() <hypothesis.strategies.SearchStrategy.map>`
 .. |strategy.map()| replace:: :func:`.map() <hypothesis.strategies.SearchStrategy.map>`
 
+.. |@rule| replace:: :func:`@rule <hypothesis.stateful.rule>`
+
 .. |@reproduce_failure| replace:: :func:`@reproduce_failure <hypothesis.reproduce_failure>`
 
 .. |ExampleDatabase| replace:: :class:`~hypothesis.database.ExampleDatabase`

hypothesis-python/docs/reference/api.rst

@@ -256,116 +256,11 @@ Settings
     :members:
     :exclude-members: register_profile, get_profile, load_profile
 
-.. _phases:
-
-Controlling what runs
-~~~~~~~~~~~~~~~~~~~~~
-
-Hypothesis divides tests into logically distinct phases.
-
-- |Phase.explicit|: Running explicit examples from |@example|.
-- |Phase.reuse|: Running examples from the database which previously failed.
-- |Phase.generate|: Generating new random examples.
-- |Phase.target|: Mutating examples for :ref:`targeted property-based testing <targeted>`.
-
-  - Requires |Phase.generate|.
-
-- |Phase.shrink|: Shrinking failing examples.
-- |Phase.explain|: Attempting to explain why a failure occurred.
-
-  - Requires |Phase.shrink|.
-
-.. note::
-
-   The explain phase has two parts, each of which is best-effort - if Hypothesis can't
-   find a useful explanation, we'll just print the minimal failing example.
-
-   Following the first failure, Hypothesis will (:ref:`usually <phases>`) track which
-   lines of code are always run on failing but never on passing inputs. On 3.12+, this uses
-   :mod:`sys.monitoring`, while 3.11 and earlier uses :func:`python:sys.settrace`. For python 3.11
-   and earlier, we therefore automatically disable the explain phase on PyPy, or if you are using
-   :pypi:`coverage` or a debugger. If there are no clearly suspicious lines of code,
-   :pep:`we refuse the temptation to guess <20>`.
-
-   After shrinking to a minimal failing example, Hypothesis will try to find parts of
-   the example -- e.g. separate args to :func:`@given() <hypothesis.given>` -- which
-   can vary freely without changing the result of that minimal failing example.
-   If the automated experiments run without finding a passing variation, we leave a
-   comment in the final report:
-
-   .. code-block:: python
-
-       test_x_divided_by_y(
-           x=0,  # or any other generated value
-           y=0,
-       )
-
-   Just remember that the *lack* of an explanation sometimes just means that Hypothesis
-   couldn't efficiently find one, not that no explanation (or simpler failing example)
-   exists.
-
-
-The phases setting provides you with fine grained control over which of these run,
-with each phase corresponding to a value on the :class:`~hypothesis.Phase` enum:
-
 .. autoclass:: hypothesis.Phase
-   :members:
-
-The phases argument accepts a collection with any subset of these. e.g.
-``settings(phases=[Phase.generate, Phase.shrink])`` will generate new examples
-and shrink them, but will not run explicit examples or reuse previous failures,
-while ``settings(phases=[Phase.explicit])`` will only run the explicit
-examples.
-
-.. _verbose-output:
-
-Seeing intermediate result
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+    :members:
 
 .. autoclass:: hypothesis.Verbosity
-    :members: quiet,normal,verbose,debug
-
-    .. documenting all members runs into https://stackoverflow.com/a/78657325
-    .. and the fix there didn't work for me
-    .. TODO python 3.13: remove this?
-
-To see what's going on while Hypothesis runs your tests, you can turn
-up the verbosity setting.
-
-.. code-block:: pycon
-
-    >>> from hypothesis import find, settings, Verbosity
-    >>> from hypothesis.strategies import lists, integers
-    >>> @given(lists(integers()))
-    ... @settings(verbosity=Verbosity.verbose)
-    ... def f(x):
-    ...     assert not any(x)
-    ... f()
-    Trying example: []
-    Falsifying example: [-1198601713, -67, 116, -29578]
-    Shrunk example to [-1198601713]
-    Shrunk example to [-1198601600]
-    Shrunk example to [-1191228800]
-    Shrunk example to [-8421504]
-    Shrunk example to [-32896]
-    Shrunk example to [-128]
-    Shrunk example to [64]
-    Shrunk example to [32]
-    Shrunk example to [16]
-    Shrunk example to [8]
-    Shrunk example to [4]
-    Shrunk example to [3]
-    Shrunk example to [2]
-    Shrunk example to [1]
-    [1]
-
-The four levels are quiet, normal, verbose and debug. normal is the default,
-while in quiet mode Hypothesis will not print anything out, not even the final
-falsifying example. debug is basically verbose but a bit more so. You probably
-don't want it.
-
-If you are using :pypi:`pytest`, you may also need to
-:doc:`disable output capturing for passing tests <pytest:how-to/capture-stdout-stderr>`.
+    :members:
 
 Building settings objects
 ~~~~~~~~~~~~~~~~~~~~~~~~~

hypothesis-python/docs/reference/integrations.rst

@@ -97,8 +97,8 @@ is to let you answer questions you didn't think of in advance.  In slogan form,
   *Debugging should be a data analysis problem.*
 
 By default, Hypothesis only reports the minimal failing example... but sometimes you might
-want to know something about *all* the examples.  Printing them to the terminal with
-:ref:`verbose output <verbose-output>` might be nice, but isn't always enough.
+want to know something about *all* the examples.  Printing them to the terminal by increasing
+|Verbosity| might be nice, but isn't always enough.
 This feature gives you an analysis-ready dataframe with useful columns and one row
 per test case, with columns from arguments to code coverage to pass/fail status.
 
@@ -171,9 +171,9 @@ Hypothesis includes a tiny plugin to improve integration with :pypi:`pytest`, wh
 
 - ``pytest --hypothesis-show-statistics`` can be used to :ref:`display test and data generation statistics <statistics>`.
 - ``pytest --hypothesis-profile=<profile name>`` can be used to :ref:`load a settings profile <settings_profiles>`.
-- ``pytest --hypothesis-verbosity=<level name>`` can be used to :ref:`override the current verbosity level <verbose-output>`.
+- ``pytest --hypothesis-verbosity=<level name>`` can be used to override the current |Verbosity| setting.
 - ``pytest --hypothesis-seed=<an int>`` can be used to :ref:`reproduce a failure with a particular seed <reproducing-with-seed>`.
-- ``pytest --hypothesis-explain`` can be used to :ref:`temporarily enable the explain phase <phases>`.
+- ``pytest --hypothesis-explain`` can be used to temporarily enable |Phase.explain|.
 
 Finally, all tests that are defined with Hypothesis automatically have ``@pytest.mark.hypothesis`` applied to them.  See :ref:`here for information on working with markers <pytest:mark examples>`.