Document reject() function.

[jenstroeger]

I noticed that e.g. the Getting started with Hypothesis article demonstrates the use of hypothesis.reject(). However, I wasn’t able to find more documentation on that function, likely because there is none:

hypothesis/hypothesis-python/src/hypothesis/control.py

Lines 23 to 24 in 226028d

	def reject() -> NoReturn:
	raise UnsatisfiedAssumption()

Would it make sense/be possible to elaborate?

Thank you!

[rsokl]

I think a reasonable description would be:

"""
Discards an example by raising `UnsatisfiableAssumption`.

Hypothesis won’t count it towards the ‘budget’ of examples it is allowed to run.
"""

I'll add documentation to this function. Thanks for bringing this to our attention! 🙏

[jenstroeger]

Great, thank you @rsokl!

[Zac-HD]

The reason you won't see it anywhere in the docs is that I'd prefer to point people to assume(False) - since this is exactly equivalent and I'd rather have only one (obvious) way to do it.

See #2943 for steps to get this fixed in the article though 😓

[jenstroeger]

That makes sense, thanks @Zac-HD

Perhaps for the sake of making your intent clear it might make sense then to implement reject() by calling assume():

def reject() -> bool:
    return assume(False)

That would also raise the UnsatisfiedAssumption at the cost of an extra function call… 🤔 Anyway. All good 👍🏼