diff --git a/hypothesis/RELEASE.rst b/hypothesis/RELEASE.rst new file mode 100644 index 0000000000..8aa92bda41 --- /dev/null +++ b/hypothesis/RELEASE.rst @@ -0,0 +1,7 @@ +RELEASE_TYPE: patch + +Document the "gotcha" that :func:`~hypothesis.strategies.nothing` is not +suitable for use as a placeholder strategy in "explicit +:class:`~hypothesis.example` only" setups. See :issue:`4774`. + +Contributed by Marco Ricci. diff --git a/hypothesis/src/hypothesis/strategies/_internal/misc.py b/hypothesis/src/hypothesis/strategies/_internal/misc.py index cbcfa32445..cb1d55d67b 100644 --- a/hypothesis/src/hypothesis/strategies/_internal/misc.py +++ b/hypothesis/src/hypothesis/strategies/_internal/misc.py @@ -83,6 +83,8 @@ def just(value: T) -> SearchStrategy[T]: def none() -> SearchStrategy[None]: """Return a strategy which only generates None. + Useful as a placeholder strategy. + Examples from this strategy do not shrink (because there is only one). """ @@ -125,6 +127,14 @@ def nothing() -> SearchStrategy["Never"]: """This strategy never successfully draws a value and will always reject on an attempt to draw. + ``nothing()`` is *not* suitable as a placeholder strategy in |@given|, + even when used together with |@example| and with only |Phase.explicit| + active, because it is too easy for a change in settings or settings profile + to cause the test to suddenly fail mysteriously. Prefer |st.none| as a + placeholder strategy for this use case. See `issue #4774 + `__ for more + details. + Examples from this strategy do not shrink (because there are none). """ return NOTHING