def example(self):
# type: () -> Ex
"""Provide an example of the sort of value that this strategy
generates. This is biased to be slightly simpler than is typical for
values from this strategy, for clarity purposes.
This method shouldn't be taken too seriously. It's here for interactive
exploration of the API, not for any sort of real testing.
This method is part of the public API.
"""
if getattr(sys, "ps1", None) is None: # pragma: no branch
# The other branch *is* covered in cover/test_examples.py; but as that
# uses `pexpect` for an interactive session `coverage` doesn't see it.
warnings.warn(
"The `.example()` method is good for exploring strategies, but should "
"only be used interactively. We recommend using `@given` for tests - "
"it performs better, saves and replays failures to avoid flakiness, "
"and reports minimal examples. (strategy: %r)" % (self, ),
NonInteractiveExampleWarning,
)
context = _current_build_context.value
if context is not None:
if context.data is not None and context.data.depth > 0:
raise HypothesisException(
"Using example() inside a strategy definition is a bad "
"idea. Instead consider using hypothesis.strategies.builds() "
"or @hypothesis.strategies.composite to define your strategy."
" See https://hypothesis.readthedocs.io/en/latest/data.html"
"#hypothesis.strategies.builds or "
"https://hypothesis.readthedocs.io/en/latest/data.html"
"#composite-strategies for more details.")
else:
raise HypothesisException(
"Using example() inside a test function is a bad "
"idea. Instead consider using hypothesis.strategies.data() "
"to draw more examples during testing. See "
"https://hypothesis.readthedocs.io/en/latest/data.html"
"#drawing-interactively-in-tests for more details.")
from hypothesis.core import given
# Note: this function has a weird name because it might appear in
# tracebacks, and we want users to know that they can ignore it.
@given(self)
@settings(
database=None,
max_examples=10,
deadline=None,
verbosity=Verbosity.quiet,
phases=(Phase.generate, ),
suppress_health_check=HealthCheck.all(),
)
def example_generating_inner_function(ex):
examples.append(ex)
examples = [] # type: List[Ex]
example_generating_inner_function()
return random_choice(examples)
def example(self, random=not_set):
# type: (UniqueIdentifier) -> Ex
"""Provide an example of the sort of value that this strategy
generates. This is biased to be slightly simpler than is typical for
values from this strategy, for clarity purposes.
This method shouldn't be taken too seriously. It's here for interactive
exploration of the API, not for any sort of real testing.
This method is part of the public API.
"""
if random is not not_set:
note_deprecation("The random argument does nothing", since="2019-07-08")
context = _current_build_context.value
if context is not None:
if context.data is not None and context.data.depth > 0:
raise HypothesisException(
"Using example() inside a strategy definition is a bad "
"idea. Instead consider using hypothesis.strategies.builds() "
"or @hypothesis.strategies.composite to define your strategy."
" See https://hypothesis.readthedocs.io/en/latest/data.html"
"#hypothesis.strategies.builds or "
"https://hypothesis.readthedocs.io/en/latest/data.html"
"#composite-strategies for more details."
)
else:
raise HypothesisException(
"Using example() inside a test function is a bad "
"idea. Instead consider using hypothesis.strategies.data() "
"to draw more examples during testing. See "
"https://hypothesis.readthedocs.io/en/latest/data.html"
"#drawing-interactively-in-tests for more details."
)
from hypothesis.core import given
# Note: this function has a weird name because it might appear in
# tracebacks, and we want users to know that they can ignore it.
@given(self)
@settings(
database=None,
max_examples=10,
deadline=None,
verbosity=Verbosity.quiet,
phases=(Phase.generate,),
suppress_health_check=HealthCheck.all(),
)
def example_generating_inner_function(ex):
examples.append(ex)
examples = [] # type: List[Ex]
example_generating_inner_function()
return random_choice(examples)
def _db_for_path(path=None):
if path is not_set:
if os.getenv("HYPOTHESIS_DATABASE_FILE") is not None: # pragma: no cover
raise HypothesisException(
"The $HYPOTHESIS_DATABASE_FILE environment variable no longer has any "
"effect. Configure your database location via a settings profile instead.\n"
"https://hypothesis.readthedocs.io/en/latest/settings.html#settings-profiles"
)
# Note: storage_directory attempts to create the dir in question, so
# if os.access fails there *must* be a fatal permissions issue.
path = storage_directory("examples")
if os.access(path, os.R_OK | os.W_OK | os.X_OK):
return _db_for_path(path)
else: # pragma: no cover
warnings.warn(
HypothesisWarning(
"The database setting is not configured, and the default "
"location is unusable - falling back to an in-memory "
"database for this session. path=%r" % (path,)
)
)
return InMemoryExampleDatabase()
if path in (None, ":memory:"):
return InMemoryExampleDatabase()
return DirectoryBasedExampleDatabase(str(path))
def _db_for_path(path=None):
if path is not_set:
if os.getenv(
"HYPOTHESIS_DATABASE_FILE") is not None: # pragma: no cover
raise HypothesisException(
"The $HYPOTHESIS_DATABASE_FILE environment variable no longer has any "
"effect. Configure your database location via a settings profile instead.\n"
"https://hypothesis.readthedocs.io/en/latest/settings.html#settings-profiles"
)
path = storage_directory("examples")
if not _usable_dir(path): # pragma: no cover
warnings.warn(
HypothesisWarning(
"The database setting is not configured, and the default "
"location is unusable - falling back to an in-memory "
f"database for this session. path={path!r}"))
return InMemoryExampleDatabase()
if path in (None, ":memory:"):
return InMemoryExampleDatabase()
return DirectoryBasedExampleDatabase(str(path))
def example(self, random=None):
# type: (Random) -> Ex
"""Provide an example of the sort of value that this strategy
generates. This is biased to be slightly simpler than is typical for
values from this strategy, for clarity purposes.
This method shouldn't be taken too seriously. It's here for interactive
exploration of the API, not for any sort of real testing.
This method is part of the public API.
"""
context = _current_build_context.value
if context is not None:
if context.data is not None and context.data.depth > 0:
raise HypothesisException(
"Using example() inside a strategy definition is a bad "
"idea. Instead consider using hypothesis.strategies.builds() "
"or @hypothesis.strategies.composite to define your strategy."
" See https://hypothesis.readthedocs.io/en/latest/data.html"
"#hypothesis.strategies.builds or "
"https://hypothesis.readthedocs.io/en/latest/data.html"
"#composite-strategies for more details."
)
else:
raise HypothesisException(
"Using example() inside a test function is a bad "
"idea. Instead consider using hypothesis.strategies.data() "
"to draw more examples during testing. See "
"https://hypothesis.readthedocs.io/en/latest/data.html"
"#drawing-interactively-in-tests for more details."
)
from hypothesis import find, settings, Verbosity
# Conjecture will always try the zero example first. This would result
# in us producing the same example each time, which is boring, so we
# deliberately skip the first example it feeds us.
first = [] # type: list
def condition(x):
if first:
return True
else:
first.append(x)
return False
try:
return find(
self,
condition,
random=random,
settings=settings(
database=None,
verbosity=Verbosity.quiet,
phases=tuple(set(Phase) - {Phase.shrink}),
),
)
except (NoSuchExample, Unsatisfiable):
# This can happen when a strategy has only one example. e.g.
# st.just(x). In that case we wanted the first example after all.
if first:
return first[0]
raise NoExamples(u"Could not find any valid examples in 100 tries")
