Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# This file is part of Hypothesis, which may be found at
2# https://github.com/HypothesisWorks/hypothesis/
3#
4# Copyright the Hypothesis Authors.
5# Individual contributors are listed in AUTHORS.rst and the git log.
6#
7# This Source Code Form is subject to the terms of the Mozilla Public License,
8# v. 2.0. If a copy of the MPL was not distributed with this file, You can
9# obtain one at https://mozilla.org/MPL/2.0/.
11import codecs
12import enum
13import math
14import operator
15import random
16import re
17import string
18import sys
19import typing
20import warnings
21from collections.abc import Collection, Hashable, Iterable, Sequence
22from contextvars import ContextVar
23from decimal import Context, Decimal, localcontext
24from fractions import Fraction
25from functools import reduce
26from inspect import Parameter, Signature, isabstract, isclass
27from re import Pattern
28from types import FunctionType, GenericAlias
29from typing import (
30 TYPE_CHECKING,
31 Annotated,
32 Any,
33 AnyStr,
34 Callable,
35 Literal,
36 NoReturn,
37 Optional,
38 Protocol,
39 TypeVar,
40 Union,
41 cast,
42 get_args,
43 get_origin,
44 overload,
45)
46from uuid import UUID
48import attr
50from hypothesis._settings import note_deprecation
51from hypothesis.control import (
52 cleanup,
53 current_build_context,
54 deprecate_random_in_strategy,
55 note,
56 should_note,
57)
58from hypothesis.errors import (
59 HypothesisSideeffectWarning,
60 HypothesisWarning,
61 InvalidArgument,
62 ResolutionFailed,
63 RewindRecursive,
64 SmallSearchSpaceWarning,
65)
66from hypothesis.internal.cathetus import cathetus
67from hypothesis.internal.charmap import (
68 Categories,
69 CategoryName,
70 as_general_categories,
71 categories as all_categories,
72)
73from hypothesis.internal.compat import (
74 Concatenate,
75 EllipsisType,
76 ParamSpec,
77 bit_count,
78 ceil,
79 floor,
80 get_type_hints,
81 is_typed_named_tuple,
82)
83from hypothesis.internal.conjecture.data import ConjectureData
84from hypothesis.internal.conjecture.utils import (
85 calc_label_from_callable,
86 calc_label_from_name,
87 check_sample,
88 combine_labels,
89 identity,
90)
91from hypothesis.internal.entropy import get_seeder_and_restorer
92from hypothesis.internal.floats import float_of
93from hypothesis.internal.reflection import (
94 define_function_signature,
95 get_pretty_function_description,
96 get_signature,
97 is_first_param_referenced_in_function,
98 nicerepr,
99 repr_call,
100 required_args,
101)
102from hypothesis.internal.validation import (
103 check_type,
104 check_valid_integer,
105 check_valid_interval,
106 check_valid_magnitude,
107 check_valid_size,
108 check_valid_sizes,
109 try_convert,
110)
111from hypothesis.strategies._internal import SearchStrategy, check_strategy
112from hypothesis.strategies._internal.collections import (
113 FixedDictStrategy,
114 ListStrategy,
115 TupleStrategy,
116 UniqueListStrategy,
117 UniqueSampledListStrategy,
118 tuples,
119)
120from hypothesis.strategies._internal.deferred import DeferredStrategy
121from hypothesis.strategies._internal.functions import FunctionStrategy
122from hypothesis.strategies._internal.lazy import LazyStrategy, unwrap_strategies
123from hypothesis.strategies._internal.misc import BooleansStrategy, just, none, nothing
124from hypothesis.strategies._internal.numbers import (
125 IntegersStrategy,
126 Real,
127 floats,
128 integers,
129)
130from hypothesis.strategies._internal.recursive import RecursiveStrategy
131from hypothesis.strategies._internal.shared import SharedStrategy
132from hypothesis.strategies._internal.strategies import (
133 Ex,
134 SampledFromStrategy,
135 T,
136 one_of,
137)
138from hypothesis.strategies._internal.strings import (
139 BytesStrategy,
140 OneCharStringStrategy,
141 TextStrategy,
142 _check_is_single_character,
143)
144from hypothesis.strategies._internal.utils import cacheable, defines_strategy
145from hypothesis.utils.conventions import not_set
146from hypothesis.vendor.pretty import RepresentationPrinter
148if TYPE_CHECKING:
149 from typing import TypeAlias
152@cacheable
153@defines_strategy(force_reusable_values=True)
154def booleans() -> SearchStrategy[bool]:
155 """Returns a strategy which generates instances of :class:`python:bool`.
157 Examples from this strategy will shrink towards ``False`` (i.e.
158 shrinking will replace ``True`` with ``False`` where possible).
159 """
160 return BooleansStrategy()
163@overload
164def sampled_from(elements: Sequence[T]) -> SearchStrategy[T]: # pragma: no cover
165 ...
168@overload
169def sampled_from(elements: type[enum.Enum]) -> SearchStrategy[Any]: # pragma: no cover
170 # `SearchStrategy[Enum]` is unreliable due to metaclass issues.
171 ...
174@overload
175def sampled_from(
176 elements: Union[type[enum.Enum], Sequence[Any]],
177) -> SearchStrategy[Any]: # pragma: no cover
178 ...
181@defines_strategy(try_non_lazy=True)
182def sampled_from(
183 elements: Union[type[enum.Enum], Sequence[Any]],
184) -> SearchStrategy[Any]:
185 """Returns a strategy which generates any value present in ``elements``.
187 Note that as with :func:`~hypothesis.strategies.just`, values will not be
188 copied and thus you should be careful of using mutable data.
190 ``sampled_from`` supports ordered collections, as well as
191 :class:`~python:enum.Enum` objects. :class:`~python:enum.Flag` objects
192 may also generate any combination of their members.
194 Examples from this strategy shrink by replacing them with values earlier in
195 the list. So e.g. ``sampled_from([10, 1])`` will shrink by trying to replace
196 1 values with 10, and ``sampled_from([1, 10])`` will shrink by trying to
197 replace 10 values with 1.
199 It is an error to sample from an empty sequence, because returning :func:`nothing`
200 makes it too easy to silently drop parts of compound strategies. If you need
201 that behaviour, use ``sampled_from(seq) if seq else nothing()``.
202 """
203 values = check_sample(elements, "sampled_from")
204 force_repr = None
205 # check_sample converts to tuple unconditionally, but we want to preserve
206 # square braces for list reprs.
207 # This will not cover custom sequence implementations which return different
208 # braces (or other, more unusual things) for their reprs, but this is a tradeoff
209 # between repr accuracy and greedily-evaluating all sequence reprs (at great
210 # cost for large sequences).
211 force_repr_braces = ("[", "]") if isinstance(elements, list) else None
212 if isinstance(elements, type) and issubclass(elements, enum.Enum):
213 force_repr = f"sampled_from({elements.__module__}.{elements.__name__})"
215 if isclass(elements) and issubclass(elements, enum.Flag):
216 # Combinations of enum.Flag members (including empty) are also members. We generate these
217 # dynamically, because static allocation takes O(2^n) memory. LazyStrategy is used for the
218 # ease of force_repr.
219 # Add all named values, both flag bits (== list(elements)) and aliases. The aliases are
220 # necessary for full coverage for flags that would fail enum.NAMED_FLAGS check, and they
221 # are also nice values to shrink to.
222 flags = sorted(
223 set(elements.__members__.values()),
224 key=lambda v: (bit_count(v.value), v.value),
225 )
226 # Finally, try to construct the empty state if it is not named. It's placed at the
227 # end so that we shrink to named values.
228 flags_with_empty = flags
229 if not flags or flags[0].value != 0:
230 try:
231 flags_with_empty = [*flags, elements(0)]
232 except TypeError: # pragma: no cover
233 # Happens on some python versions (at least 3.12) when there are no named values
234 pass
235 inner = [
236 # Consider one or no named flags set, with shrink-to-named-flag behaviour.
237 # Special cases (length zero or one) are handled by the inner sampled_from.
238 sampled_from(flags_with_empty),
239 ]
240 if len(flags) > 1:
241 inner += [
242 # Uniform distribution over number of named flags or combinations set. The overlap
243 # at r=1 is intentional, it may lead to oversampling but gives consistent shrinking
244 # behaviour.
245 integers(min_value=1, max_value=len(flags))
246 .flatmap(lambda r: sets(sampled_from(flags), min_size=r, max_size=r))
247 .map(lambda s: elements(reduce(operator.or_, s))),
248 ]
249 return LazyStrategy(one_of, args=inner, kwargs={}, force_repr=force_repr)
250 if not values:
252 def has_annotations(elements):
253 if sys.version_info[:2] < (3, 14):
254 return vars(elements).get("__annotations__")
255 else: # pragma: no cover # covered by 3.14 tests
256 import annotationlib
258 return bool(annotationlib.get_annotations(elements))
260 if (
261 isinstance(elements, type)
262 and issubclass(elements, enum.Enum)
263 and has_annotations(elements)
264 ):
265 # See https://github.com/HypothesisWorks/hypothesis/issues/2923
266 raise InvalidArgument(
267 f"Cannot sample from {elements.__module__}.{elements.__name__} "
268 "because it contains no elements. It does however have annotations, "
269 "so maybe you tried to write an enum as if it was a dataclass?"
270 )
271 raise InvalidArgument("Cannot sample from a length-zero sequence.")
272 if len(values) == 1:
273 return just(values[0])
274 return SampledFromStrategy(
275 values, force_repr=force_repr, force_repr_braces=force_repr_braces
276 )
279def _gets_first_item(fn: Callable) -> bool:
280 # Introspection for either `itemgetter(0)`, or `lambda x: x[0]`
281 if isinstance(fn, FunctionType):
282 s = get_pretty_function_description(fn)
283 return bool(re.fullmatch(s, r"lambda ([a-z]+): \1\[0\]"))
284 return isinstance(fn, operator.itemgetter) and repr(fn) == "operator.itemgetter(0)"
287@cacheable
288@defines_strategy()
289def lists(
290 elements: SearchStrategy[Ex],
291 *,
292 min_size: int = 0,
293 max_size: Optional[int] = None,
294 unique_by: Union[
295 None,
296 Callable[[Ex], Hashable],
297 tuple[Callable[[Ex], Hashable], ...],
298 ] = None,
299 unique: bool = False,
300) -> SearchStrategy[list[Ex]]:
301 """Returns a list containing values drawn from elements with length in the
302 interval [min_size, max_size] (no bounds in that direction if these are
303 None). If max_size is 0, only the empty list will be drawn.
305 If ``unique`` is True (or something that evaluates to True), we compare direct
306 object equality, as if unique_by was ``lambda x: x``. This comparison only
307 works for hashable types.
309 If ``unique_by`` is not None it must be a callable or tuple of callables
310 returning a hashable type when given a value drawn from elements. The
311 resulting list will satisfy the condition that for ``i`` != ``j``,
312 ``unique_by(result[i])`` != ``unique_by(result[j])``.
314 If ``unique_by`` is a tuple of callables the uniqueness will be respective
315 to each callable.
317 For example, the following will produce two columns of integers with both
318 columns being unique respectively.
320 .. code-block:: pycon
322 >>> twoints = st.tuples(st.integers(), st.integers())
323 >>> st.lists(twoints, unique_by=(lambda x: x[0], lambda x: x[1]))
325 Examples from this strategy shrink by trying to remove elements from the
326 list, and by shrinking each individual element of the list.
327 """
328 check_valid_sizes(min_size, max_size)
329 check_strategy(elements, "elements")
330 if unique:
331 if unique_by is not None:
332 raise InvalidArgument(
333 "cannot specify both unique and unique_by "
334 "(you probably only want to set unique_by)"
335 )
336 else:
337 unique_by = identity
339 if max_size == 0:
340 return builds(list)
341 if unique_by is not None:
342 if not (callable(unique_by) or isinstance(unique_by, tuple)):
343 raise InvalidArgument(
344 f"{unique_by=} is not a callable or tuple of callables"
345 )
346 if callable(unique_by):
347 unique_by = (unique_by,)
348 if len(unique_by) == 0:
349 raise InvalidArgument("unique_by is empty")
350 for i, f in enumerate(unique_by):
351 if not callable(f):
352 raise InvalidArgument(f"unique_by[{i}]={f!r} is not a callable")
353 # Note that lazy strategies automatically unwrap when passed to a defines_strategy
354 # function.
355 tuple_suffixes = None
356 if (
357 # We're generating a list of tuples unique by the first element, perhaps
358 # via st.dictionaries(), and this will be more efficient if we rearrange
359 # our strategy somewhat to draw the first element then draw add the rest.
360 isinstance(elements, TupleStrategy)
361 and len(elements.element_strategies) >= 1
362 and all(_gets_first_item(fn) for fn in unique_by)
363 ):
364 unique_by = (identity,)
365 tuple_suffixes = TupleStrategy(elements.element_strategies[1:])
366 elements = elements.element_strategies[0]
368 # UniqueSampledListStrategy offers a substantial performance improvement for
369 # unique arrays with few possible elements, e.g. of eight-bit integer types.
370 if (
371 isinstance(elements, IntegersStrategy)
372 and elements.start is not None
373 and elements.end is not None
374 and (elements.end - elements.start) <= 255
375 ):
376 elements = SampledFromStrategy(
377 sorted(range(elements.start, elements.end + 1), key=abs) # type: ignore
378 if elements.end < 0 or elements.start > 0
379 else (
380 list(range(elements.end + 1))
381 + list(range(-1, elements.start - 1, -1))
382 )
383 )
385 if isinstance(elements, SampledFromStrategy):
386 element_count = len(elements.elements)
387 if min_size > element_count:
388 raise InvalidArgument(
389 f"Cannot create a collection of {min_size=} unique "
390 f"elements with values drawn from only {element_count} distinct "
391 "elements"
392 )
394 if max_size is not None:
395 max_size = min(max_size, element_count)
396 else:
397 max_size = element_count
399 return UniqueSampledListStrategy(
400 elements=elements,
401 max_size=max_size,
402 min_size=min_size,
403 keys=unique_by,
404 tuple_suffixes=tuple_suffixes,
405 )
407 return UniqueListStrategy(
408 elements=elements,
409 max_size=max_size,
410 min_size=min_size,
411 keys=unique_by,
412 tuple_suffixes=tuple_suffixes,
413 )
414 return ListStrategy(elements, min_size=min_size, max_size=max_size)
417@cacheable
418@defines_strategy()
419def sets(
420 elements: SearchStrategy[Ex],
421 *,
422 min_size: int = 0,
423 max_size: Optional[int] = None,
424) -> SearchStrategy[set[Ex]]:
425 """This has the same behaviour as lists, but returns sets instead.
427 Note that Hypothesis cannot tell if values are drawn from elements
428 are hashable until running the test, so you can define a strategy
429 for sets of an unhashable type but it will fail at test time.
431 Examples from this strategy shrink by trying to remove elements from the
432 set, and by shrinking each individual element of the set.
433 """
434 return lists(
435 elements=elements, min_size=min_size, max_size=max_size, unique=True
436 ).map(set)
439@cacheable
440@defines_strategy()
441def frozensets(
442 elements: SearchStrategy[Ex],
443 *,
444 min_size: int = 0,
445 max_size: Optional[int] = None,
446) -> SearchStrategy[frozenset[Ex]]:
447 """This is identical to the sets function but instead returns
448 frozensets."""
449 return lists(
450 elements=elements, min_size=min_size, max_size=max_size, unique=True
451 ).map(frozenset)
454class PrettyIter:
455 def __init__(self, values):
456 self._values = values
457 self._iter = iter(self._values)
459 def __iter__(self):
460 return self._iter
462 def __next__(self):
463 return next(self._iter)
465 def __repr__(self) -> str:
466 return f"iter({self._values!r})"
469@defines_strategy()
470def iterables(
471 elements: SearchStrategy[Ex],
472 *,
473 min_size: int = 0,
474 max_size: Optional[int] = None,
475 unique_by: Union[
476 None,
477 Callable[[Ex], Hashable],
478 tuple[Callable[[Ex], Hashable], ...],
479 ] = None,
480 unique: bool = False,
481) -> SearchStrategy[Iterable[Ex]]:
482 """This has the same behaviour as lists, but returns iterables instead.
484 Some iterables cannot be indexed (e.g. sets) and some do not have a
485 fixed length (e.g. generators). This strategy produces iterators,
486 which cannot be indexed and do not have a fixed length. This ensures
487 that you do not accidentally depend on sequence behaviour.
488 """
489 return lists(
490 elements=elements,
491 min_size=min_size,
492 max_size=max_size,
493 unique_by=unique_by,
494 unique=unique,
495 ).map(PrettyIter)
498# this type definition is imprecise, in multiple ways:
499# * mapping and optional can be of different types:
500# s: dict[str | int, int] = st.fixed_dictionaries(
501# {"a": st.integers()}, optional={1: st.integers()}
502# )
503# * the values in either mapping or optional need not all be of the same type:
504# s: dict[str, int | bool] = st.fixed_dictionaries(
505# {"a": st.integers(), "b": st.booleans()}
506# )
507# * the arguments may be of any dict-compatible type, in which case the return
508# value will be of that type instead of dit
509#
510# Overloads may help here, but I doubt we'll be able to satisfy all these
511# constraints.
512#
513# Here's some platonic ideal test cases for revealed_types.py, with the understanding
514# that some may not be achievable:
515#
516# ("fixed_dictionaries({'a': booleans()})", "dict[str, bool]"),
517# ("fixed_dictionaries({'a': booleans(), 'b': integers()})", "dict[str, bool | int]"),
518# ("fixed_dictionaries({}, optional={'a': booleans()})", "dict[str, bool]"),
519# (
520# "fixed_dictionaries({'a': booleans()}, optional={1: booleans()})",
521# "dict[str | int, bool]",
522# ),
523# (
524# "fixed_dictionaries({'a': booleans()}, optional={1: integers()})",
525# "dict[str | int, bool | int]",
526# ),
529@defines_strategy()
530def fixed_dictionaries(
531 mapping: dict[T, SearchStrategy[Ex]],
532 *,
533 optional: Optional[dict[T, SearchStrategy[Ex]]] = None,
534) -> SearchStrategy[dict[T, Ex]]:
535 """Generates a dictionary of the same type as mapping with a fixed set of
536 keys mapping to strategies. ``mapping`` must be a dict subclass.
538 Generated values have all keys present in mapping, in iteration order,
539 with the corresponding values drawn from mapping[key].
541 If ``optional`` is passed, the generated value *may or may not* contain each
542 key from ``optional`` and a value drawn from the corresponding strategy.
543 Generated values may contain optional keys in an arbitrary order.
545 Examples from this strategy shrink by shrinking each individual value in
546 the generated dictionary, and omitting optional key-value pairs.
547 """
548 check_type(dict, mapping, "mapping")
549 for k, v in mapping.items():
550 check_strategy(v, f"mapping[{k!r}]")
552 if optional is not None:
553 check_type(dict, optional, "optional")
554 for k, v in optional.items():
555 check_strategy(v, f"optional[{k!r}]")
556 if type(mapping) != type(optional):
557 raise InvalidArgument(
558 f"Got arguments of different types: "
559 f"mapping={nicerepr(type(mapping))}, "
560 f"optional={nicerepr(type(optional))}"
561 )
562 if set(mapping) & set(optional):
563 raise InvalidArgument(
564 "The following keys were in both mapping and optional, "
565 f"which is invalid: {set(mapping) & set(optional)!r}"
566 )
568 return FixedDictStrategy(mapping, optional=optional)
571_get_first_item = operator.itemgetter(0)
574@cacheable
575@defines_strategy()
576def dictionaries(
577 keys: SearchStrategy[Ex],
578 values: SearchStrategy[T],
579 *,
580 dict_class: type = dict,
581 min_size: int = 0,
582 max_size: Optional[int] = None,
583) -> SearchStrategy[dict[Ex, T]]:
584 # Describing the exact dict_class to Mypy drops the key and value types,
585 # so we report Dict[K, V] instead of Mapping[Any, Any] for now. Sorry!
586 """Generates dictionaries of type ``dict_class`` with keys drawn from the ``keys``
587 argument and values drawn from the ``values`` argument.
589 The size parameters have the same interpretation as for
590 :func:`~hypothesis.strategies.lists`.
592 Examples from this strategy shrink by trying to remove keys from the
593 generated dictionary, and by shrinking each generated key and value.
594 """
595 check_valid_sizes(min_size, max_size)
596 if max_size == 0:
597 return fixed_dictionaries(dict_class())
598 check_strategy(keys, "keys")
599 check_strategy(values, "values")
601 return lists(
602 tuples(keys, values),
603 min_size=min_size,
604 max_size=max_size,
605 unique_by=_get_first_item,
606 ).map(dict_class)
609@cacheable
610@defines_strategy(force_reusable_values=True)
611def characters(
612 *,
613 codec: Optional[str] = None,
614 min_codepoint: Optional[int] = None,
615 max_codepoint: Optional[int] = None,
616 categories: Optional[Collection[CategoryName]] = None,
617 exclude_categories: Optional[Collection[CategoryName]] = None,
618 exclude_characters: Optional[Collection[str]] = None,
619 include_characters: Optional[Collection[str]] = None,
620 # Note: these arguments are deprecated aliases for backwards compatibility
621 blacklist_categories: Optional[Collection[CategoryName]] = None,
622 whitelist_categories: Optional[Collection[CategoryName]] = None,
623 blacklist_characters: Optional[Collection[str]] = None,
624 whitelist_characters: Optional[Collection[str]] = None,
625) -> SearchStrategy[str]:
626 r"""Generates characters, length-one :class:`python:str`\ ings,
627 following specified filtering rules.
629 - When no filtering rules are specified, any character can be produced.
630 - If ``min_codepoint`` or ``max_codepoint`` is specified, then only
631 characters having a codepoint in that range will be produced.
632 - If ``categories`` is specified, then only characters from those
633 Unicode categories will be produced. This is a further restriction,
634 characters must also satisfy ``min_codepoint`` and ``max_codepoint``.
635 - If ``exclude_categories`` is specified, then any character from those
636 categories will not be produced. You must not pass both ``categories``
637 and ``exclude_categories``; these arguments are alternative ways to
638 specify exactly the same thing.
639 - If ``include_characters`` is specified, then any additional characters
640 in that list will also be produced.
641 - If ``exclude_characters`` is specified, then any characters in
642 that list will be not be produced. Any overlap between
643 ``include_characters`` and ``exclude_characters`` will raise an
644 exception.
645 - If ``codec`` is specified, only characters in the specified `codec encodings`_
646 will be produced.
648 The ``_codepoint`` arguments must be integers between zero and
649 :obj:`python:sys.maxunicode`. The ``_characters`` arguments must be
650 collections of length-one unicode strings, such as a unicode string.
652 The ``_categories`` arguments must be used to specify either the
653 one-letter Unicode major category or the two-letter Unicode
654 `general category`_. For example, ``('Nd', 'Lu')`` signifies "Number,
655 decimal digit" and "Letter, uppercase". A single letter ('major category')
656 can be given to match all corresponding categories, for example ``'P'``
657 for characters in any punctuation category.
659 We allow codecs from the :mod:`codecs` module and their aliases, platform
660 specific and user-registered codecs if they are available, and
661 `python-specific text encodings`_ (but not text or binary transforms).
662 ``include_characters`` which cannot be encoded using this codec will
663 raise an exception. If non-encodable codepoints or categories are
664 explicitly allowed, the ``codec`` argument will exclude them without
665 raising an exception.
667 .. _general category: https://en.wikipedia.org/wiki/Unicode_character_property
668 .. _codec encodings: https://docs.python.org/3/library/codecs.html#encodings-and-unicode
669 .. _python-specific text encodings: https://docs.python.org/3/library/codecs.html#python-specific-encodings
671 Examples from this strategy shrink towards the codepoint for ``'0'``,
672 or the first allowable codepoint after it if ``'0'`` is excluded.
673 """
674 check_valid_size(min_codepoint, "min_codepoint")
675 check_valid_size(max_codepoint, "max_codepoint")
676 check_valid_interval(min_codepoint, max_codepoint, "min_codepoint", "max_codepoint")
677 categories = cast(Optional[Categories], categories)
678 if categories is not None and exclude_categories is not None:
679 raise InvalidArgument(
680 f"Pass at most one of {categories=} and {exclude_categories=} - "
681 "these arguments both specify which categories are allowed, so it "
682 "doesn't make sense to use both in a single call."
683 )
685 # Handle deprecation of whitelist/blacklist arguments
686 has_old_arg = any(v is not None for k, v in locals().items() if "list" in k)
687 has_new_arg = any(v is not None for k, v in locals().items() if "lude" in k)
688 if has_old_arg and has_new_arg:
689 raise InvalidArgument(
690 "The deprecated blacklist/whitelist arguments cannot be used in "
691 "the same call as their replacement include/exclude arguments."
692 )
693 if blacklist_categories is not None:
694 exclude_categories = blacklist_categories
695 if whitelist_categories is not None:
696 categories = whitelist_categories
697 if blacklist_characters is not None:
698 exclude_characters = blacklist_characters
699 if whitelist_characters is not None:
700 include_characters = whitelist_characters
702 if (
703 min_codepoint is None
704 and max_codepoint is None
705 and categories is None
706 and exclude_categories is None
707 and include_characters is not None
708 and codec is None
709 ):
710 raise InvalidArgument(
711 "Nothing is excluded by other arguments, so passing only "
712 f"{include_characters=} would have no effect. "
713 "Also pass categories=(), or use "
714 f"sampled_from({include_characters!r}) instead."
715 )
716 exclude_characters = exclude_characters or ""
717 include_characters = include_characters or ""
718 if not_one_char := [c for c in exclude_characters if len(c) != 1]:
719 raise InvalidArgument(
720 "Elements of exclude_characters are required to be a single character, "
721 f"but {not_one_char!r} passed in {exclude_characters=} was not."
722 )
723 if not_one_char := [c for c in include_characters if len(c) != 1]:
724 raise InvalidArgument(
725 "Elements of include_characters are required to be a single character, "
726 f"but {not_one_char!r} passed in {include_characters=} was not."
727 )
728 overlap = set(exclude_characters).intersection(include_characters)
729 if overlap:
730 raise InvalidArgument(
731 f"Characters {sorted(overlap)!r} are present in both "
732 f"{include_characters=} and {exclude_characters=}"
733 )
734 if categories is not None:
735 categories = as_general_categories(categories, "categories")
736 if exclude_categories is not None:
737 exclude_categories = as_general_categories(
738 exclude_categories, "exclude_categories"
739 )
740 if categories is not None and not categories and not include_characters:
741 raise InvalidArgument(
742 "When `categories` is an empty collection and there are "
743 "no characters specified in include_characters, nothing can "
744 "be generated by the characters() strategy."
745 )
746 both_cats = set(exclude_categories or ()).intersection(categories or ())
747 if both_cats:
748 # Note: we check that exactly one of `categories` or `exclude_categories` is
749 # passed above, but retain this older check for the deprecated arguments.
750 raise InvalidArgument(
751 f"Categories {sorted(both_cats)!r} are present in both "
752 f"{categories=} and {exclude_categories=}"
753 )
754 elif exclude_categories is not None:
755 categories = set(all_categories()) - set(exclude_categories)
756 del exclude_categories
758 if codec is not None:
759 try:
760 codec = codecs.lookup(codec).name
761 # Check this is not a str-to-str or bytes-to-bytes codec; see
762 # https://docs.python.org/3/library/codecs.html#binary-transforms
763 "".encode(codec)
764 except LookupError:
765 raise InvalidArgument(f"{codec=} is not valid on this system") from None
766 except Exception:
767 raise InvalidArgument(f"{codec=} is not a valid codec") from None
769 for char in include_characters:
770 try:
771 char.encode(encoding=codec, errors="strict")
772 except UnicodeEncodeError:
773 raise InvalidArgument(
774 f"Character {char!r} in {include_characters=} "
775 f"cannot be encoded with {codec=}"
776 ) from None
778 # ascii and utf-8 are sufficient common that we have faster special handling
779 if codec == "ascii":
780 if (max_codepoint is None) or (max_codepoint > 127):
781 max_codepoint = 127
782 codec = None
783 elif codec == "utf-8":
784 if categories is None:
785 categories = all_categories()
786 categories = tuple(c for c in categories if c != "Cs")
788 return OneCharStringStrategy.from_characters_args(
789 categories=categories,
790 exclude_characters=exclude_characters,
791 min_codepoint=min_codepoint,
792 max_codepoint=max_codepoint,
793 include_characters=include_characters,
794 codec=codec,
795 )
798# Hide the deprecated aliases from documentation and casual inspection
799characters.__signature__ = (__sig := get_signature(characters)).replace( # type: ignore
800 parameters=[p for p in __sig.parameters.values() if "list" not in p.name]
801)
804@cacheable
805@defines_strategy(force_reusable_values=True)
806def text(
807 alphabet: Union[Collection[str], SearchStrategy[str]] = characters(codec="utf-8"),
808 *,
809 min_size: int = 0,
810 max_size: Optional[int] = None,
811) -> SearchStrategy[str]:
812 """Generates strings with characters drawn from ``alphabet``, which should
813 be a collection of length one strings or a strategy generating such strings.
815 The default alphabet strategy can generate the full unicode range but
816 excludes surrogate characters because they are invalid in the UTF-8
817 encoding. You can use :func:`~hypothesis.strategies.characters` without
818 arguments to find surrogate-related bugs such as :bpo:`34454`.
820 ``min_size`` and ``max_size`` have the usual interpretations.
821 Note that Python measures string length by counting codepoints: U+00C5
822 ``Å`` is a single character, while U+0041 U+030A ``Å`` is two - the ``A``,
823 and a combining ring above.
825 Examples from this strategy shrink towards shorter strings, and with the
826 characters in the text shrinking as per the alphabet strategy.
827 This strategy does not :func:`~python:unicodedata.normalize` examples,
828 so generated strings may be in any or none of the 'normal forms'.
829 """
830 check_valid_sizes(min_size, max_size)
831 if isinstance(alphabet, SearchStrategy):
832 char_strategy = unwrap_strategies(alphabet)
833 if isinstance(char_strategy, SampledFromStrategy):
834 # Check this via the up-front validation logic below, and incidentally
835 # convert into a `characters()` strategy for standard text shrinking.
836 return text(char_strategy.elements, min_size=min_size, max_size=max_size)
837 elif not isinstance(char_strategy, OneCharStringStrategy):
838 char_strategy = char_strategy.map(_check_is_single_character)
839 else:
840 non_string = [c for c in alphabet if not isinstance(c, str)]
841 if non_string:
842 raise InvalidArgument(
843 "The following elements in alphabet are not unicode "
844 f"strings: {non_string!r}"
845 )
846 not_one_char = [c for c in alphabet if len(c) != 1]
847 if not_one_char:
848 raise InvalidArgument(
849 "The following elements in alphabet are not of length one, "
850 f"which leads to violation of size constraints: {not_one_char!r}"
851 )
852 if alphabet in ["ascii", "utf-8"]:
853 warnings.warn(
854 f"st.text({alphabet!r}): it seems like you are trying to use the "
855 f"codec {alphabet!r}. st.text({alphabet!r}) instead generates "
856 f"strings using the literal characters {list(alphabet)!r}. To specify "
857 f"the {alphabet} codec, use st.text(st.characters(codec={alphabet!r})). "
858 "If you intended to use character literals, you can silence this "
859 "warning by reordering the characters.",
860 HypothesisWarning,
861 # this stacklevel is of course incorrect, but breaking out of the
862 # levels of LazyStrategy and validation isn't worthwhile.
863 stacklevel=1,
864 )
865 char_strategy = (
866 characters(categories=(), include_characters=alphabet)
867 if alphabet
868 else nothing()
869 )
870 if (max_size == 0 or char_strategy.is_empty) and not min_size:
871 return just("")
872 # mypy is unhappy with ListStrategy(SearchStrategy[list[Ex]]) and then TextStrategy
873 # setting Ex = str. Mypy is correct to complain because we have an LSP violation
874 # here in the TextStrategy.do_draw override. Would need refactoring to resolve.
875 return TextStrategy(char_strategy, min_size=min_size, max_size=max_size) # type: ignore
878@overload
879def from_regex(
880 regex: Union[bytes, Pattern[bytes]],
881 *,
882 fullmatch: bool = False,
883) -> SearchStrategy[bytes]: # pragma: no cover
884 ...
887@overload
888def from_regex(
889 regex: Union[str, Pattern[str]],
890 *,
891 fullmatch: bool = False,
892 alphabet: Union[str, SearchStrategy[str]] = characters(codec="utf-8"),
893) -> SearchStrategy[str]: # pragma: no cover
894 ...
897@cacheable
898@defines_strategy()
899def from_regex(
900 regex: Union[AnyStr, Pattern[AnyStr]],
901 *,
902 fullmatch: bool = False,
903 alphabet: Union[str, SearchStrategy[str], None] = None,
904) -> SearchStrategy[AnyStr]:
905 r"""Generates strings that contain a match for the given regex (i.e. ones
906 for which :func:`python:re.search` will return a non-None result).
908 ``regex`` may be a pattern or :func:`compiled regex <python:re.compile>`.
909 Both byte-strings and unicode strings are supported, and will generate
910 examples of the same type.
912 You can use regex flags such as :obj:`python:re.IGNORECASE` or
913 :obj:`python:re.DOTALL` to control generation. Flags can be passed either
914 in compiled regex or inside the pattern with a ``(?iLmsux)`` group.
916 Some regular expressions are only partly supported - the underlying
917 strategy checks local matching and relies on filtering to resolve
918 context-dependent expressions. Using too many of these constructs may
919 cause health-check errors as too many examples are filtered out. This
920 mainly includes (positive or negative) lookahead and lookbehind groups.
922 If you want the generated string to match the whole regex you should use
923 boundary markers. So e.g. ``r"\A.\Z"`` will return a single character
924 string, while ``"."`` will return any string, and ``r"\A.$"`` will return
925 a single character optionally followed by a ``"\n"``.
926 Alternatively, passing ``fullmatch=True`` will ensure that the whole
927 string is a match, as if you had used the ``\A`` and ``\Z`` markers.
929 The ``alphabet=`` argument constrains the characters in the generated
930 string, as for :func:`text`, and is only supported for unicode strings.
932 Examples from this strategy shrink towards shorter strings and lower
933 character values, with exact behaviour that may depend on the pattern.
934 """
935 check_type((str, bytes, re.Pattern), regex, "regex")
936 check_type(bool, fullmatch, "fullmatch")
937 pattern = regex.pattern if isinstance(regex, re.Pattern) else regex
938 if alphabet is not None:
939 check_type((str, SearchStrategy), alphabet, "alphabet")
940 if not isinstance(pattern, str):
941 raise InvalidArgument("alphabet= is not supported for bytestrings")
942 alphabet = OneCharStringStrategy.from_alphabet(alphabet)
943 elif isinstance(pattern, str):
944 alphabet = characters(codec="utf-8")
946 # TODO: We would like to move this to the top level, but pending some major
947 # refactoring it's hard to do without creating circular imports.
948 from hypothesis.strategies._internal.regex import regex_strategy
950 return regex_strategy(regex, fullmatch, alphabet=alphabet)
953@cacheable
954@defines_strategy(force_reusable_values=True)
955def binary(
956 *,
957 min_size: int = 0,
958 max_size: Optional[int] = None,
959) -> SearchStrategy[bytes]:
960 """Generates :class:`python:bytes`.
962 The generated :class:`python:bytes` will have a length of at least ``min_size``
963 and at most ``max_size``. If ``max_size`` is None there is no upper limit.
965 Examples from this strategy shrink towards smaller strings and lower byte
966 values.
967 """
968 check_valid_sizes(min_size, max_size)
969 return BytesStrategy(min_size, max_size)
972@cacheable
973@defines_strategy()
974def randoms(
975 *,
976 note_method_calls: bool = False,
977 use_true_random: bool = False,
978) -> SearchStrategy[random.Random]:
979 """Generates instances of ``random.Random``. The generated Random instances
980 are of a special HypothesisRandom subclass.
982 - If ``note_method_calls`` is set to ``True``, Hypothesis will print the
983 randomly drawn values in any falsifying test case. This can be helpful
984 for debugging the behaviour of randomized algorithms.
985 - If ``use_true_random`` is set to ``True`` then values will be drawn from
986 their usual distribution, otherwise they will actually be Hypothesis
987 generated values (and will be shrunk accordingly for any failing test
988 case). Setting ``use_true_random=False`` will tend to expose bugs that
989 would occur with very low probability when it is set to True, and this
990 flag should only be set to True when your code relies on the distribution
991 of values for correctness.
993 For managing global state, see the :func:`~hypothesis.strategies.random_module`
994 strategy and :func:`~hypothesis.register_random` function.
995 """
996 check_type(bool, note_method_calls, "note_method_calls")
997 check_type(bool, use_true_random, "use_true_random")
999 from hypothesis.strategies._internal.random import RandomStrategy
1001 return RandomStrategy(
1002 use_true_random=use_true_random, note_method_calls=note_method_calls
1003 )
1006class RandomSeeder:
1007 def __init__(self, seed):
1008 self.seed = seed
1010 def __repr__(self):
1011 return f"RandomSeeder({self.seed!r})"
1014class RandomModule(SearchStrategy):
1015 def do_draw(self, data: ConjectureData) -> RandomSeeder:
1016 # It would be unsafe to do run this method more than once per test case,
1017 # because cleanup() runs tasks in FIFO order (at time of writing!).
1018 # Fortunately, the random_module() strategy wraps us in shared(), so
1019 # it's cached for all but the first of any number of calls.
1020 seed = data.draw(integers(0, 2**32 - 1))
1021 seed_all, restore_all = get_seeder_and_restorer(seed)
1022 seed_all()
1023 cleanup(restore_all)
1024 return RandomSeeder(seed)
1027@cacheable
1028@defines_strategy()
1029def random_module() -> SearchStrategy[RandomSeeder]:
1030 """Hypothesis always seeds global PRNGs before running a test, and restores the
1031 previous state afterwards.
1033 If having a fixed seed would unacceptably weaken your tests, and you
1034 cannot use a ``random.Random`` instance provided by
1035 :func:`~hypothesis.strategies.randoms`, this strategy calls
1036 :func:`python:random.seed` with an arbitrary integer and passes you
1037 an opaque object whose repr displays the seed value for debugging.
1038 If ``numpy.random`` is available, that state is also managed, as is anything
1039 managed by :func:`hypothesis.register_random`.
1041 Examples from these strategy shrink to seeds closer to zero.
1042 """
1043 return shared(RandomModule(), key="hypothesis.strategies.random_module()")
1046class BuildsStrategy(SearchStrategy[Ex]):
1047 def __init__(
1048 self,
1049 target: Callable[..., Ex],
1050 args: tuple[SearchStrategy[Any], ...],
1051 kwargs: dict[str, SearchStrategy[Any]],
1052 ):
1053 super().__init__()
1054 self.target = target
1055 self.args = args
1056 self.kwargs = kwargs
1058 def calc_label(self) -> int:
1059 return combine_labels(
1060 self.class_label,
1061 calc_label_from_callable(self.target),
1062 *[strat.label for strat in self.args],
1063 *[calc_label_from_name(k) for k in self.kwargs],
1064 *[strat.label for strat in self.kwargs.values()],
1065 )
1067 def do_draw(self, data: ConjectureData) -> Ex:
1068 args = [data.draw(s) for s in self.args]
1069 kwargs = {k: data.draw(v) for k, v in self.kwargs.items()}
1070 try:
1071 obj = self.target(*args, **kwargs)
1072 except TypeError as err:
1073 if (
1074 isinstance(self.target, type)
1075 and issubclass(self.target, enum.Enum)
1076 and not (self.args or self.kwargs)
1077 ):
1078 name = self.target.__module__ + "." + self.target.__qualname__
1079 raise InvalidArgument(
1080 f"Calling {name} with no arguments raised an error - "
1081 f"try using sampled_from({name}) instead of builds({name})"
1082 ) from err
1083 if not (self.args or self.kwargs):
1084 from .types import is_a_new_type, is_generic_type
1086 if is_a_new_type(self.target) or is_generic_type(self.target):
1087 raise InvalidArgument(
1088 f"Calling {self.target!r} with no arguments raised an "
1089 f"error - try using from_type({self.target!r}) instead "
1090 f"of builds({self.target!r})"
1091 ) from err
1092 if getattr(self.target, "__no_type_check__", None) is True:
1093 # Note: could use PEP-678 __notes__ here. Migrate over once we're
1094 # using an `exceptiongroup` backport with support for that.
1095 raise TypeError(
1096 "This might be because the @no_type_check decorator prevented "
1097 "Hypothesis from inferring a strategy for some required arguments."
1098 ) from err
1099 raise
1101 current_build_context().record_call(obj, self.target, args=args, kwargs=kwargs)
1102 return obj
1104 def do_validate(self) -> None:
1105 tuples(*self.args).validate()
1106 fixed_dictionaries(self.kwargs).validate()
1108 def __repr__(self) -> str:
1109 bits = [get_pretty_function_description(self.target)]
1110 bits.extend(map(repr, self.args))
1111 bits.extend(f"{k}={v!r}" for k, v in self.kwargs.items())
1112 return f"builds({', '.join(bits)})"
1115@cacheable
1116@defines_strategy()
1117def builds(
1118 target: Callable[..., Ex],
1119 /,
1120 *args: SearchStrategy[Any],
1121 **kwargs: Union[SearchStrategy[Any], EllipsisType],
1122) -> SearchStrategy[Ex]:
1123 """Generates values by drawing from ``args`` and ``kwargs`` and passing
1124 them to the callable (provided as the first positional argument) in the
1125 appropriate argument position.
1127 e.g. ``builds(target, integers(), flag=booleans())`` would draw an
1128 integer ``i`` and a boolean ``b`` and call ``target(i, flag=b)``.
1130 If the callable has type annotations, they will be used to infer a strategy
1131 for required arguments that were not passed to builds. You can also tell
1132 builds to infer a strategy for an optional argument by passing ``...``
1133 (:obj:`python:Ellipsis`) as a keyword argument to builds, instead of a strategy for
1134 that argument to the callable.
1136 If the callable is a class defined with :pypi:`attrs`, missing required
1137 arguments will be inferred from the attribute on a best-effort basis,
1138 e.g. by checking :ref:`attrs standard validators <attrs:api-validators>`.
1139 Dataclasses are handled natively by the inference from type hints.
1141 Examples from this strategy shrink by shrinking the argument values to
1142 the callable.
1143 """
1144 if not callable(target):
1145 from hypothesis.strategies._internal.types import is_a_union
1147 # before 3.14, unions were callable, so it got an error message in
1148 # BuildsStrategy.do_draw. In 3.14+, unions are not callable, so
1149 # we error earlier here instead.
1150 suggestion = (
1151 f" Try using from_type({target}) instead?" if is_a_union(target) else ""
1152 )
1153 raise InvalidArgument(
1154 "The first positional argument to builds() must be a callable "
1155 f"target to construct.{suggestion}"
1156 )
1158 if ... in args: # type: ignore # we only annotated the allowed types
1159 # Avoid an implementation nightmare juggling tuples and worse things
1160 raise InvalidArgument(
1161 "... was passed as a positional argument to "
1162 "builds(), but is only allowed as a keyword arg"
1163 )
1164 required = required_args(target, args, kwargs)
1165 to_infer = {k for k, v in kwargs.items() if v is ...}
1166 if required or to_infer:
1167 if isinstance(target, type) and attr.has(target):
1168 # Use our custom introspection for attrs classes
1169 from hypothesis.strategies._internal.attrs import from_attrs
1171 return from_attrs(target, args, kwargs, required | to_infer)
1172 # Otherwise, try using type hints
1173 hints = get_type_hints(target)
1174 if to_infer - set(hints):
1175 badargs = ", ".join(sorted(to_infer - set(hints)))
1176 raise InvalidArgument(
1177 f"passed ... for {badargs}, but we cannot infer a strategy "
1178 "because these arguments have no type annotation"
1179 )
1180 infer_for = {k: v for k, v in hints.items() if k in (required | to_infer)}
1181 if infer_for:
1182 from hypothesis.strategies._internal.types import _global_type_lookup
1184 for kw, t in infer_for.items():
1185 if t in _global_type_lookup:
1186 kwargs[kw] = from_type(t)
1187 else:
1188 # We defer resolution of these type annotations so that the obvious
1189 # approach to registering recursive types just works. I.e.,
1190 # if we're inside `register_type_strategy(cls, builds(cls, ...))`
1191 # and `...` contains recursion on `cls`. See
1192 # https://github.com/HypothesisWorks/hypothesis/issues/3026
1193 kwargs[kw] = deferred(lambda t=t: from_type(t)) # type: ignore
1195 # validated by handling all EllipsisType in the to_infer case
1196 kwargs = cast(dict[str, SearchStrategy], kwargs)
1197 return BuildsStrategy(target, args, kwargs)
1200@cacheable
1201@defines_strategy(never_lazy=True)
1202def from_type(thing: type[T]) -> SearchStrategy[T]:
1203 """Looks up the appropriate search strategy for the given type.
1205 |st.from_type| is used internally to fill in missing arguments to
1206 |st.builds| and can be used interactively
1207 to explore what strategies are available or to debug type resolution.
1209 You can use |st.register_type_strategy| to
1210 handle your custom types, or to globally redefine certain strategies -
1211 for example excluding NaN from floats, or use timezone-aware instead of
1212 naive time and datetime strategies.
1214 |st.from_type| looks up a strategy in the following order:
1216 1. If ``thing`` is in the default lookup mapping or user-registered lookup,
1217 return the corresponding strategy. The default lookup covers all types
1218 with Hypothesis strategies, including extras where possible.
1219 2. If ``thing`` is from the :mod:`python:typing` module, return the
1220 corresponding strategy (special logic).
1221 3. If ``thing`` has one or more subtypes in the merged lookup, return
1222 the union of the strategies for those types that are not subtypes of
1223 other elements in the lookup.
1224 4. Finally, if ``thing`` has type annotations for all required arguments,
1225 and is not an abstract class, it is resolved via
1226 |st.builds|.
1227 5. Because :mod:`abstract types <python:abc>` cannot be instantiated,
1228 we treat abstract types as the union of their concrete subclasses.
1229 Note that this lookup works via inheritance but not via
1230 :obj:`~python:abc.ABCMeta.register`, so you may still need to use
1231 |st.register_type_strategy|.
1233 There is a valuable recipe for leveraging |st.from_type| to generate
1234 "everything except" values from a specified type. I.e.
1236 .. code-block:: python
1238 def everything_except(excluded_types):
1239 return (
1240 from_type(type)
1241 .flatmap(from_type)
1242 .filter(lambda x: not isinstance(x, excluded_types))
1243 )
1245 For example, ``everything_except(int)`` returns a strategy that can
1246 generate anything that |st.from_type| can ever generate, except for
1247 instances of |int|, and excluding instances of types
1248 added via |st.register_type_strategy|.
1250 This is useful when writing tests which check that invalid input is
1251 rejected in a certain way.
1252 """
1253 try:
1254 with warnings.catch_warnings():
1255 warnings.simplefilter("error")
1256 return _from_type(thing)
1257 except Exception:
1258 return _from_type_deferred(thing)
1261def _from_type_deferred(thing: type[Ex]) -> SearchStrategy[Ex]:
1262 # This tricky little dance is because we want to show the repr of the actual
1263 # underlying strategy wherever possible, as a form of user education, but
1264 # would prefer to fall back to the default "from_type(...)" repr instead of
1265 # "deferred(...)" for recursive types or invalid arguments.
1266 try:
1267 thing_repr = nicerepr(thing)
1268 if hasattr(thing, "__module__"):
1269 module_prefix = f"{thing.__module__}."
1270 if not thing_repr.startswith(module_prefix):
1271 thing_repr = module_prefix + thing_repr
1272 repr_ = f"from_type({thing_repr})"
1273 except Exception: # pragma: no cover
1274 repr_ = None
1275 return LazyStrategy(
1276 lambda thing: deferred(lambda: _from_type(thing)),
1277 (thing,),
1278 {},
1279 force_repr=repr_,
1280 )
1283_recurse_guard: ContextVar = ContextVar("recurse_guard")
1286def _from_type(thing: type[Ex]) -> SearchStrategy[Ex]:
1287 # TODO: We would like to move this to the top level, but pending some major
1288 # refactoring it's hard to do without creating circular imports.
1289 from hypothesis.strategies._internal import types
1291 def as_strategy(strat_or_callable, thing):
1292 # User-provided strategies need some validation, and callables even more
1293 # of it. We do this in three places, hence the helper function
1294 if not isinstance(strat_or_callable, SearchStrategy):
1295 assert callable(strat_or_callable) # Validated in register_type_strategy
1296 strategy = strat_or_callable(thing)
1297 else:
1298 strategy = strat_or_callable
1299 if strategy is NotImplemented:
1300 return NotImplemented
1301 if not isinstance(strategy, SearchStrategy):
1302 raise ResolutionFailed(
1303 f"Error: {thing} was registered for {nicerepr(strat_or_callable)}, "
1304 f"but returned non-strategy {strategy!r}"
1305 )
1306 if strategy.is_empty:
1307 raise ResolutionFailed(f"Error: {thing!r} resolved to an empty strategy")
1308 return strategy
1310 def from_type_guarded(thing):
1311 """Returns the result of producer, or ... if recursion on thing is encountered"""
1312 try:
1313 recurse_guard = _recurse_guard.get()
1314 except LookupError:
1315 # We can't simply define the contextvar with default=[], as the
1316 # default object would be shared across contexts
1317 _recurse_guard.set(recurse_guard := [])
1318 if thing in recurse_guard:
1319 raise RewindRecursive(thing)
1320 recurse_guard.append(thing)
1321 try:
1322 return _from_type(thing)
1323 except RewindRecursive as rr:
1324 if rr.target != thing:
1325 raise
1326 return ... # defer resolution
1327 finally:
1328 recurse_guard.pop()
1330 # Let registered extra modules handle their own recognized types first, before
1331 # e.g. Unions are resolved
1332 try:
1333 known = thing in types._global_type_lookup
1334 except TypeError:
1335 # thing is not always hashable!
1336 pass
1337 else:
1338 if not known:
1339 for module, resolver in types._global_extra_lookup.items():
1340 if module in sys.modules:
1341 strat = resolver(thing)
1342 if strat is not None:
1343 return strat
1345 if types.is_a_new_type(thing):
1346 # Check if we have an explicitly registered strategy for this thing,
1347 # resolve it so, and otherwise resolve as for the base type.
1348 if thing in types._global_type_lookup:
1349 strategy = as_strategy(types._global_type_lookup[thing], thing)
1350 if strategy is not NotImplemented:
1351 return strategy
1352 return _from_type(thing.__supertype__) # type: ignore
1353 if types.is_a_type_alias_type(thing): # pragma: no cover # covered by 3.12+ tests
1354 if thing in types._global_type_lookup:
1355 strategy = as_strategy(types._global_type_lookup[thing], thing)
1356 if strategy is not NotImplemented:
1357 return strategy
1358 return _from_type(thing.__value__) # type: ignore
1359 if types.is_a_union(thing):
1360 args = sorted(thing.__args__, key=types.type_sorting_key) # type: ignore
1361 return one_of([_from_type(t) for t in args])
1362 if thing in types.LiteralStringTypes: # pragma: no cover
1363 # We can't really cover this because it needs either
1364 # typing-extensions or python3.11+ typing.
1365 # `LiteralString` from runtime's point of view is just a string.
1366 # Fallback to regular text.
1367 return text() # type: ignore
1369 # We also have a special case for TypeVars.
1370 # They are represented as instances like `~T` when they come here.
1371 # We need to work with their type instead.
1372 if isinstance(thing, TypeVar) and type(thing) in types._global_type_lookup:
1373 strategy = as_strategy(types._global_type_lookup[type(thing)], thing)
1374 if strategy is not NotImplemented:
1375 return strategy
1377 if not types.is_a_type(thing):
1378 if isinstance(thing, str):
1379 # See https://github.com/HypothesisWorks/hypothesis/issues/3016
1380 raise InvalidArgument(
1381 f"Got {thing!r} as a type annotation, but the forward-reference "
1382 "could not be resolved from a string to a type. Consider using "
1383 "`from __future__ import annotations` instead of forward-reference "
1384 "strings."
1385 )
1386 raise InvalidArgument(f"{thing=} must be a type") # pragma: no cover
1388 if thing in types.NON_RUNTIME_TYPES:
1389 # Some code like `st.from_type(TypeAlias)` does not make sense.
1390 # Because there are types in python that do not exist in runtime.
1391 raise InvalidArgument(
1392 f"Could not resolve {thing!r} to a strategy, "
1393 f"because there is no such thing as a runtime instance of {thing!r}"
1394 )
1396 # Now that we know `thing` is a type, the first step is to check for an
1397 # explicitly registered strategy. This is the best (and hopefully most
1398 # common) way to resolve a type to a strategy. Note that the value in the
1399 # lookup may be a strategy or a function from type -> strategy; and we
1400 # convert empty results into an explicit error.
1401 try:
1402 if thing in types._global_type_lookup:
1403 strategy = as_strategy(types._global_type_lookup[thing], thing)
1404 if strategy is not NotImplemented:
1405 return strategy
1406 elif (
1407 isinstance(thing, GenericAlias)
1408 and (to := get_origin(thing)) in types._global_type_lookup
1409 ):
1410 strategy = as_strategy(types._global_type_lookup[to], thing)
1411 if strategy is not NotImplemented:
1412 return strategy
1413 except TypeError: # pragma: no cover
1414 # This was originally due to a bizarre divergence in behaviour on Python 3.9.0:
1415 # typing.Callable[[], foo] has __args__ = (foo,) but collections.abc.Callable
1416 # has __args__ = ([], foo); and as a result is non-hashable.
1417 # We've kept it because we turn out to have more type errors from... somewhere.
1418 # FIXME: investigate that, maybe it should be fixed more precisely?
1419 pass
1421 if (hasattr(typing, "_TypedDictMeta") and type(thing) is typing._TypedDictMeta) or (
1422 hasattr(types.typing_extensions, "_TypedDictMeta") # type: ignore
1423 and type(thing) is types.typing_extensions._TypedDictMeta # type: ignore
1424 ): # pragma: no cover
1426 def _get_annotation_arg(key, annotation_type):
1427 try:
1428 return get_args(annotation_type)[0]
1429 except IndexError:
1430 raise InvalidArgument(
1431 f"`{key}: {annotation_type.__name__}` is not a valid type annotation"
1432 ) from None
1434 # Taken from `Lib/typing.py` and modified:
1435 def _get_typeddict_qualifiers(key, annotation_type):
1436 qualifiers = []
1437 while True:
1438 annotation_origin = types.extended_get_origin(annotation_type)
1439 if annotation_origin is Annotated:
1440 if annotation_args := get_args(annotation_type):
1441 annotation_type = annotation_args[0]
1442 else:
1443 break
1444 elif annotation_origin in types.RequiredTypes:
1445 qualifiers.append(types.RequiredTypes)
1446 annotation_type = _get_annotation_arg(key, annotation_type)
1447 elif annotation_origin in types.NotRequiredTypes:
1448 qualifiers.append(types.NotRequiredTypes)
1449 annotation_type = _get_annotation_arg(key, annotation_type)
1450 elif annotation_origin in types.ReadOnlyTypes:
1451 qualifiers.append(types.ReadOnlyTypes)
1452 annotation_type = _get_annotation_arg(key, annotation_type)
1453 else:
1454 break
1455 return set(qualifiers), annotation_type
1457 # The __optional_keys__ attribute may or may not be present, but if there's no
1458 # way to tell and we just have to assume that everything is required.
1459 # See https://github.com/python/cpython/pull/17214 for details.
1460 optional = set(getattr(thing, "__optional_keys__", ()))
1461 required = set(
1462 getattr(thing, "__required_keys__", get_type_hints(thing).keys())
1463 )
1464 anns = {}
1465 for k, v in get_type_hints(thing).items():
1466 qualifiers, v = _get_typeddict_qualifiers(k, v)
1467 # We ignore `ReadOnly` type for now, only unwrap it.
1468 if types.RequiredTypes in qualifiers:
1469 optional.discard(k)
1470 required.add(k)
1471 if types.NotRequiredTypes in qualifiers:
1472 optional.add(k)
1473 required.discard(k)
1475 anns[k] = from_type_guarded(v)
1476 if anns[k] is ...:
1477 anns[k] = _from_type_deferred(v)
1479 if not required.isdisjoint(optional): # pragma: no cover
1480 # It is impossible to cover, because `typing.py` or `typing-extensions`
1481 # won't allow creating incorrect TypedDicts,
1482 # this is just a sanity check from our side.
1483 raise InvalidArgument(
1484 f"Required keys overlap with optional keys in a TypedDict:"
1485 f" {required=}, {optional=}"
1486 )
1487 if (
1488 (not anns)
1489 and thing.__annotations__
1490 and ".<locals>." in getattr(thing, "__qualname__", "")
1491 ):
1492 raise InvalidArgument("Failed to retrieve type annotations for local type")
1493 return fixed_dictionaries( # type: ignore
1494 mapping={k: v for k, v in anns.items() if k in required},
1495 optional={k: v for k, v in anns.items() if k in optional},
1496 )
1498 # If there's no explicitly registered strategy, maybe a subtype of thing
1499 # is registered - if so, we can resolve it to the subclass strategy.
1500 # We'll start by checking if thing is from from the typing module,
1501 # because there are several special cases that don't play well with
1502 # subclass and instance checks.
1503 if (
1504 isinstance(thing, types.typing_root_type)
1505 or (isinstance(get_origin(thing), type) and get_args(thing))
1506 or isinstance(thing, typing.ForwardRef)
1507 ):
1508 return types.from_typing_type(thing)
1510 # If it's not from the typing module, we get all registered types that are
1511 # a subclass of `thing` and are not themselves a subtype of any other such
1512 # type. For example, `Number -> integers() | floats()`, but bools() is
1513 # not included because bool is a subclass of int as well as Number.
1514 strategies = [
1515 s
1516 for s in (
1517 as_strategy(v, thing)
1518 for k, v in sorted(types._global_type_lookup.items(), key=repr)
1519 if isinstance(k, type)
1520 and issubclass(k, thing)
1521 and sum(types.try_issubclass(k, typ) for typ in types._global_type_lookup)
1522 == 1
1523 )
1524 if s is not NotImplemented
1525 ]
1526 if any(not s.is_empty for s in strategies):
1527 return one_of(strategies)
1529 # If we don't have a strategy registered for this type or any subtype, we
1530 # may be able to fall back on type annotations.
1531 if issubclass(thing, enum.Enum):
1532 return sampled_from(thing)
1534 # Finally, try to build an instance by calling the type object. Unlike builds(),
1535 # this block *does* try to infer strategies for arguments with default values.
1536 # That's because of the semantic different; builds() -> "call this with ..."
1537 # so we only infer when *not* doing so would be an error; from_type() -> "give
1538 # me arbitrary instances" so the greater variety is acceptable.
1539 # And if it's *too* varied, express your opinions with register_type_strategy()
1540 if not isabstract(thing):
1541 # If we know that builds(thing) will fail, give a better error message
1542 required = required_args(thing)
1543 if required and not (
1544 required.issubset(get_type_hints(thing))
1545 or attr.has(thing)
1546 or is_typed_named_tuple(thing) # weird enough that we have a specific check
1547 ):
1548 raise ResolutionFailed(
1549 f"Could not resolve {thing!r} to a strategy; consider "
1550 "using register_type_strategy"
1551 )
1552 try:
1553 hints = get_type_hints(thing)
1554 params = get_signature(thing).parameters
1555 except Exception:
1556 params = {} # type: ignore
1558 posonly_args = []
1559 kwargs = {}
1560 for k, p in params.items():
1561 if (
1562 p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD, p.KEYWORD_ONLY)
1563 and k in hints
1564 and k != "return"
1565 ):
1566 ps = from_type_guarded(hints[k])
1567 if p.default is not Parameter.empty and ps is not ...:
1568 ps = just(p.default) | ps
1569 if p.kind is Parameter.POSITIONAL_ONLY:
1570 # builds() doesn't infer strategies for positional args, so:
1571 if ps is ...: # pragma: no cover # rather fiddly to test
1572 if p.default is Parameter.empty:
1573 raise ResolutionFailed(
1574 f"Could not resolve {thing!r} to a strategy; "
1575 "consider using register_type_strategy"
1576 )
1577 ps = just(p.default)
1578 posonly_args.append(ps)
1579 else:
1580 kwargs[k] = ps
1581 if (
1582 params
1583 and not (posonly_args or kwargs)
1584 and not issubclass(thing, BaseException)
1585 ):
1586 from_type_repr = repr_call(from_type, (thing,), {})
1587 builds_repr = repr_call(builds, (thing,), {})
1588 warnings.warn(
1589 f"{from_type_repr} resolved to {builds_repr}, because we could not "
1590 "find any (non-varargs) arguments. Use st.register_type_strategy() "
1591 "to resolve to a strategy which can generate more than one value, "
1592 "or silence this warning.",
1593 SmallSearchSpaceWarning,
1594 stacklevel=2,
1595 )
1596 return builds(thing, *posonly_args, **kwargs)
1598 # And if it's an abstract type, we'll resolve to a union of subclasses instead.
1599 subclasses = thing.__subclasses__()
1600 if not subclasses:
1601 raise ResolutionFailed(
1602 f"Could not resolve {thing!r} to a strategy, because it is an abstract "
1603 "type without any subclasses. Consider using register_type_strategy"
1604 )
1606 subclass_strategies: SearchStrategy = nothing()
1607 for sc in subclasses:
1608 try:
1609 subclass_strategies |= _from_type(sc)
1610 except Exception:
1611 pass
1612 if subclass_strategies.is_empty:
1613 # We're unable to resolve subclasses now, but we might be able to later -
1614 # so we'll just go back to the mixed distribution.
1615 return sampled_from(subclasses).flatmap(_from_type)
1616 return subclass_strategies
1619@cacheable
1620@defines_strategy(force_reusable_values=True)
1621def fractions(
1622 min_value: Optional[Union[Real, str]] = None,
1623 max_value: Optional[Union[Real, str]] = None,
1624 *,
1625 max_denominator: Optional[int] = None,
1626) -> SearchStrategy[Fraction]:
1627 """Returns a strategy which generates Fractions.
1629 If ``min_value`` is not None then all generated values are no less than
1630 ``min_value``. If ``max_value`` is not None then all generated values are no
1631 greater than ``max_value``. ``min_value`` and ``max_value`` may be anything accepted
1632 by the :class:`~fractions.Fraction` constructor.
1634 If ``max_denominator`` is not None then the denominator of any generated
1635 values is no greater than ``max_denominator``. Note that ``max_denominator`` must
1636 be None or a positive integer.
1638 Examples from this strategy shrink towards smaller denominators, then
1639 closer to zero.
1640 """
1641 min_value = try_convert(Fraction, min_value, "min_value")
1642 max_value = try_convert(Fraction, max_value, "max_value")
1643 # These assertions tell Mypy what happened in try_convert
1644 assert min_value is None or isinstance(min_value, Fraction)
1645 assert max_value is None or isinstance(max_value, Fraction)
1647 check_valid_interval(min_value, max_value, "min_value", "max_value")
1648 check_valid_integer(max_denominator, "max_denominator")
1650 if max_denominator is not None:
1651 if max_denominator < 1:
1652 raise InvalidArgument(f"{max_denominator=} must be >= 1")
1653 if min_value is not None and min_value.denominator > max_denominator:
1654 raise InvalidArgument(
1655 f"The {min_value=} has a denominator greater than the "
1656 f"{max_denominator=}"
1657 )
1658 if max_value is not None and max_value.denominator > max_denominator:
1659 raise InvalidArgument(
1660 f"The {max_value=} has a denominator greater than the "
1661 f"{max_denominator=}"
1662 )
1664 if min_value is not None and min_value == max_value:
1665 return just(min_value)
1667 def dm_func(denom):
1668 """Take denom, construct numerator strategy, and build fraction."""
1669 # Four cases of algebra to get integer bounds and scale factor.
1670 min_num, max_num = None, None
1671 if max_value is None and min_value is None:
1672 pass
1673 elif min_value is None:
1674 max_num = denom * max_value.numerator
1675 denom *= max_value.denominator
1676 elif max_value is None:
1677 min_num = denom * min_value.numerator
1678 denom *= min_value.denominator
1679 else:
1680 low = min_value.numerator * max_value.denominator
1681 high = max_value.numerator * min_value.denominator
1682 scale = min_value.denominator * max_value.denominator
1683 # After calculating our integer bounds and scale factor, we remove
1684 # the gcd to avoid drawing more bytes for the example than needed.
1685 # Note that `div` can be at most equal to `scale`.
1686 div = math.gcd(scale, math.gcd(low, high))
1687 min_num = denom * low // div
1688 max_num = denom * high // div
1689 denom *= scale // div
1691 return builds(
1692 Fraction, integers(min_value=min_num, max_value=max_num), just(denom)
1693 )
1695 if max_denominator is None:
1696 return integers(min_value=1).flatmap(dm_func)
1698 return (
1699 integers(1, max_denominator)
1700 .flatmap(dm_func)
1701 .map(lambda f: f.limit_denominator(max_denominator))
1702 )
1705def _as_finite_decimal(
1706 value: Union[Real, str, None], name: str, allow_infinity: Optional[bool]
1707) -> Optional[Decimal]:
1708 """Convert decimal bounds to decimals, carefully."""
1709 assert name in ("min_value", "max_value")
1710 if value is None:
1711 return None
1712 if not isinstance(value, Decimal):
1713 with localcontext(Context()): # ensure that default traps are enabled
1714 value = try_convert(Decimal, value, name)
1715 assert isinstance(value, Decimal)
1716 if value.is_finite():
1717 return value
1718 if value.is_infinite() and (value < 0 if "min" in name else value > 0):
1719 if allow_infinity or allow_infinity is None:
1720 return None
1721 raise InvalidArgument(f"{allow_infinity=}, but {name}={value!r}")
1722 # This could be infinity, quiet NaN, or signalling NaN
1723 raise InvalidArgument(f"Invalid {name}={value!r}")
1726@cacheable
1727@defines_strategy(force_reusable_values=True)
1728def decimals(
1729 min_value: Optional[Union[Real, str]] = None,
1730 max_value: Optional[Union[Real, str]] = None,
1731 *,
1732 allow_nan: Optional[bool] = None,
1733 allow_infinity: Optional[bool] = None,
1734 places: Optional[int] = None,
1735) -> SearchStrategy[Decimal]:
1736 """Generates instances of :class:`python:decimal.Decimal`, which may be:
1738 - A finite rational number, between ``min_value`` and ``max_value``.
1739 - Not a Number, if ``allow_nan`` is True. None means "allow NaN, unless
1740 ``min_value`` and ``max_value`` are not None".
1741 - Positive or negative infinity, if ``max_value`` and ``min_value``
1742 respectively are None, and ``allow_infinity`` is not False. None means
1743 "allow infinity, unless excluded by the min and max values".
1745 Note that where floats have one ``NaN`` value, Decimals have four: signed,
1746 and either *quiet* or *signalling*. See `the decimal module docs
1747 <https://docs.python.org/3/library/decimal.html#special-values>`_ for
1748 more information on special values.
1750 If ``places`` is not None, all finite values drawn from the strategy will
1751 have that number of digits after the decimal place.
1753 Examples from this strategy do not have a well defined shrink order but
1754 try to maximize human readability when shrinking.
1755 """
1756 # Convert min_value and max_value to Decimal values, and validate args
1757 check_valid_integer(places, "places")
1758 if places is not None and places < 0:
1759 raise InvalidArgument(f"{places=} may not be negative")
1760 min_value = _as_finite_decimal(min_value, "min_value", allow_infinity)
1761 max_value = _as_finite_decimal(max_value, "max_value", allow_infinity)
1762 check_valid_interval(min_value, max_value, "min_value", "max_value")
1763 if allow_infinity and (None not in (min_value, max_value)):
1764 raise InvalidArgument("Cannot allow infinity between finite bounds")
1765 # Set up a strategy for finite decimals. Note that both floating and
1766 # fixed-point decimals require careful handling to remain isolated from
1767 # any external precision context - in short, we always work out the
1768 # required precision for lossless operation and use context methods.
1769 if places is not None:
1770 # Fixed-point decimals are basically integers with a scale factor
1771 def ctx(val):
1772 """Return a context in which this value is lossless."""
1773 precision = ceil(math.log10(abs(val) or 1)) + places + 1
1774 return Context(prec=max([precision, 1]))
1776 def int_to_decimal(val):
1777 context = ctx(val)
1778 return context.quantize(context.multiply(val, factor), factor)
1780 factor = Decimal(10) ** -places
1781 min_num, max_num = None, None
1782 if min_value is not None:
1783 min_num = ceil(ctx(min_value).divide(min_value, factor))
1784 if max_value is not None:
1785 max_num = floor(ctx(max_value).divide(max_value, factor))
1786 if min_num is not None and max_num is not None and min_num > max_num:
1787 raise InvalidArgument(
1788 f"There are no decimals with {places} places between "
1789 f"{min_value=} and {max_value=}"
1790 )
1791 strat = integers(min_num, max_num).map(int_to_decimal)
1792 else:
1793 # Otherwise, they're like fractions featuring a power of ten
1794 def fraction_to_decimal(val):
1795 precision = (
1796 ceil(math.log10(abs(val.numerator) or 1) + math.log10(val.denominator))
1797 + 1
1798 )
1799 return Context(prec=precision or 1).divide(
1800 Decimal(val.numerator), val.denominator
1801 )
1803 strat = fractions(min_value, max_value).map(fraction_to_decimal)
1804 # Compose with sampled_from for infinities and NaNs as appropriate
1805 special: list[Decimal] = []
1806 if allow_nan or (allow_nan is None and (None in (min_value, max_value))):
1807 special.extend(map(Decimal, ("NaN", "-NaN", "sNaN", "-sNaN")))
1808 if allow_infinity or (allow_infinity is None and max_value is None):
1809 special.append(Decimal("Infinity"))
1810 if allow_infinity or (allow_infinity is None and min_value is None):
1811 special.append(Decimal("-Infinity"))
1812 return strat | (sampled_from(special) if special else nothing())
1815@defines_strategy(never_lazy=True)
1816def recursive(
1817 base: SearchStrategy[Ex],
1818 extend: Callable[[SearchStrategy[Any]], SearchStrategy[T]],
1819 *,
1820 max_leaves: int = 100,
1821) -> SearchStrategy[Union[T, Ex]]:
1822 """base: A strategy to start from.
1824 extend: A function which takes a strategy and returns a new strategy.
1826 max_leaves: The maximum number of elements to be drawn from base on a given
1827 run.
1829 This returns a strategy ``S`` such that ``S = extend(base | S)``. That is,
1830 values may be drawn from base, or from any strategy reachable by mixing
1831 applications of | and extend.
1833 An example may clarify: ``recursive(booleans(), lists)`` would return a
1834 strategy that may return arbitrarily nested and mixed lists of booleans.
1835 So e.g. ``False``, ``[True]``, ``[False, []]``, and ``[[[[True]]]]`` are
1836 all valid values to be drawn from that strategy.
1838 Examples from this strategy shrink by trying to reduce the amount of
1839 recursion and by shrinking according to the shrinking behaviour of base
1840 and the result of extend.
1842 """
1844 return RecursiveStrategy(base, extend, max_leaves)
1847class PermutationStrategy(SearchStrategy):
1848 def __init__(self, values):
1849 super().__init__()
1850 self.values = values
1852 def do_draw(self, data):
1853 # Reversed Fisher-Yates shuffle: swap each element with itself or with
1854 # a later element. This shrinks i==j for each element, i.e. to no
1855 # change. We don't consider the last element as it's always a no-op.
1856 result = list(self.values)
1857 for i in range(len(result) - 1):
1858 j = data.draw_integer(i, len(result) - 1)
1859 result[i], result[j] = result[j], result[i]
1860 return result
1863@defines_strategy()
1864def permutations(values: Sequence[T]) -> SearchStrategy[list[T]]:
1865 """Return a strategy which returns permutations of the ordered collection
1866 ``values``.
1868 Examples from this strategy shrink by trying to become closer to the
1869 original order of values.
1870 """
1871 values = check_sample(values, "permutations")
1872 if not values:
1873 return builds(list)
1875 return PermutationStrategy(values)
1878class CompositeStrategy(SearchStrategy):
1879 def __init__(self, definition, args, kwargs):
1880 super().__init__()
1881 self.definition = definition
1882 self.args = args
1883 self.kwargs = kwargs
1885 def do_draw(self, data):
1886 return self.definition(data.draw, *self.args, **self.kwargs)
1888 def calc_label(self) -> int:
1889 return combine_labels(
1890 self.class_label,
1891 calc_label_from_callable(self.definition),
1892 )
1895class DrawFn(Protocol):
1896 """This type only exists so that you can write type hints for functions
1897 decorated with :func:`@composite <hypothesis.strategies.composite>`.
1899 .. code-block:: python
1901 def draw(strategy: SearchStrategy[Ex], label: object = None) -> Ex: ...
1903 @composite
1904 def list_and_index(draw: DrawFn) -> tuple[int, str]:
1905 i = draw(integers()) # type of `i` inferred as 'int'
1906 s = draw(text()) # type of `s` inferred as 'str'
1907 return i, s
1908 """
1910 def __init__(self):
1911 raise TypeError("Protocols cannot be instantiated") # pragma: no cover
1913 # Protocol overrides our signature for __init__,
1914 # so we override it right back to make the docs look nice.
1915 __signature__: Signature = Signature(parameters=[])
1917 # We define this as a callback protocol because a simple typing.Callable is
1918 # insufficient to fully represent the interface, due to the optional `label`
1919 # parameter.
1920 def __call__(self, strategy: SearchStrategy[Ex], label: object = None) -> Ex:
1921 raise NotImplementedError
1924def _composite(f):
1925 # Wrapped below, using ParamSpec if available
1926 if isinstance(f, (classmethod, staticmethod)):
1927 special_method = type(f)
1928 f = f.__func__
1929 else:
1930 special_method = None
1932 sig = get_signature(f)
1933 params = tuple(sig.parameters.values())
1935 if not (params and "POSITIONAL" in params[0].kind.name):
1936 raise InvalidArgument(
1937 "Functions wrapped with composite must take at least one "
1938 "positional argument."
1939 )
1940 if params[0].default is not sig.empty:
1941 raise InvalidArgument("A default value for initial argument will never be used")
1942 if not (f is typing._overload_dummy or is_first_param_referenced_in_function(f)):
1943 note_deprecation(
1944 "There is no reason to use @st.composite on a function which "
1945 "does not call the provided draw() function internally.",
1946 since="2022-07-17",
1947 has_codemod=False,
1948 )
1949 if get_origin(sig.return_annotation) is SearchStrategy:
1950 ret_repr = repr(sig.return_annotation).replace("hypothesis.strategies.", "st.")
1951 warnings.warn(
1952 f"Return-type annotation is `{ret_repr}`, but the decorated "
1953 "function should return a value (not a strategy)",
1954 HypothesisWarning,
1955 stacklevel=3 if sys.version_info[:2] > (3, 9) else 5, # ugh
1956 )
1957 if params[0].kind.name != "VAR_POSITIONAL":
1958 params = params[1:]
1959 newsig = sig.replace(
1960 parameters=params,
1961 return_annotation=(
1962 SearchStrategy
1963 if sig.return_annotation is sig.empty
1964 else SearchStrategy[sig.return_annotation]
1965 ),
1966 )
1968 @defines_strategy()
1969 @define_function_signature(f.__name__, f.__doc__, newsig)
1970 def accept(*args, **kwargs):
1971 return CompositeStrategy(f, args, kwargs)
1973 accept.__module__ = f.__module__
1974 accept.__signature__ = newsig
1975 if special_method is not None:
1976 return special_method(accept)
1977 return accept
1980composite_doc = """
1981Defines a strategy that is built out of potentially arbitrarily many other
1982strategies.
1984@composite provides a callable ``draw`` as the first parameter to the decorated
1985function, which can be used to dynamically draw a value from any strategy. For
1986example:
1988.. code-block:: python
1990 from hypothesis import strategies as st, given
1992 @st.composite
1993 def values(draw):
1994 n1 = draw(st.integers())
1995 n2 = draw(st.integers(min_value=n1))
1996 return (n1, n2)
1998 @given(values())
1999 def f(value):
2000 (n1, n2) = value
2001 assert n1 <= n2
2003@composite cannot mix test code and generation code. If you need that, use
2004|st.data|.
2006If :func:`@composite <hypothesis.strategies.composite>` is used to decorate a
2007method or classmethod, the ``draw`` argument must come before ``self`` or
2008``cls``. While we therefore recommend writing strategies as standalone functions
2009and using |st.register_type_strategy| to associate them with a class, methods
2010are supported and the ``@composite`` decorator may be applied either before or
2011after ``@classmethod`` or ``@staticmethod``. See :issue:`2578` and :pull:`2634`
2012for more details.
2014Examples from this strategy shrink by shrinking the output of each draw call.
2015"""
2016if typing.TYPE_CHECKING or ParamSpec is not None:
2017 P = ParamSpec("P")
2019 def composite(
2020 f: Callable[Concatenate[DrawFn, P], Ex],
2021 ) -> Callable[P, SearchStrategy[Ex]]:
2022 return _composite(f)
2024else: # pragma: no cover
2026 @cacheable
2027 def composite(f: Callable[..., Ex]) -> Callable[..., SearchStrategy[Ex]]:
2028 return _composite(f)
2031composite.__doc__ = composite_doc
2034@defines_strategy(force_reusable_values=True)
2035@cacheable
2036def complex_numbers(
2037 *,
2038 min_magnitude: Real = 0,
2039 max_magnitude: Optional[Real] = None,
2040 allow_infinity: Optional[bool] = None,
2041 allow_nan: Optional[bool] = None,
2042 allow_subnormal: bool = True,
2043 width: Literal[32, 64, 128] = 128,
2044) -> SearchStrategy[complex]:
2045 """Returns a strategy that generates :class:`~python:complex`
2046 numbers.
2048 This strategy draws complex numbers with constrained magnitudes.
2049 The ``min_magnitude`` and ``max_magnitude`` parameters should be
2050 non-negative :class:`~python:numbers.Real` numbers; a value
2051 of ``None`` corresponds an infinite upper bound.
2053 If ``min_magnitude`` is nonzero or ``max_magnitude`` is finite, it
2054 is an error to enable ``allow_nan``. If ``max_magnitude`` is finite,
2055 it is an error to enable ``allow_infinity``.
2057 ``allow_infinity``, ``allow_nan``, and ``allow_subnormal`` are
2058 applied to each part of the complex number separately, as for
2059 :func:`~hypothesis.strategies.floats`.
2061 The magnitude constraints are respected up to a relative error
2062 of (around) floating-point epsilon, due to implementation via
2063 the system ``sqrt`` function.
2065 The ``width`` argument specifies the maximum number of bits of precision
2066 required to represent the entire generated complex number.
2067 Valid values are 32, 64 or 128, which correspond to the real and imaginary
2068 components each having width 16, 32 or 64, respectively.
2069 Passing ``width=64`` will still use the builtin 128-bit
2070 :class:`~python:complex` class, but always for values which can be
2071 exactly represented as two 32-bit floats.
2073 Examples from this strategy shrink by shrinking their real and
2074 imaginary parts, as :func:`~hypothesis.strategies.floats`.
2076 If you need to generate complex numbers with particular real and
2077 imaginary parts or relationships between parts, consider using
2078 :func:`builds(complex, ...) <hypothesis.strategies.builds>` or
2079 :func:`@composite <hypothesis.strategies.composite>` respectively.
2080 """
2081 check_valid_magnitude(min_magnitude, "min_magnitude")
2082 check_valid_magnitude(max_magnitude, "max_magnitude")
2083 check_valid_interval(min_magnitude, max_magnitude, "min_magnitude", "max_magnitude")
2084 if max_magnitude == math.inf:
2085 max_magnitude = None
2087 if allow_infinity is None:
2088 allow_infinity = bool(max_magnitude is None)
2089 elif allow_infinity and max_magnitude is not None:
2090 raise InvalidArgument(f"Cannot have {allow_infinity=} with {max_magnitude=}")
2091 if allow_nan is None:
2092 allow_nan = bool(min_magnitude == 0 and max_magnitude is None)
2093 elif allow_nan and not (min_magnitude == 0 and max_magnitude is None):
2094 raise InvalidArgument(
2095 f"Cannot have {allow_nan=}, {min_magnitude=}, {max_magnitude=}"
2096 )
2097 check_type(bool, allow_subnormal, "allow_subnormal")
2098 if width not in (32, 64, 128):
2099 raise InvalidArgument(
2100 f"{width=}, but must be 32, 64 or 128 (other complex dtypes "
2101 "such as complex192 or complex256 are not supported)"
2102 # For numpy, these types would be supported (but not by CPython):
2103 # https://numpy.org/doc/stable/reference/arrays.scalars.html#complex-floating-point-types
2104 )
2105 component_width = width // 2
2106 allow_kw = {
2107 "allow_nan": allow_nan,
2108 "allow_infinity": allow_infinity,
2109 # If we have a nonzero normal min_magnitude and draw a zero imaginary part,
2110 # then allow_subnormal=True would be an error with the min_value to the floats()
2111 # strategy for the real part. We therefore replace True with None.
2112 "allow_subnormal": None if allow_subnormal else allow_subnormal,
2113 "width": component_width,
2114 }
2116 if min_magnitude == 0 and max_magnitude is None:
2117 # In this simple but common case, there are no constraints on the
2118 # magnitude and therefore no relationship between the real and
2119 # imaginary parts.
2120 return builds(complex, floats(**allow_kw), floats(**allow_kw)) # type: ignore
2122 @composite
2123 def constrained_complex(draw):
2124 # We downcast drawn floats to the desired (component) width so we
2125 # guarantee the resulting complex values are representable. Note
2126 # truncating the mantissa bits with float_of() cannot increase the
2127 # magnitude of a float, so we are guaranteed to stay within the allowed
2128 # range. See https://github.com/HypothesisWorks/hypothesis/issues/3573
2130 # Draw the imaginary part, and determine the maximum real part given
2131 # this and the max_magnitude
2132 if max_magnitude is None:
2133 zi = draw(floats(**allow_kw))
2134 rmax = None
2135 else:
2136 zi = draw(
2137 floats(
2138 -float_of(max_magnitude, component_width),
2139 float_of(max_magnitude, component_width),
2140 **allow_kw,
2141 )
2142 )
2143 rmax = float_of(cathetus(max_magnitude, zi), component_width)
2144 # Draw the real part from the allowed range given the imaginary part
2145 if min_magnitude == 0 or math.fabs(zi) >= min_magnitude:
2146 zr = draw(floats(None if rmax is None else -rmax, rmax, **allow_kw))
2147 else:
2148 rmin = float_of(cathetus(min_magnitude, zi), component_width)
2149 zr = draw(floats(rmin, rmax, **allow_kw))
2150 # Order of conditions carefully tuned so that for a given pair of
2151 # magnitude arguments, we always either draw or do not draw the bool
2152 # (crucial for good shrinking behaviour) but only invert when needed.
2153 if min_magnitude > 0 and draw(booleans()) and math.fabs(zi) <= min_magnitude:
2154 zr = -zr
2155 return complex(zr, zi)
2157 return constrained_complex()
2160@defines_strategy(never_lazy=True)
2161def shared(
2162 base: SearchStrategy[Ex],
2163 *,
2164 key: Optional[Hashable] = None,
2165) -> SearchStrategy[Ex]:
2166 """Returns a strategy that draws a single shared value per run, drawn from
2167 base. Any two shared instances with the same key will share the same value,
2168 otherwise the identity of this strategy will be used. That is:
2170 >>> s = integers() # or any other strategy
2171 >>> x = shared(s)
2172 >>> y = shared(s)
2174 In the above x and y may draw different (or potentially the same) values.
2175 In the following they will always draw the same:
2177 >>> x = shared(s, key="hi")
2178 >>> y = shared(s, key="hi")
2180 Examples from this strategy shrink as per their base strategy.
2181 """
2182 return SharedStrategy(base, key)
2185@composite
2186def _maybe_nil_uuids(draw, uuid):
2187 # Equivalent to `random_uuids | just(...)`, with a stronger bias to the former.
2188 if draw(data()).conjecture_data.draw_boolean(1 / 64):
2189 return UUID("00000000-0000-0000-0000-000000000000")
2190 return uuid
2193@cacheable
2194@defines_strategy(force_reusable_values=True)
2195def uuids(
2196 *, version: Optional[Literal[1, 2, 3, 4, 5]] = None, allow_nil: bool = False
2197) -> SearchStrategy[UUID]:
2198 """Returns a strategy that generates :class:`UUIDs <uuid.UUID>`.
2200 If the optional version argument is given, value is passed through
2201 to :class:`~python:uuid.UUID` and only UUIDs of that version will
2202 be generated.
2204 If ``allow_nil`` is True, generate the nil UUID much more often.
2205 Otherwise, all returned values from this will be unique, so e.g. if you do
2206 ``lists(uuids())`` the resulting list will never contain duplicates.
2208 Examples from this strategy don't have any meaningful shrink order.
2209 """
2210 check_type(bool, allow_nil, "allow_nil")
2211 if version not in (None, 1, 2, 3, 4, 5):
2212 raise InvalidArgument(
2213 f"{version=}, but version must be in "
2214 "(None, 1, 2, 3, 4, 5) to pass to the uuid.UUID constructor."
2215 )
2216 random_uuids = shared(
2217 randoms(use_true_random=True), key="hypothesis.strategies.uuids.generator"
2218 ).map(lambda r: UUID(version=version, int=r.getrandbits(128)))
2220 if allow_nil:
2221 if version is not None:
2222 raise InvalidArgument("The nil UUID is not of any version")
2223 return random_uuids.flatmap(_maybe_nil_uuids)
2224 return random_uuids
2227class RunnerStrategy(SearchStrategy):
2228 def __init__(self, default):
2229 super().__init__()
2230 self.default = default
2232 def do_draw(self, data):
2233 if data.hypothesis_runner is not_set:
2234 if self.default is not_set:
2235 raise InvalidArgument(
2236 "Cannot use runner() strategy with no "
2237 "associated runner or explicit default."
2238 )
2239 return self.default
2240 return data.hypothesis_runner
2243@defines_strategy(force_reusable_values=True)
2244def runner(*, default: Any = not_set) -> SearchStrategy[Any]:
2245 """A strategy for getting "the current test runner", whatever that may be.
2246 The exact meaning depends on the entry point, but it will usually be the
2247 associated 'self' value for it.
2249 If you are using this in a rule for stateful testing, this strategy
2250 will return the instance of the :class:`~hypothesis.stateful.RuleBasedStateMachine`
2251 that the rule is running for.
2253 If there is no current test runner and a default is provided, return
2254 that default. If no default is provided, raises InvalidArgument.
2256 Examples from this strategy do not shrink (because there is only one).
2257 """
2258 return RunnerStrategy(default)
2261class DataObject:
2262 """This type only exists so that you can write type hints for tests using
2263 the :func:`~hypothesis.strategies.data` strategy. Do not use it directly!
2264 """
2266 # Note that "only exists" here really means "is only exported to users",
2267 # but we want to treat it as "semi-stable", not document it as "public API".
2269 def __init__(self, data: ConjectureData) -> None:
2270 self.count = 0
2271 self.conjecture_data = data
2273 __signature__ = Signature() # hide internals from Sphinx introspection
2275 def __repr__(self) -> str:
2276 return "data(...)"
2278 def draw(self, strategy: SearchStrategy[Ex], label: Any = None) -> Ex:
2279 """Like :obj:`~hypothesis.strategies.DrawFn`."""
2280 check_strategy(strategy, "strategy")
2281 self.count += 1
2282 desc = f"Draw {self.count}{'' if label is None else f' ({label})'}"
2283 with deprecate_random_in_strategy("{}from {!r}", desc, strategy):
2284 result = self.conjecture_data.draw(strategy, observe_as=f"generate:{desc}")
2286 # optimization to avoid needless printer.pretty
2287 if should_note():
2288 printer = RepresentationPrinter(context=current_build_context())
2289 printer.text(f"{desc}: ")
2290 if self.conjecture_data.provider.avoid_realization:
2291 printer.text("<symbolic>")
2292 else:
2293 printer.pretty(result)
2294 note(printer.getvalue())
2295 return result
2298class DataStrategy(SearchStrategy):
2299 def do_draw(self, data):
2300 if data._shared_data_strategy is None:
2301 data._shared_data_strategy = DataObject(data)
2302 return data._shared_data_strategy
2304 def __repr__(self) -> str:
2305 return "data()"
2307 def map(self, f):
2308 self.__not_a_first_class_strategy("map")
2310 def filter(self, condition: Callable[[Ex], Any]) -> NoReturn:
2311 self.__not_a_first_class_strategy("filter")
2313 def flatmap(self, f):
2314 self.__not_a_first_class_strategy("flatmap")
2316 def example(self) -> NoReturn:
2317 self.__not_a_first_class_strategy("example")
2319 def __not_a_first_class_strategy(self, name: str) -> NoReturn:
2320 raise InvalidArgument(
2321 f"Cannot call {name} on a DataStrategy. You should probably "
2322 "be using @composite for whatever it is you're trying to do."
2323 )
2326@cacheable
2327@defines_strategy(never_lazy=True)
2328def data() -> SearchStrategy[DataObject]:
2329 """
2330 Provides an object ``data`` with a ``data.draw`` function which acts like
2331 the ``draw`` callable provided by |st.composite|, in that it can be used
2332 to dynamically draw values from strategies. |st.data| is more powerful
2333 than |st.composite|, because it allows you to mix generation and test code.
2335 Here's an example of dynamically generating values using |st.data|:
2337 .. code-block:: python
2339 from hypothesis import strategies as st, given
2341 @given(st.data())
2342 def test_values(data):
2343 n1 = data.draw(st.integers())
2344 n2 = data.draw(st.integers(min_value=n1))
2345 assert n1 + 1 <= n2
2347 If the test fails, each draw will be printed with the falsifying example.
2348 e.g. the above is wrong (it has a boundary condition error), so will print:
2350 .. code-block:: pycon
2352 Falsifying example: test_values(data=data(...))
2353 Draw 1: 0
2354 Draw 2: 0
2356 Optionally, you can provide a label to identify values generated by each call
2357 to ``data.draw()``. These labels can be used to identify values in the
2358 output of a falsifying example.
2360 For instance:
2362 .. code-block:: python
2364 @given(st.data())
2365 def test_draw_sequentially(data):
2366 x = data.draw(st.integers(), label="First number")
2367 y = data.draw(st.integers(min_value=x), label="Second number")
2368 assert x < y
2370 will produce:
2372 .. code-block:: pycon
2374 Falsifying example: test_draw_sequentially(data=data(...))
2375 Draw 1 (First number): 0
2376 Draw 2 (Second number): 0
2378 Examples from this strategy shrink by shrinking the output of each draw call.
2379 """
2380 return DataStrategy()
2383if sys.version_info < (3, 12):
2384 # TypeAliasType is new in 3.12
2385 RegisterTypeT: "TypeAlias" = type[Ex]
2386else: # pragma: no cover # covered by test_mypy.py
2387 from typing import TypeAliasType
2389 # see https://github.com/HypothesisWorks/hypothesis/issues/4410
2390 RegisterTypeT: "TypeAlias" = Union[type[Ex], TypeAliasType]
2393def register_type_strategy(
2394 custom_type: RegisterTypeT,
2395 strategy: Union[SearchStrategy[Ex], Callable[[type[Ex]], SearchStrategy[Ex]]],
2396) -> None:
2397 """Add an entry to the global type-to-strategy lookup.
2399 This lookup is used in :func:`~hypothesis.strategies.builds` and
2400 |@given|.
2402 :func:`~hypothesis.strategies.builds` will be used automatically for
2403 classes with type annotations on ``__init__`` , so you only need to
2404 register a strategy if one or more arguments need to be more tightly
2405 defined than their type-based default, or if you want to supply a strategy
2406 for an argument with a default value.
2408 ``strategy`` may be a search strategy, or a function that takes a type and
2409 returns a strategy (useful for generic types). The function may return
2410 :data:`NotImplemented` to conditionally not provide a strategy for the type
2411 (the type will still be resolved by other methods, if possible, as if the
2412 function was not registered).
2414 Note that you may not register a parametrised generic type (such as
2415 ``MyCollection[int]``) directly, because the resolution logic does not
2416 handle this case correctly. Instead, you may register a *function* for
2417 ``MyCollection`` and `inspect the type parameters within that function
2418 <https://stackoverflow.com/q/48572831>`__.
2419 """
2420 # TODO: We would like to move this to the top level, but pending some major
2421 # refactoring it's hard to do without creating circular imports.
2422 from hypothesis.strategies._internal import types
2424 if not types.is_a_type(custom_type):
2425 raise InvalidArgument(f"{custom_type=} must be a type")
2426 if custom_type in types.NON_RUNTIME_TYPES:
2427 raise InvalidArgument(
2428 f"{custom_type=} is not allowed to be registered, "
2429 f"because there is no such thing as a runtime instance of {custom_type!r}"
2430 )
2431 if not (isinstance(strategy, SearchStrategy) or callable(strategy)):
2432 raise InvalidArgument(
2433 f"{strategy=} must be a SearchStrategy, or a function that takes "
2434 "a generic type and returns a specific SearchStrategy"
2435 )
2436 if isinstance(strategy, SearchStrategy):
2437 with warnings.catch_warnings():
2438 warnings.simplefilter("error", HypothesisSideeffectWarning)
2440 # Calling is_empty forces materialization of lazy strategies. If this is done at import
2441 # time, lazy strategies will warn about it; here, we force that warning to raise to
2442 # avoid the materialization. Ideally, we'd just check if the strategy is lazy, but the
2443 # lazy strategy may be wrapped underneath another strategy so that's complicated.
2444 try:
2445 if strategy.is_empty:
2446 raise InvalidArgument(f"{strategy=} must not be empty")
2447 except HypothesisSideeffectWarning: # pragma: no cover
2448 pass
2449 if types.has_type_arguments(custom_type):
2450 raise InvalidArgument(
2451 f"Cannot register generic type {custom_type!r}, because it has type "
2452 "arguments which would not be handled. Instead, register a function "
2453 f"for {get_origin(custom_type)!r} which can inspect specific type "
2454 "objects and return a strategy."
2455 )
2456 if (
2457 "pydantic.generics" in sys.modules
2458 and issubclass(custom_type, sys.modules["pydantic.generics"].GenericModel)
2459 and not re.search(r"[A-Za-z_]+\[.+\]", repr(custom_type))
2460 and callable(strategy)
2461 ): # pragma: no cover
2462 # See https://github.com/HypothesisWorks/hypothesis/issues/2940
2463 raise InvalidArgument(
2464 f"Cannot register a function for {custom_type!r}, because parametrized "
2465 "`pydantic.generics.GenericModel` subclasses aren't actually generic "
2466 "types at runtime. In this case, you should register a strategy "
2467 "directly for each parametrized form that you anticipate using."
2468 )
2470 types._global_type_lookup[custom_type] = strategy
2471 from_type.__clear_cache() # type: ignore
2474@cacheable
2475@defines_strategy(never_lazy=True)
2476def deferred(definition: Callable[[], SearchStrategy[Ex]]) -> SearchStrategy[Ex]:
2477 """A deferred strategy allows you to write a strategy that references other
2478 strategies that have not yet been defined. This allows for the easy
2479 definition of recursive and mutually recursive strategies.
2481 The definition argument should be a zero-argument function that returns a
2482 strategy. It will be evaluated the first time the strategy is used to
2483 produce an example.
2485 Example usage:
2487 >>> import hypothesis.strategies as st
2488 >>> x = st.deferred(lambda: st.booleans() | st.tuples(x, x))
2489 >>> x.example()
2490 (((False, (True, True)), (False, True)), (True, True))
2491 >>> x.example()
2492 True
2494 Mutual recursion also works fine:
2496 >>> a = st.deferred(lambda: st.booleans() | b)
2497 >>> b = st.deferred(lambda: st.tuples(a, a))
2498 >>> a.example()
2499 True
2500 >>> b.example()
2501 (False, (False, ((False, True), False)))
2503 Examples from this strategy shrink as they normally would from the strategy
2504 returned by the definition.
2505 """
2506 return DeferredStrategy(definition)
2509def domains() -> SearchStrategy[str]:
2510 import hypothesis.provisional
2512 return hypothesis.provisional.domains()
2515@defines_strategy(force_reusable_values=True)
2516def emails(
2517 *, domains: SearchStrategy[str] = LazyStrategy(domains, (), {})
2518) -> SearchStrategy[str]:
2519 """A strategy for generating email addresses as unicode strings. The
2520 address format is specified in :rfc:`5322#section-3.4.1`. Values shrink
2521 towards shorter local-parts and host domains.
2523 If ``domains`` is given then it must be a strategy that generates domain
2524 names for the emails, defaulting to :func:`~hypothesis.provisional.domains`.
2526 This strategy is useful for generating "user data" for tests, as
2527 mishandling of email addresses is a common source of bugs.
2528 """
2529 local_chars = string.ascii_letters + string.digits + "!#$%&'*+-/=^_`{|}~"
2530 local_part = text(local_chars, min_size=1, max_size=64)
2531 # TODO: include dot-atoms, quoted strings, escaped chars, etc in local part
2532 return builds("{}@{}".format, local_part, domains).filter(
2533 lambda addr: len(addr) <= 254
2534 )
2537def _functions(*, like, returns, pure):
2538 # Wrapped up to use ParamSpec below
2539 check_type(bool, pure, "pure")
2540 if not callable(like):
2541 raise InvalidArgument(
2542 "The first argument to functions() must be a callable to imitate, "
2543 f"but got non-callable like={nicerepr(like)!r}"
2544 )
2545 if returns in (None, ...):
2546 # Passing `None` has never been *documented* as working, but it still
2547 # did from May 2020 to Jan 2022 so we'll avoid breaking it without cause.
2548 hints = get_type_hints(like)
2549 returns = from_type(hints.get("return", type(None)))
2550 check_strategy(returns, "returns")
2551 return FunctionStrategy(like, returns, pure)
2554if typing.TYPE_CHECKING or ParamSpec is not None:
2556 @overload
2557 def functions(
2558 *, pure: bool = ...
2559 ) -> SearchStrategy[Callable[[], None]]: # pragma: no cover
2560 ...
2562 @overload
2563 def functions(
2564 *,
2565 like: Callable[P, T],
2566 pure: bool = ...,
2567 ) -> SearchStrategy[Callable[P, T]]: # pragma: no cover
2568 ...
2570 @overload
2571 def functions(
2572 *,
2573 returns: SearchStrategy[T],
2574 pure: bool = ...,
2575 ) -> SearchStrategy[Callable[[], T]]: # pragma: no cover
2576 ...
2578 @overload
2579 def functions(
2580 *,
2581 like: Callable[P, Any],
2582 returns: SearchStrategy[T],
2583 pure: bool = ...,
2584 ) -> SearchStrategy[Callable[P, T]]: # pragma: no cover
2585 ...
2587 @defines_strategy()
2588 def functions(*, like=lambda: None, returns=..., pure=False):
2589 # We shouldn't need overloads here, but mypy disallows default args for
2590 # generics: https://github.com/python/mypy/issues/3737
2591 """functions(*, like=lambda: None, returns=..., pure=False)
2593 A strategy for functions, which can be used in callbacks.
2595 The generated functions will mimic the interface of ``like``, which must
2596 be a callable (including a class, method, or function). The return value
2597 for the function is drawn from the ``returns`` argument, which must be a
2598 strategy. If ``returns`` is not passed, we attempt to infer a strategy
2599 from the return-type annotation if present, falling back to :func:`~none`.
2601 If ``pure=True``, all arguments passed to the generated function must be
2602 hashable, and if passed identical arguments the original return value will
2603 be returned again - *not* regenerated, so beware mutable values.
2605 If ``pure=False``, generated functions do not validate their arguments, and
2606 may return a different value if called again with the same arguments.
2608 Generated functions can only be called within the scope of the ``@given``
2609 which created them.
2610 """
2611 return _functions(like=like, returns=returns, pure=pure)
2613else: # pragma: no cover
2615 @defines_strategy()
2616 def functions(
2617 *,
2618 like: Callable[..., Any] = lambda: None,
2619 returns: Union[SearchStrategy[Any], EllipsisType] = ...,
2620 pure: bool = False,
2621 ) -> SearchStrategy[Callable[..., Any]]:
2622 """functions(*, like=lambda: None, returns=..., pure=False)
2624 A strategy for functions, which can be used in callbacks.
2626 The generated functions will mimic the interface of ``like``, which must
2627 be a callable (including a class, method, or function). The return value
2628 for the function is drawn from the ``returns`` argument, which must be a
2629 strategy. If ``returns`` is not passed, we attempt to infer a strategy
2630 from the return-type annotation if present, falling back to :func:`~none`.
2632 If ``pure=True``, all arguments passed to the generated function must be
2633 hashable, and if passed identical arguments the original return value will
2634 be returned again - *not* regenerated, so beware mutable values.
2636 If ``pure=False``, generated functions do not validate their arguments, and
2637 may return a different value if called again with the same arguments.
2639 Generated functions can only be called within the scope of the ``@given``
2640 which created them.
2641 """
2642 return _functions(like=like, returns=returns, pure=pure)
2645@composite
2646def slices(draw: Any, size: int) -> slice:
2647 """Generates slices that will select indices up to the supplied size
2649 Generated slices will have start and stop indices that range from -size to size - 1
2650 and will step in the appropriate direction. Slices should only produce an empty selection
2651 if the start and end are the same.
2653 Examples from this strategy shrink toward 0 and smaller values
2654 """
2655 check_valid_size(size, "size")
2656 if size == 0:
2657 step = draw(none() | integers().filter(bool))
2658 return slice(None, None, step)
2659 # For slices start is inclusive and stop is exclusive
2660 start = draw(integers(0, size - 1) | none())
2661 stop = draw(integers(0, size) | none())
2663 # Limit step size to be reasonable
2664 if start is None and stop is None:
2665 max_step = size
2666 elif start is None:
2667 max_step = stop
2668 elif stop is None:
2669 max_step = start
2670 else:
2671 max_step = abs(start - stop)
2673 step = draw(integers(1, max_step or 1))
2675 if (draw(booleans()) and start == stop) or (stop or 0) < (start or 0):
2676 step *= -1
2678 if draw(booleans()) and start is not None:
2679 start -= size
2680 if draw(booleans()) and stop is not None:
2681 stop -= size
2682 if (not draw(booleans())) and step == 1:
2683 step = None
2685 return slice(start, stop, step)