Repository: HypothesisWorks/hypothesis

Issue:
Suggest that those using `just(foo())` may want `builds(foo)`
Because I spent a remarkable amount of time not realising I wanted
`builsd` - https://stackoverflow.com/a/46297774/928098


Discussion:
I'm not happy with the language I used here but hopefully you get the idea

(Also I couldn't run tests locally, sorry, the snakepit stuff keeps failing and I haven't yet worked out why)
This is a good point, thanks!

> I'm not happy with the language I used here but hopefully you get the idea

Yeah, but the versions of Hypothesis for things that aren't Python aren't ready yet.

(I kid, I kid)

If you'll permit a bit of bikeshedding over this, perhaps the thing to do is to try and merge this sentence into a paragraph with the preceding line? e.g. rather than the "Beware of mutable values" language say something like "If you need a fresh value each time, consider something like `builds(lambda: ...)`?

(I'm not super happy with that language either, but maybe it points in the right direction?)

Also this involves a source code change so needs a RELEASE.rst. See https://github.com/HypothesisWorks/hypothesis-python/blob/master/CONTRIBUTING.rst#the-release-file for details.

> (Also I couldn't run tests locally, sorry, the snakepit stuff keeps failing and I haven't yet worked out why)

No worries. I'd be interested in debugging with you some time, but using the CI for testing the bulk of your changes is totally acceptable and we all do it. :-)
> If you'll permit a bit of bikeshedding over this

Please! Good idea, thanks, will give it a try

> Also this involves a source code change so needs a RELEASE.rst

Whoops, cheers!
> perhaps the thing to do is to try and merge this sentence into a paragraph with the preceding line? e.g. rather than the "Beware of mutable values" language say something like "If you need a fresh value each time, consider something like builds(lambda: ...)?

I think that's an excellent point (and will amend accordingly) but I still feel like I want something a bit more obvious, which might work as a nice lead-in to the above - let's see how this attempt looks...
I think this is still a little confusing. If `value` is a literal defined inside the lambda, you will get a fresh version of `value` each time. If `value` is defined elsewhere, then `lambda: value` will give you the same version each time. Eg

    lambda: {'A': 1, 'B': 2}
works, but

    my_dict = {'A': 1, 'B': 2}
    lambda: my_dict
won't work. Knowing this is only knowledge about Python, not about Hypothesis. But the example `lambda: value` looks very like the second example, so it seems like we are suggesting something that it is easy to become confused about.

Resolving patch:
diff --git a/src/hypothesis/strategies.py b/src/hypothesis/strategies.py
--- a/src/hypothesis/strategies.py
+++ b/src/hypothesis/strategies.py
@@ -172,9 +172,13 @@ def nothing():
 
 
 def just(value):
-    """Return a strategy which only generates value.
+    """Return a strategy which only generates ``value``.
 
-    Note: value is not copied. Be wary of using mutable values.
+    Note: ``value`` is not copied. Be wary of using mutable values.
+
+    If ``value`` is the result of a callable, you can use
+    :func:`builds(callable) <hypothesis.strategies.builds>` instead
+    of ``just(callable())`` to get a fresh value each time.
 
     """
     from hypothesis.searchstrategy.misc import JustStrategy


Test patch: