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 dataclasses
13import enum
14import math
15import operator
16import random
17import re
18import string
19import sys
20import typing
21import warnings
22from collections.abc import (
23 AsyncGenerator,
24 AsyncIterable,
25 AsyncIterator,
26 Callable,
27 Collection,
28 Generator,
29 Hashable,
30 Iterable,
31 Iterator,
32 Mapping,
33 Sequence,
34)
35from contextvars import ContextVar
36from decimal import Context, Decimal, localcontext
37from fractions import Fraction
38from functools import reduce
39from inspect import (
40 Parameter,
41 Signature,
42 isabstract,
43 isasyncgenfunction,
44 isclass,
45 iscoroutinefunction,
46 isgeneratorfunction,
47)
48from re import Pattern
49from types import EllipsisType, FunctionType, GenericAlias
50from typing import (
51 Annotated,
52 Any,
53 AnyStr,
54 Concatenate,
55 Literal,
56 NewType,
57 NoReturn,
58 ParamSpec,
59 Protocol,
60 TypeAlias,
61 TypeVar,
62 cast,
63 get_args,
64 get_origin,
65 overload,
66)
67from uuid import UUID
69from hypothesis._native.internal.cathetus import cathetus
70from hypothesis.control import (
71 cleanup,
72 current_build_context,
73 deprecate_random_in_strategy,
74 note,
75 should_note,
76)
77from hypothesis.errors import (
78 CannotInvert,
79 HypothesisSideeffectWarning,
80 HypothesisWarning,
81 InvalidArgument,
82 ResolutionFailed,
83 RewindRecursive,
84 SmallSearchSpaceWarning,
85)
86from hypothesis.internal.charmap import (
87 Categories,
88 CategoryName,
89 as_general_categories,
90 categories as all_categories,
91)
92from hypothesis.internal.compat import (
93 add_note,
94 bit_count,
95 ceil,
96 floor,
97 get_type_hints,
98 is_typed_named_tuple,
99)
100from hypothesis.internal.conjecture.choice import ChoiceT
101from hypothesis.internal.conjecture.data import ConjectureData
102from hypothesis.internal.conjecture.junkdrawer import equal_values
103from hypothesis.internal.conjecture.utils import (
104 calc_label_from_callable,
105 calc_label_from_name,
106 check_sample,
107 combine_labels,
108 fisher_yates_shuffle,
109 identity,
110)
111from hypothesis.internal.entropy import get_seeder_and_restorer
112from hypothesis.internal.floats import float_of
113from hypothesis.internal.reflection import (
114 define_function_signature,
115 get_pretty_function_description,
116 get_signature,
117 is_first_param_referenced_in_function,
118 nicerepr,
119 repr_call,
120 required_args,
121)
122from hypothesis.internal.validation import (
123 check_type,
124 check_valid_integer,
125 check_valid_interval,
126 check_valid_magnitude,
127 check_valid_size,
128 check_valid_sizes,
129 try_convert,
130)
131from hypothesis.strategies._internal import SearchStrategy, check_strategy
132from hypothesis.strategies._internal.collections import (
133 FixedDictStrategy,
134 ListStrategy,
135 TupleStrategy,
136 UniqueListStrategy,
137 UniqueSampledListStrategy,
138 tuples,
139)
140from hypothesis.strategies._internal.deferred import DeferredStrategy
141from hypothesis.strategies._internal.functions import FunctionStrategy
142from hypothesis.strategies._internal.lazy import LazyStrategy, unwrap_strategies
143from hypothesis.strategies._internal.misc import BooleansStrategy, just, none, nothing
144from hypothesis.strategies._internal.numbers import (
145 IntegersStrategy,
146 Real,
147 floats,
148 integers,
149)
150from hypothesis.strategies._internal.recursive import RecursiveStrategy
151from hypothesis.strategies._internal.shared import SharedStrategy
152from hypothesis.strategies._internal.strategies import (
153 Ex,
154 SampledFromStrategy,
155 T,
156 one_of,
157)
158from hypothesis.strategies._internal.strings import (
159 BytesStrategy,
160 OneCharStringStrategy,
161 TextStrategy,
162 _check_is_single_character,
163)
164from hypothesis.strategies._internal.utils import cacheable, defines_strategy
165from hypothesis.utils.conventions import not_set
166from hypothesis.utils.deprecation import note_deprecation
167from hypothesis.vendor.pretty import ArgLabelsT, RepresentationPrinter
170@cacheable
171@defines_strategy(force_reusable_values=True)
172def booleans() -> SearchStrategy[bool]:
173 """Returns a strategy which generates instances of :class:`python:bool`.
175 Examples from this strategy will shrink towards ``False`` (i.e.
176 shrinking will replace ``True`` with ``False`` where possible).
177 """
178 return BooleansStrategy()
181@overload
182def sampled_from(elements: Sequence[T]) -> SearchStrategy[T]: ...
185@overload
186def sampled_from(elements: type[enum.Enum]) -> SearchStrategy[Any]:
187 # `SearchStrategy[Enum]` is unreliable due to metaclass issues.
188 ...
191@overload
192def sampled_from(
193 elements: type[enum.Enum] | Sequence[Any],
194) -> SearchStrategy[Any]: ...
197@defines_strategy(eager="try")
198def sampled_from(
199 elements: type[enum.Enum] | Sequence[Any],
200) -> SearchStrategy[Any]:
201 """Returns a strategy which generates any value present in ``elements``.
203 Note that as with :func:`~hypothesis.strategies.just`, values will not be
204 copied and thus you should be careful of using mutable data.
206 ``sampled_from`` supports ordered collections, as well as
207 :class:`~python:enum.Enum` objects. :class:`~python:enum.Flag` objects
208 may also generate any combination of their members.
210 Examples from this strategy shrink by replacing them with values earlier in
211 the list. So e.g. ``sampled_from([10, 1])`` will shrink by trying to replace
212 1 values with 10, and ``sampled_from([1, 10])`` will shrink by trying to
213 replace 10 values with 1.
215 It is an error to sample from an empty sequence, because returning :func:`nothing`
216 makes it too easy to silently drop parts of compound strategies. If you need
217 that behaviour, use ``sampled_from(seq) if seq else nothing()``.
218 """
219 values = check_sample(elements, "sampled_from")
220 force_repr = None
221 # check_sample converts to tuple unconditionally, but we want to preserve
222 # square braces for list reprs.
223 # This will not cover custom sequence implementations which return different
224 # braces (or other, more unusual things) for their reprs, but this is a tradeoff
225 # between repr accuracy and greedily-evaluating all sequence reprs (at great
226 # cost for large sequences).
227 force_repr_braces = ("[", "]") if isinstance(elements, list) else None
228 if isinstance(elements, type) and issubclass(elements, enum.Enum):
229 force_repr = f"sampled_from({elements.__module__}.{elements.__name__})"
231 if isclass(elements) and issubclass(elements, enum.Flag):
232 # Combinations of enum.Flag members (including empty) are also members. We generate these
233 # dynamically, because static allocation takes O(2^n) memory. LazyStrategy is used for the
234 # ease of force_repr.
235 # Add all named values, both flag bits (== list(elements)) and aliases. The aliases are
236 # necessary for full coverage for flags that would fail enum.NAMED_FLAGS check, and they
237 # are also nice values to shrink to.
238 flags = sorted(
239 set(elements.__members__.values()),
240 key=lambda v: (bit_count(v.value), v.value),
241 )
242 # Finally, try to construct the empty state if it is not named. It's placed at the
243 # end so that we shrink to named values.
244 flags_with_empty = flags
245 if not flags or flags[0].value != 0:
246 try:
247 flags_with_empty = [*flags, elements(0)]
248 except TypeError: # pragma: no cover
249 # Happens on some python versions (at least 3.12) when there are no named values
250 pass
251 inner = [
252 # Consider one or no named flags set, with shrink-to-named-flag behaviour.
253 # Special cases (length zero or one) are handled by the inner sampled_from.
254 sampled_from(flags_with_empty),
255 ]
256 if len(flags) > 1:
257 inner += [
258 # Uniform distribution over number of named flags or combinations set. The overlap
259 # at r=1 is intentional, it may lead to oversampling but gives consistent shrinking
260 # behaviour.
261 integers(min_value=1, max_value=len(flags))
262 .flatmap(lambda r: sets(sampled_from(flags), min_size=r, max_size=r))
263 .map(lambda s: elements(reduce(operator.or_, s))),
264 ]
265 return LazyStrategy(one_of, args=inner, kwargs={}, force_repr=force_repr)
266 if not values:
268 def has_annotations(elements):
269 if sys.version_info[:2] < (3, 14):
270 return vars(elements).get("__annotations__")
271 else:
272 import annotationlib
274 return bool(annotationlib.get_annotations(elements))
276 if (
277 isinstance(elements, type)
278 and issubclass(elements, enum.Enum)
279 and has_annotations(elements)
280 ):
281 # See https://github.com/HypothesisWorks/hypothesis/issues/2923
282 raise InvalidArgument(
283 f"Cannot sample from {elements.__module__}.{elements.__name__} "
284 "because it contains no elements. It does however have annotations, "
285 "so maybe you tried to write an enum as if it was a dataclass?"
286 )
287 raise InvalidArgument("Cannot sample from a length-zero sequence.")
288 if len(values) == 1:
289 return just(values[0])
290 return SampledFromStrategy(
291 values, force_repr=force_repr, force_repr_braces=force_repr_braces
292 )
295def _gets_first_item(fn: Callable) -> bool:
296 # Introspection for either `itemgetter(0)`, or `lambda x: x[0]`
297 if isinstance(fn, FunctionType):
298 s = get_pretty_function_description(fn)
299 return bool(re.fullmatch(s, r"lambda ([a-z]+): \1\[0\]"))
300 return isinstance(fn, operator.itemgetter) and repr(fn) == "operator.itemgetter(0)"
303@cacheable
304@defines_strategy()
305def lists(
306 elements: SearchStrategy[Ex],
307 *,
308 min_size: int = 0,
309 max_size: int | None = None,
310 unique_by: (
311 Callable[[Ex], Hashable] | tuple[Callable[[Ex], Hashable], ...] | None
312 ) = None,
313 unique: bool = False,
314) -> SearchStrategy[list[Ex]]:
315 """Returns a list containing values drawn from elements with length in the
316 interval [min_size, max_size] (no bounds in that direction if these are
317 None). If max_size is 0, only the empty list will be drawn.
319 If ``unique`` is True (or something that evaluates to True), we compare direct
320 object equality, as if unique_by was ``lambda x: x``. This comparison only
321 works for hashable types.
323 If ``unique_by`` is not None it must be a callable or tuple of callables
324 returning a hashable type when given a value drawn from elements. The
325 resulting list will satisfy the condition that for ``i`` != ``j``,
326 ``unique_by(result[i])`` != ``unique_by(result[j])``.
328 If ``unique_by`` is a tuple of callables the uniqueness will be respective
329 to each callable.
331 For example, the following will produce two columns of integers with both
332 columns being unique respectively.
334 .. code-block:: pycon
336 >>> twoints = st.tuples(st.integers(), st.integers())
337 >>> st.lists(twoints, unique_by=(lambda x: x[0], lambda x: x[1]))
339 Examples from this strategy shrink by trying to remove elements from the
340 list, and by shrinking each individual element of the list.
341 """
342 check_valid_sizes(min_size, max_size)
343 check_strategy(elements, "elements")
344 if unique:
345 if unique_by is not None:
346 raise InvalidArgument(
347 "cannot specify both unique and unique_by "
348 "(you probably only want to set unique_by)"
349 )
350 else:
351 unique_by = identity
353 if max_size == 0:
354 return builds(list)
355 if unique_by is not None:
356 if not (callable(unique_by) or isinstance(unique_by, tuple)):
357 raise InvalidArgument(
358 f"{unique_by=} is not a callable or tuple of callables"
359 )
360 if callable(unique_by):
361 unique_by = (unique_by,)
362 if len(unique_by) == 0:
363 raise InvalidArgument("unique_by is empty")
364 for i, f in enumerate(unique_by):
365 if not callable(f):
366 raise InvalidArgument(f"unique_by[{i}]={f!r} is not a callable")
367 # Note that lazy strategies automatically unwrap when passed to a defines_strategy
368 # function.
369 tuple_suffixes = None
370 if (
371 # We're generating a list of tuples unique by the first element, perhaps
372 # via st.dictionaries(), and this will be more efficient if we rearrange
373 # our strategy somewhat to draw the first element then draw add the rest.
374 isinstance(elements, TupleStrategy)
375 and len(elements.element_strategies) >= 1
376 and all(_gets_first_item(fn) for fn in unique_by)
377 ):
378 unique_by = (identity,)
379 tuple_suffixes = TupleStrategy(elements.element_strategies[1:])
380 elements = elements.element_strategies[0]
382 # UniqueSampledListStrategy offers a substantial performance improvement for
383 # unique arrays with few possible elements, e.g. of eight-bit integer types.
384 if (
385 isinstance(elements, IntegersStrategy)
386 and elements.start is not None
387 and elements.end is not None
388 and (elements.end - elements.start) <= 255
389 ):
390 elements = SampledFromStrategy(
391 sorted(range(elements.start, elements.end + 1), key=abs)
392 if elements.end < 0 or elements.start > 0
393 else (
394 list(range(elements.end + 1))
395 + list(range(-1, elements.start - 1, -1))
396 )
397 )
399 if isinstance(elements, SampledFromStrategy):
400 element_count = len(elements.elements)
401 if min_size > element_count:
402 raise InvalidArgument(
403 f"Cannot create a collection of {min_size=} unique "
404 f"elements with values drawn from only {element_count} distinct "
405 "elements"
406 )
408 if max_size is not None:
409 max_size = min(max_size, element_count)
410 else:
411 max_size = element_count
413 return UniqueSampledListStrategy(
414 elements=elements,
415 max_size=max_size,
416 min_size=min_size,
417 keys=unique_by,
418 tuple_suffixes=tuple_suffixes,
419 )
421 return UniqueListStrategy(
422 elements=elements,
423 max_size=max_size,
424 min_size=min_size,
425 keys=unique_by,
426 tuple_suffixes=tuple_suffixes,
427 )
428 return ListStrategy(elements, min_size=min_size, max_size=max_size)
431@cacheable
432@defines_strategy()
433def sets(
434 elements: SearchStrategy[Ex],
435 *,
436 min_size: int = 0,
437 max_size: int | None = None,
438) -> SearchStrategy[set[Ex]]:
439 """This has the same behaviour as lists, but returns sets instead.
441 Note that Hypothesis cannot tell if values are drawn from elements
442 are hashable until running the test, so you can define a strategy
443 for sets of an unhashable type but it will fail at test time.
445 Examples from this strategy shrink by trying to remove elements from the
446 set, and by shrinking each individual element of the set.
447 """
448 return lists(
449 elements=elements, min_size=min_size, max_size=max_size, unique=True
450 ).map(set)
453@cacheable
454@defines_strategy()
455def frozensets(
456 elements: SearchStrategy[Ex],
457 *,
458 min_size: int = 0,
459 max_size: int | None = None,
460) -> SearchStrategy[frozenset[Ex]]:
461 """This is identical to the sets function but instead returns
462 frozensets."""
463 return lists(
464 elements=elements, min_size=min_size, max_size=max_size, unique=True
465 ).map(frozenset)
468class PrettyIter:
469 def __init__(self, values):
470 self._values = values
471 self._iter = iter(self._values)
473 def __iter__(self):
474 return self._iter
476 def __next__(self):
477 return next(self._iter)
479 def __repr__(self) -> str:
480 return f"iter({self._values!r})"
482 def _repr_pretty_(self, printer, cycle):
483 if cycle:
484 printer.text("iter(...)")
485 else:
486 printer.text("iter(")
487 printer.pretty(self._values)
488 printer.text(")")
491@defines_strategy()
492def iterables(
493 elements: SearchStrategy[Ex],
494 *,
495 min_size: int = 0,
496 max_size: int | None = None,
497 unique_by: (
498 Callable[[Ex], Hashable] | tuple[Callable[[Ex], Hashable], ...] | None
499 ) = None,
500 unique: bool = False,
501) -> SearchStrategy[Iterable[Ex]]:
502 """This has the same behaviour as lists, but returns iterables instead.
504 Some iterables cannot be indexed (e.g. sets) and some do not have a
505 fixed length (e.g. generators). This strategy produces iterators,
506 which cannot be indexed and do not have a fixed length. This ensures
507 that you do not accidentally depend on sequence behaviour.
508 """
509 return lists(
510 elements=elements,
511 min_size=min_size,
512 max_size=max_size,
513 unique_by=unique_by,
514 unique=unique,
515 ).map(PrettyIter)
518# fixed_dictionaries accepts Mapping rather than the invariant dict so that
519# type-checkers can infer the value type even when the per-key strategies are
520# heterogeneous: Mapping is covariant in its value type and SearchStrategy is
521# covariant in its own, so e.g. `SearchStrategy[int] | SearchStrategy[str]` is
522# accepted as `SearchStrategy[int | str]`. The overloads let mapping and
523# optional contribute independent key and value types, which are unioned in the
524# result. See revealed_types.py for the resulting types.
525#
526# We use fresh typevars rather than the module-level Ex because Ex has a default
527# (PEP 696), and a defaulted typevar may not precede a bare one in a signature.
528#
529# The remaining imprecision is that we always report a plain dict, even though
530# at runtime the result preserves the concrete (dict-subclass) type of mapping.
531K = TypeVar("K")
532V = TypeVar("V")
533K2 = TypeVar("K2")
534V2 = TypeVar("V2")
537@overload
538def fixed_dictionaries(
539 mapping: Mapping[K, SearchStrategy[V]],
540) -> SearchStrategy[dict[K, V]]: ...
543@overload
544def fixed_dictionaries(
545 # Matching an empty mapping against NoReturn lets the result come solely
546 # from optional, rather than picking up a spurious `Any` from the empty
547 # mapping (whose key and value types are otherwise uninferable).
548 mapping: Mapping[NoReturn, NoReturn],
549 *,
550 optional: Mapping[K2, SearchStrategy[V2]],
551) -> SearchStrategy[dict[K2, V2]]: ...
554@overload
555def fixed_dictionaries(
556 mapping: Mapping[K, SearchStrategy[V]],
557 *,
558 optional: Mapping[K2, SearchStrategy[V2]],
559) -> SearchStrategy[dict[K | K2, V | V2]]: ...
562@defines_strategy()
563def fixed_dictionaries(
564 mapping: Mapping[Any, SearchStrategy[Any]],
565 *,
566 optional: Mapping[Any, SearchStrategy[Any]] | None = None,
567) -> SearchStrategy[dict[Any, Any]]:
568 """Generates a dictionary of the same type as mapping with a fixed set of
569 keys mapping to strategies. ``mapping`` must be a dict subclass.
571 Generated values have all keys present in mapping, in iteration order,
572 with the corresponding values drawn from mapping[key].
574 If ``optional`` is passed, the generated value *may or may not* contain each
575 key from ``optional`` and a value drawn from the corresponding strategy.
576 Generated values may contain optional keys in an arbitrary order.
578 Examples from this strategy shrink by shrinking each individual value in
579 the generated dictionary, and omitting optional key-value pairs.
580 """
581 check_type(Mapping, mapping, "mapping")
582 for k, v in mapping.items():
583 check_strategy(v, f"mapping[{k!r}]")
585 if optional is not None:
586 check_type(Mapping, optional, "optional")
587 for k, v in optional.items():
588 check_strategy(v, f"optional[{k!r}]")
589 if type(mapping) != type(optional):
590 raise InvalidArgument(
591 f"Got arguments of different types: "
592 f"mapping={nicerepr(type(mapping))}, "
593 f"optional={nicerepr(type(optional))}"
594 )
595 if set(mapping) & set(optional):
596 raise InvalidArgument(
597 "The following keys were in both mapping and optional, "
598 f"which is invalid: {set(mapping) & set(optional)!r}"
599 )
601 # FixedDictStrategy honestly types itself as SearchStrategy[Mapping], since
602 # type(mapping)(pairs) may return any Mapping subclass. We narrow to dict
603 # here because that's what callers almost always get and find convenient.
604 return cast(
605 "SearchStrategy[dict[Any, Any]]",
606 FixedDictStrategy(mapping, optional=optional),
607 )
610_get_first_item = operator.itemgetter(0)
613@cacheable
614@defines_strategy()
615def dictionaries(
616 keys: SearchStrategy[Ex],
617 values: SearchStrategy[T],
618 *,
619 dict_class: type = dict,
620 min_size: int = 0,
621 max_size: int | None = None,
622) -> SearchStrategy[dict[Ex, T]]:
623 # Describing the exact dict_class to Mypy drops the key and value types,
624 # so we report Dict[K, V] instead of Mapping[Any, Any] for now. Sorry!
625 """Generates dictionaries of type ``dict_class`` with keys drawn from the ``keys``
626 argument and values drawn from the ``values`` argument.
628 The size parameters have the same interpretation as for
629 :func:`~hypothesis.strategies.lists`.
631 Examples from this strategy shrink by trying to remove keys from the
632 generated dictionary, and by shrinking each generated key and value.
633 """
634 check_valid_sizes(min_size, max_size)
635 if max_size == 0:
636 return fixed_dictionaries(dict_class())
637 check_strategy(keys, "keys")
638 check_strategy(values, "values")
640 return lists(
641 tuples(keys, values),
642 min_size=min_size,
643 max_size=max_size,
644 unique_by=_get_first_item,
645 ).map(dict_class)
648@cacheable
649@defines_strategy(force_reusable_values=True)
650def characters(
651 *,
652 codec: str | None = None,
653 min_codepoint: int | None = None,
654 max_codepoint: int | None = None,
655 categories: Collection[CategoryName] | None = None,
656 exclude_categories: Collection[CategoryName] | None = None,
657 exclude_characters: Collection[str] | None = None,
658 include_characters: Collection[str] | None = None,
659 # Note: these arguments are deprecated aliases for backwards compatibility
660 blacklist_categories: Collection[CategoryName] | None = None,
661 whitelist_categories: Collection[CategoryName] | None = None,
662 blacklist_characters: Collection[str] | None = None,
663 whitelist_characters: Collection[str] | None = None,
664) -> SearchStrategy[str]:
665 r"""Generates characters, length-one :class:`python:str`\ ings,
666 following specified filtering rules.
668 - When no filtering rules are specified, any character can be produced.
669 - If ``min_codepoint`` or ``max_codepoint`` is specified, then only
670 characters having a codepoint in that range will be produced.
671 - If ``categories`` is specified, then only characters from those
672 Unicode categories will be produced. This is a further restriction,
673 characters must also satisfy ``min_codepoint`` and ``max_codepoint``.
674 - If ``exclude_categories`` is specified, then any character from those
675 categories will not be produced. You must not pass both ``categories``
676 and ``exclude_categories``; these arguments are alternative ways to
677 specify exactly the same thing.
678 - If ``include_characters`` is specified, then any additional characters
679 in that list will also be produced.
680 - If ``exclude_characters`` is specified, then any characters in
681 that list will be not be produced. Any overlap between
682 ``include_characters`` and ``exclude_characters`` will raise an
683 exception.
684 - If ``codec`` is specified, only characters in the specified `codec encodings`_
685 will be produced.
687 The ``_codepoint`` arguments must be integers between zero and
688 :obj:`python:sys.maxunicode`. The ``_characters`` arguments must be
689 collections of length-one unicode strings, such as a unicode string.
691 The ``_categories`` arguments must be used to specify either the
692 one-letter Unicode major category or the two-letter Unicode
693 `general category`_. For example, ``('Nd', 'Lu')`` signifies "Number,
694 decimal digit" and "Letter, uppercase". A single letter ('major category')
695 can be given to match all corresponding categories, for example ``'P'``
696 for characters in any punctuation category.
698 We allow codecs from the :mod:`codecs` module and their aliases, platform
699 specific and user-registered codecs if they are available, and
700 `python-specific text encodings`_ (but not text or binary transforms).
701 ``include_characters`` which cannot be encoded using this codec will
702 raise an exception. If non-encodable codepoints or categories are
703 explicitly allowed, the ``codec`` argument will exclude them without
704 raising an exception. A few legacy codecs have characters which encode
705 successfully but do not decode back to the same character - for example
706 the yen sign becomes a backslash under ``shift_jis`` - and if any could
707 be generated we issue
708 :class:`~hypothesis.errors.NonRoundTrippableCharactersWarning`. Pass
709 each of them in either ``include_characters``, to generate them without
710 the warning, or ``exclude_characters``, to generate only characters
711 which round-trip.
713 .. _general category: https://en.wikipedia.org/wiki/Unicode_character_property
714 .. _codec encodings: https://docs.python.org/3/library/codecs.html#encodings-and-unicode
715 .. _python-specific text encodings: https://docs.python.org/3/library/codecs.html#python-specific-encodings
717 Examples from this strategy shrink towards the codepoint for ``'0'``,
718 or the first allowable codepoint after it if ``'0'`` is excluded.
719 """
720 check_valid_size(min_codepoint, "min_codepoint")
721 check_valid_size(max_codepoint, "max_codepoint")
722 check_valid_interval(min_codepoint, max_codepoint, "min_codepoint", "max_codepoint")
723 categories = cast(Categories | None, categories)
724 if categories is not None and exclude_categories is not None:
725 raise InvalidArgument(
726 f"Pass at most one of {categories=} and {exclude_categories=} - "
727 "these arguments both specify which categories are allowed, so it "
728 "doesn't make sense to use both in a single call."
729 )
731 # Handle deprecation of whitelist/blacklist arguments
732 has_old_arg = any(v is not None for k, v in locals().items() if "list" in k)
733 has_new_arg = any(v is not None for k, v in locals().items() if "lude" in k)
734 if has_old_arg and has_new_arg:
735 raise InvalidArgument(
736 "The deprecated blacklist/whitelist arguments cannot be used in "
737 "the same call as their replacement include/exclude arguments."
738 )
739 if blacklist_categories is not None:
740 exclude_categories = blacklist_categories
741 if whitelist_categories is not None:
742 categories = whitelist_categories
743 if blacklist_characters is not None:
744 exclude_characters = blacklist_characters
745 if whitelist_characters is not None:
746 include_characters = whitelist_characters
748 if (
749 min_codepoint is None
750 and max_codepoint is None
751 and categories is None
752 and exclude_categories is None
753 and include_characters is not None
754 and codec is None
755 ):
756 raise InvalidArgument(
757 "Nothing is excluded by other arguments, so passing only "
758 f"{include_characters=} would have no effect. "
759 "Also pass categories=(), or use "
760 f"sampled_from({include_characters!r}) instead."
761 )
762 exclude_characters = exclude_characters or ""
763 include_characters = include_characters or ""
764 if not_one_char := [c for c in exclude_characters if len(c) != 1]:
765 raise InvalidArgument(
766 "Elements of exclude_characters are required to be a single character, "
767 f"but {not_one_char!r} passed in {exclude_characters=} was not."
768 )
769 if not_one_char := [c for c in include_characters if len(c) != 1]:
770 raise InvalidArgument(
771 "Elements of include_characters are required to be a single character, "
772 f"but {not_one_char!r} passed in {include_characters=} was not."
773 )
774 overlap = set(exclude_characters).intersection(include_characters)
775 if overlap:
776 raise InvalidArgument(
777 f"Characters {sorted(overlap)!r} are present in both "
778 f"{include_characters=} and {exclude_characters=}"
779 )
780 if categories is not None:
781 categories = as_general_categories(categories, "categories")
782 if exclude_categories is not None:
783 exclude_categories = as_general_categories(
784 exclude_categories, "exclude_categories"
785 )
786 if categories is not None and not categories and not include_characters:
787 raise InvalidArgument(
788 "When `categories` is an empty collection and there are "
789 "no characters specified in include_characters, nothing can "
790 "be generated by the characters() strategy."
791 )
792 both_cats = set(exclude_categories or ()).intersection(categories or ())
793 if both_cats:
794 # Note: we check that exactly one of `categories` or `exclude_categories` is
795 # passed above, but retain this older check for the deprecated arguments.
796 raise InvalidArgument(
797 f"Categories {sorted(both_cats)!r} are present in both "
798 f"{categories=} and {exclude_categories=}"
799 )
800 elif exclude_categories is not None:
801 categories = set(all_categories()) - set(exclude_categories)
802 del exclude_categories
804 if codec is not None:
805 try:
806 codec = codecs.lookup(codec).name
807 # Check this is not a str-to-str or bytes-to-bytes codec; see
808 # https://docs.python.org/3/library/codecs.html#binary-transforms
809 "".encode(codec)
810 except LookupError:
811 raise InvalidArgument(f"{codec=} is not valid on this system") from None
812 except Exception:
813 raise InvalidArgument(f"{codec=} is not a valid codec") from None
815 for char in include_characters:
816 try:
817 char.encode(encoding=codec, errors="strict")
818 except UnicodeEncodeError:
819 raise InvalidArgument(
820 f"Character {char!r} in {include_characters=} "
821 f"cannot be encoded with {codec=}"
822 ) from None
824 # ascii and utf-8 are sufficient common that we have faster special handling
825 if codec == "ascii":
826 if (max_codepoint is None) or (max_codepoint > 127):
827 max_codepoint = 127
828 codec = None
829 elif codec == "utf-8":
830 if categories is None:
831 categories = all_categories()
832 categories = tuple(c for c in categories if c != "Cs")
834 return OneCharStringStrategy.from_characters_args(
835 categories=categories,
836 exclude_characters=exclude_characters,
837 min_codepoint=min_codepoint,
838 max_codepoint=max_codepoint,
839 include_characters=include_characters,
840 codec=codec,
841 )
844# Hide the deprecated aliases from documentation and casual inspection
845characters.__signature__ = (__sig := get_signature(characters)).replace( # type: ignore
846 parameters=[p for p in __sig.parameters.values() if "list" not in p.name]
847)
850@cacheable
851@defines_strategy(force_reusable_values=True)
852def text(
853 alphabet: Collection[str] | SearchStrategy[str] = characters(codec="utf-8"),
854 *,
855 min_size: int = 0,
856 max_size: int | None = None,
857) -> SearchStrategy[str]:
858 """Generates strings with characters drawn from ``alphabet``, which should
859 be a collection of length one strings or a strategy generating such strings.
861 The default alphabet strategy can generate the full unicode range but
862 excludes surrogate characters because they are invalid in the UTF-8
863 encoding. You can use :func:`~hypothesis.strategies.characters` without
864 arguments to find surrogate-related bugs such as :bpo:`34454`.
866 ``min_size`` and ``max_size`` have the usual interpretations.
867 Note that Python measures string length by counting codepoints: U+00C5
868 ``Å`` is a single character, while U+0041 U+030A ``Å`` is two - the ``A``,
869 and a combining ring above.
871 Examples from this strategy shrink towards shorter strings, and with the
872 characters in the text shrinking as per the alphabet strategy.
873 This strategy does not :func:`~python:unicodedata.normalize` examples,
874 so generated strings may be in any or none of the 'normal forms'.
875 """
876 check_valid_sizes(min_size, max_size)
877 check_type((Collection, SearchStrategy), alphabet, "alphabet")
879 char_strategy: SearchStrategy[str] | None
880 if not isinstance(alphabet, SearchStrategy) and not alphabet:
881 char_strategy = nothing()
882 else:
883 char_strategy = OneCharStringStrategy.from_alphabet(alphabet)
884 if char_strategy is None:
885 # a strategy which cannot be statically resolved to a fixed set of
886 # characters; check each character as it is drawn instead.
887 assert isinstance(alphabet, SearchStrategy)
888 char_strategy = unwrap_strategies(alphabet).map(_check_is_single_character)
889 if (max_size == 0 or char_strategy.is_empty) and not min_size:
890 return just("")
891 # mypy is unhappy with ListStrategy(SearchStrategy[list[Ex]]) and then TextStrategy
892 # setting Ex = str. Mypy is correct to complain because we have an LSP violation
893 # here in the TextStrategy.do_draw override. Would need refactoring to resolve.
894 return TextStrategy(char_strategy, min_size=min_size, max_size=max_size) # type: ignore
897@overload
898def from_regex(
899 regex: bytes | Pattern[bytes],
900 *,
901 fullmatch: bool = False,
902) -> SearchStrategy[bytes]: ...
905@overload
906def from_regex(
907 regex: str | Pattern[str],
908 *,
909 fullmatch: bool = False,
910 alphabet: Collection[str] | SearchStrategy[str] | None = characters(codec="utf-8"),
911) -> SearchStrategy[str]: ...
914@cacheable
915@defines_strategy()
916def from_regex(
917 regex: AnyStr | Pattern[AnyStr],
918 *,
919 fullmatch: bool = False,
920 alphabet: Collection[str] | SearchStrategy[str] | None = None,
921) -> SearchStrategy[AnyStr]:
922 r"""Generates strings that contain a match for the given regex (i.e. ones
923 for which :func:`python:re.search` will return a non-None result).
925 ``regex`` may be a pattern or :func:`compiled regex <python:re.compile>`.
926 Both byte-strings and unicode strings are supported, and will generate
927 examples of the same type.
929 You can use regex flags such as :obj:`python:re.IGNORECASE` or
930 :obj:`python:re.DOTALL` to control generation. Flags can be passed either
931 in compiled regex or inside the pattern with a ``(?iLmsux)`` group.
933 Some regular expressions are only partly supported - the underlying
934 strategy checks local matching and relies on filtering to resolve
935 context-dependent expressions. Using too many of these constructs may
936 cause health-check errors as too many examples are filtered out. This
937 mainly includes (positive or negative) lookahead and lookbehind groups.
939 If you want the generated string to match the whole regex you should use
940 boundary markers. So e.g. ``r"\A.\Z"`` will return a single character
941 string, while ``"."`` will return any string, and ``r"\A.$"`` will return
942 a single character optionally followed by a ``"\n"``.
943 Alternatively, passing ``fullmatch=True`` will ensure that the whole
944 string is a match, as if you had used the ``\A`` and ``\Z`` markers.
946 The ``alphabet=`` argument may be a collection of length one strings or a strategy
947 generating such strings. ``alphabet`` constrains the characters in the generated
948 string, as for :func:`text`, and is only supported for unicode strings. If a
949 strategy is passed to ``alphabet=``, it must resolve to a fixed set of characters;
950 for example, by being a |st.characters|, |st.sampled_from|, or a |st.one_of| union
951 of such strategies.
953 Examples from this strategy shrink towards shorter strings and lower
954 character values, with exact behaviour that may depend on the pattern.
955 """
956 check_type((str, bytes, re.Pattern), regex, "regex")
957 check_type(bool, fullmatch, "fullmatch")
959 pattern = regex.pattern if isinstance(regex, re.Pattern) else regex
960 if alphabet is not None:
961 check_type((Collection, SearchStrategy), alphabet, "alphabet")
962 if not isinstance(pattern, str):
963 raise InvalidArgument("alphabet= is not supported for bytestrings")
964 resolved = OneCharStringStrategy.from_alphabet(alphabet)
965 if resolved is None:
966 raise InvalidArgument(
967 f"{alphabet=} must be a collection of characters, or a "
968 "sampled_from() or characters() strategy"
969 )
970 alphabet = resolved
971 elif isinstance(pattern, str):
972 alphabet = characters(codec="utf-8")
974 # TODO: We would like to move this to the top level, but pending some major
975 # refactoring it's hard to do without creating circular imports.
976 from hypothesis.strategies._internal.regex import regex_strategy
978 return regex_strategy(regex, fullmatch, alphabet=alphabet)
981@cacheable
982@defines_strategy(force_reusable_values=True)
983def binary(
984 *,
985 min_size: int = 0,
986 max_size: int | None = None,
987) -> SearchStrategy[bytes]:
988 """Generates :class:`python:bytes`.
990 The generated :class:`python:bytes` will have a length of at least ``min_size``
991 and at most ``max_size``. If ``max_size`` is None there is no upper limit.
993 Examples from this strategy shrink towards smaller strings and lower byte
994 values.
995 """
996 check_valid_sizes(min_size, max_size)
997 return BytesStrategy(min_size, max_size)
1000@cacheable
1001@defines_strategy()
1002def randoms(
1003 *,
1004 note_method_calls: bool = False,
1005 use_true_random: bool = False,
1006) -> SearchStrategy[random.Random]:
1007 """Generates instances of ``random.Random``. The generated Random instances
1008 are of a special HypothesisRandom subclass.
1010 - If ``note_method_calls`` is set to ``True``, Hypothesis will print the
1011 randomly drawn values in the |minimal failing test case|. This can be helpful
1012 for debugging the behaviour of randomized algorithms.
1013 - If ``use_true_random`` is set to ``True`` then values will be drawn from
1014 their usual distribution, otherwise they will actually be Hypothesis
1015 generated values (and will be shrunk accordingly for any failing test
1016 case). Setting ``use_true_random=False`` will tend to expose bugs that
1017 would occur with very low probability when it is set to True, and this
1018 flag should only be set to True when your code relies on the distribution
1019 of values for correctness.
1021 For managing global state, see the :func:`~hypothesis.strategies.random_module`
1022 strategy and :func:`~hypothesis.register_random` function.
1023 """
1024 check_type(bool, note_method_calls, "note_method_calls")
1025 check_type(bool, use_true_random, "use_true_random")
1027 from hypothesis.strategies._internal.random import RandomStrategy
1029 return RandomStrategy(
1030 use_true_random=use_true_random, note_method_calls=note_method_calls
1031 )
1034class RandomSeeder:
1035 def __init__(self, seed):
1036 self.seed = seed
1038 def __repr__(self):
1039 return f"RandomSeeder({self.seed!r})"
1042class RandomModule(SearchStrategy):
1043 def do_draw(self, data: ConjectureData) -> RandomSeeder:
1044 # It would be unsafe to do run this method more than once per test case,
1045 # because cleanup() runs tasks in FIFO order (at time of writing!).
1046 # Fortunately, the random_module() strategy wraps us in shared(), so
1047 # it's cached for all but the first of any number of calls.
1048 seed = data.draw(integers(0, 2**32 - 1))
1049 seed_all, restore_all = get_seeder_and_restorer(seed)
1050 seed_all()
1051 cleanup(restore_all)
1052 return RandomSeeder(seed)
1055@cacheable
1056@defines_strategy()
1057def random_module() -> SearchStrategy[RandomSeeder]:
1058 """Hypothesis always seeds global PRNGs before running a test, and restores the
1059 previous state afterwards.
1061 If having a fixed seed would unacceptably weaken your tests, and you
1062 cannot use a ``random.Random`` instance provided by
1063 :func:`~hypothesis.strategies.randoms`, this strategy calls
1064 :func:`python:random.seed` with an arbitrary integer and passes you
1065 an opaque object whose repr displays the seed value for debugging.
1066 If ``numpy.random`` is available, that state is also managed, as is anything
1067 managed by :func:`hypothesis.register_random`.
1069 Examples from these strategy shrink to seeds closer to zero.
1070 """
1071 return shared(RandomModule(), key="hypothesis.strategies.random_module()")
1074class BuildsStrategy(SearchStrategy[Ex]):
1075 def __init__(
1076 self,
1077 target: Callable[..., Ex],
1078 args: tuple[SearchStrategy[Any], ...],
1079 kwargs: dict[str, SearchStrategy[Any]],
1080 ):
1081 super().__init__()
1082 self.target = target
1083 self.args = args
1084 self.kwargs = kwargs
1086 def calc_label(self) -> int:
1087 return combine_labels(
1088 self.class_label,
1089 calc_label_from_callable(self.target),
1090 *[strat.label for strat in self.args],
1091 *[calc_label_from_name(k) for k in self.kwargs],
1092 *[strat.label for strat in self.kwargs.values()],
1093 )
1095 def do_draw(self, data: ConjectureData) -> Ex:
1096 context = current_build_context()
1097 arg_labels: ArgLabelsT = {}
1099 args = []
1100 for i, s in enumerate(self.args):
1101 with data.track_arg_label(f"arg[{i}]") as arg_label:
1102 args.append(data.draw(s))
1103 arg_labels |= arg_label
1105 kwargs = {}
1106 for k, v in self.kwargs.items():
1107 with data.track_arg_label(k) as arg_label:
1108 kwargs[k] = data.draw(v)
1109 arg_labels |= arg_label
1111 try:
1112 obj = self.target(*args, **kwargs)
1113 except TypeError as err:
1114 if (
1115 isinstance(self.target, type)
1116 and issubclass(self.target, enum.Enum)
1117 and not (self.args or self.kwargs)
1118 ):
1119 name = self.target.__module__ + "." + self.target.__qualname__
1120 raise InvalidArgument(
1121 f"Calling {name} with no arguments raised an error - "
1122 f"try using sampled_from({name}) instead of builds({name})"
1123 ) from err
1124 if not (self.args or self.kwargs):
1125 from .types import is_generic_type
1127 if isinstance(self.target, NewType) or is_generic_type(self.target):
1128 raise InvalidArgument(
1129 f"Calling {self.target!r} with no arguments raised an "
1130 f"error - try using from_type({self.target!r}) instead "
1131 f"of builds({self.target!r})"
1132 ) from err
1133 if getattr(self.target, "__no_type_check__", None) is True:
1134 # Note: could use PEP-678 __notes__ here. Migrate over once we're
1135 # using an `exceptiongroup` backport with support for that.
1136 raise TypeError(
1137 "This might be because the @no_type_check decorator prevented "
1138 "Hypothesis from inferring a strategy for some required arguments."
1139 ) from err
1140 raise
1142 context.record_call(
1143 obj, self.target, args=args, kwargs=kwargs, arg_labels=arg_labels
1144 )
1145 return obj
1147 def _invert(self, value: Any) -> tuple[ChoiceT, ...]:
1148 if not self.args and not self.kwargs:
1149 return ()
1150 if isinstance(self.target, type) and dataclasses.is_dataclass(self.target):
1151 # builds(MyDataclass, ...) is inspectable: positional args map to
1152 # fields in declaration order, kwargs map to fields by name.
1153 if not isinstance(value, self.target):
1154 raise CannotInvert(f"{value!r} is not an instance of {self.target!r}")
1155 field_names = [f.name for f in dataclasses.fields(self.target)]
1156 pairs = [
1157 *zip(field_names, self.args, strict=False),
1158 *self.kwargs.items(),
1159 ]
1160 choices: list[ChoiceT] = []
1161 for name, strategy in pairs:
1162 try:
1163 choices.extend(strategy._invert(getattr(value, name)))
1164 except CannotInvert as exc:
1165 add_note(exc, f"at field {name!r} of {value!r}, strategy={self!r}")
1166 raise
1167 return tuple(choices)
1168 # There are other special cases we could add here, in time.
1169 raise CannotInvert(f"cannot invert {self!r} (value={value!r})")
1171 def do_validate(self) -> None:
1172 tuples(*self.args).validate()
1173 fixed_dictionaries(self.kwargs).validate()
1175 def __repr__(self) -> str:
1176 bits = [get_pretty_function_description(self.target)]
1177 bits.extend(map(repr, self.args))
1178 bits.extend(f"{k}={v!r}" for k, v in self.kwargs.items())
1179 return f"builds({', '.join(bits)})"
1182@cacheable
1183@defines_strategy()
1184def builds(
1185 target: Callable[..., Ex],
1186 /,
1187 *args: SearchStrategy[Any],
1188 **kwargs: SearchStrategy[Any] | EllipsisType,
1189) -> SearchStrategy[Ex]:
1190 """Generates values by drawing from ``args`` and ``kwargs`` and passing
1191 them to the callable (provided as the first positional argument) in the
1192 appropriate argument position.
1194 e.g. ``builds(target, integers(), flag=booleans())`` would draw an
1195 integer ``i`` and a boolean ``b`` and call ``target(i, flag=b)``.
1197 If the callable has type annotations, they will be used to infer a strategy
1198 for required arguments that were not passed to builds. You can also tell
1199 builds to infer a strategy for an optional argument by passing ``...``
1200 (:obj:`python:Ellipsis`) as a keyword argument to builds, instead of a strategy for
1201 that argument to the callable.
1203 If the callable is a class defined with :pypi:`attrs`, missing required
1204 arguments will be inferred from the attribute on a best-effort basis,
1205 e.g. by checking :ref:`attrs standard validators <attrs:api-validators>`.
1206 Dataclasses are handled natively by the inference from type hints.
1208 Examples from this strategy shrink by shrinking the argument values to
1209 the callable.
1210 """
1211 if not callable(target):
1212 from hypothesis.strategies._internal.types import is_a_union
1214 # before 3.14, unions were callable, so it got an error message in
1215 # BuildsStrategy.do_draw. In 3.14+, unions are not callable, so
1216 # we error earlier here instead.
1217 suggestion = (
1218 f" Try using from_type({target}) instead?" if is_a_union(target) else ""
1219 )
1220 raise InvalidArgument(
1221 "The first positional argument to builds() must be a callable "
1222 f"target to construct.{suggestion}"
1223 )
1225 if ... in args: # type: ignore # we only annotated the allowed types
1226 # Avoid an implementation nightmare juggling tuples and worse things
1227 raise InvalidArgument(
1228 "... was passed as a positional argument to "
1229 "builds(), but is only allowed as a keyword arg"
1230 )
1231 required = required_args(target, args, kwargs)
1232 to_infer = {k for k, v in kwargs.items() if v is ...}
1233 if required or to_infer:
1234 if (
1235 isinstance(target, type)
1236 and (attr := sys.modules.get("attr")) is not None
1237 and attr.has(target)
1238 ):
1239 # Use our custom introspection for attrs classes
1240 from hypothesis.strategies._internal.attrs import from_attrs
1242 return from_attrs(target, args, kwargs, required | to_infer)
1243 # Otherwise, try using type hints
1244 hints = get_type_hints(target)
1245 if to_infer - set(hints):
1246 badargs = ", ".join(sorted(to_infer - set(hints)))
1247 raise InvalidArgument(
1248 f"passed ... for {badargs}, but we cannot infer a strategy "
1249 "because these arguments have no type annotation"
1250 )
1251 infer_for = {k: v for k, v in hints.items() if k in (required | to_infer)}
1252 if infer_for:
1253 from hypothesis.strategies._internal.types import _global_type_lookup
1255 for kw, t in infer_for.items():
1256 if t in _global_type_lookup:
1257 kwargs[kw] = from_type(t)
1258 else:
1259 # We defer resolution of these type annotations so that the obvious
1260 # approach to registering recursive types just works. I.e.,
1261 # if we're inside `register_type_strategy(cls, builds(cls, ...))`
1262 # and `...` contains recursion on `cls`. See
1263 # https://github.com/HypothesisWorks/hypothesis/issues/3026
1264 kwargs[kw] = deferred(lambda t=t: from_type(t)) # type: ignore
1266 # validated by handling all EllipsisType in the to_infer case
1267 kwargs = cast(dict[str, SearchStrategy], kwargs)
1268 return BuildsStrategy(target, args, kwargs)
1271@cacheable
1272@defines_strategy(eager=True)
1273def from_type(thing: type[T]) -> SearchStrategy[T]:
1274 """Looks up the appropriate search strategy for the given type.
1276 |st.from_type| is used internally to fill in missing arguments to
1277 |st.builds| and can be used interactively
1278 to explore what strategies are available or to debug type resolution.
1280 You can use |st.register_type_strategy| to
1281 handle your custom types, or to globally redefine certain strategies -
1282 for example excluding NaN from floats, or use timezone-aware instead of
1283 naive time and datetime strategies.
1285 |st.from_type| looks up a strategy in the following order:
1287 1. If ``thing`` is in the default lookup mapping or user-registered lookup,
1288 return the corresponding strategy. The default lookup covers all types
1289 with Hypothesis strategies, including extras where possible.
1290 2. If ``thing`` is from the :mod:`python:typing` module, return the
1291 corresponding strategy (special logic).
1292 3. If ``thing`` has one or more subtypes in the merged lookup, return
1293 the union of the strategies for those types that are not subtypes of
1294 other elements in the lookup.
1295 4. Finally, if ``thing`` has type annotations for all required arguments,
1296 and is not an abstract class, it is resolved via
1297 |st.builds|.
1298 5. Because :mod:`abstract types <python:abc>` cannot be instantiated,
1299 we treat abstract types as the union of their concrete subclasses.
1300 Note that this lookup works via inheritance but not via
1301 :obj:`~python:abc.ABCMeta.register`, so you may still need to use
1302 |st.register_type_strategy|.
1304 There is a valuable recipe for leveraging |st.from_type| to generate
1305 "everything except" values from a specified type. I.e.
1307 .. code-block:: python
1309 def everything_except(excluded_types):
1310 return (
1311 from_type(type)
1312 .flatmap(from_type)
1313 .filter(lambda x: not isinstance(x, excluded_types))
1314 )
1316 For example, ``everything_except(int)`` returns a strategy that can
1317 generate anything that |st.from_type| can ever generate, except for
1318 instances of |int|, and excluding instances of types
1319 added via |st.register_type_strategy|.
1321 This is useful when writing tests which check that invalid input is
1322 rejected in a certain way.
1323 """
1324 try:
1325 with warnings.catch_warnings():
1326 warnings.simplefilter("error")
1327 return _from_type(thing)
1328 except Exception:
1329 return _from_type_deferred(thing)
1332def _from_type_deferred(thing: type[Ex]) -> SearchStrategy[Ex]:
1333 # This tricky little dance is because we want to show the repr of the actual
1334 # underlying strategy wherever possible, as a form of user education, but
1335 # would prefer to fall back to the default "from_type(...)" repr instead of
1336 # "deferred(...)" for recursive types or invalid arguments.
1337 try:
1338 thing_repr = nicerepr(thing)
1339 if hasattr(thing, "__module__"):
1340 module_prefix = f"{thing.__module__}."
1341 if not thing_repr.startswith(module_prefix):
1342 thing_repr = module_prefix + thing_repr
1343 repr_ = f"from_type({thing_repr})"
1344 except Exception: # pragma: no cover
1345 repr_ = None
1346 return LazyStrategy(
1347 lambda thing: deferred(lambda: _from_type(thing)),
1348 (thing,),
1349 {},
1350 force_repr=repr_,
1351 )
1354_recurse_guard: ContextVar = ContextVar("recurse_guard")
1355_abstract_recurse_guard: ContextVar = ContextVar("abstract_recurse_guard")
1358def _from_type(thing: type[Ex]) -> SearchStrategy[Ex]:
1359 # TODO: We would like to move this to the top level, but pending some major
1360 # refactoring it's hard to do without creating circular imports.
1361 from hypothesis.strategies._internal import types
1363 def as_strategy(strat_or_callable, thing):
1364 # User-provided strategies need some validation, and callables even more
1365 # of it. We do this in three places, hence the helper function
1366 if not isinstance(strat_or_callable, SearchStrategy):
1367 assert callable(strat_or_callable) # Validated in register_type_strategy
1368 strategy = strat_or_callable(thing)
1369 else:
1370 strategy = strat_or_callable
1371 if strategy is NotImplemented:
1372 return NotImplemented
1373 if not isinstance(strategy, SearchStrategy):
1374 raise ResolutionFailed(
1375 f"Error: {thing} was registered for {nicerepr(strat_or_callable)}, "
1376 f"but returned non-strategy {strategy!r}"
1377 )
1378 if strategy.is_empty:
1379 raise ResolutionFailed(f"Error: {thing!r} resolved to an empty strategy")
1380 return strategy
1382 def from_type_guarded(thing):
1383 """Returns the result of producer, or ... if recursion on thing is encountered"""
1384 try:
1385 recurse_guard = _recurse_guard.get()
1386 except LookupError:
1387 # We can't simply define the contextvar with default=[], as the
1388 # default object would be shared across contexts
1389 _recurse_guard.set(recurse_guard := [])
1390 if thing in recurse_guard:
1391 raise RewindRecursive(thing)
1392 recurse_guard.append(thing)
1393 try:
1394 return _from_type(thing)
1395 except RewindRecursive as rr:
1396 if rr.target != thing:
1397 raise
1398 return ... # defer resolution
1399 finally:
1400 recurse_guard.pop()
1402 # Let registered extra modules handle their own recognized types first, before
1403 # e.g. Unions are resolved
1404 try:
1405 known = thing in types._global_type_lookup
1406 except TypeError:
1407 # thing is not always hashable!
1408 pass
1409 else:
1410 if not known:
1411 for module, resolver in types._global_extra_lookup.items():
1412 if module in sys.modules:
1413 strat = resolver(thing)
1414 if strat is not None:
1415 return strat
1417 if isinstance(thing, NewType):
1418 # Check if we have an explicitly registered strategy for this thing,
1419 # resolve it so, and otherwise resolve as for the base type.
1420 if thing in types._global_type_lookup:
1421 strategy = as_strategy(types._global_type_lookup[thing], thing)
1422 if strategy is not NotImplemented:
1423 return strategy
1424 return _from_type(thing.__supertype__)
1425 if types.is_a_type_alias_type(thing): # pragma: no cover # covered by 3.12+ tests
1426 if thing in types._global_type_lookup:
1427 strategy = as_strategy(types._global_type_lookup[thing], thing)
1428 if strategy is not NotImplemented:
1429 return strategy
1430 return _from_type(thing.__value__) # type: ignore
1431 if types.is_a_type_alias_type(origin := get_origin(thing)): # pragma: no cover
1432 # Handle parametrized type aliases like `type A[T] = list[T]; thing = A[int]`.
1433 # In this case, `thing` is a GenericAlias whose origin is a TypeAliasType.
1434 #
1435 # covered by 3.12+ tests.
1436 if origin in types._global_type_lookup:
1437 strategy = as_strategy(types._global_type_lookup[origin], thing)
1438 if strategy is not NotImplemented:
1439 return strategy
1440 return _from_type(types.evaluate_type_alias_type(thing))
1441 if types.is_a_union(thing):
1442 args = sorted(thing.__args__, key=types.type_sorting_key) # type: ignore
1443 return one_of([_from_type(t) for t in args])
1444 if thing in types.LiteralStringTypes:
1445 # We can't really cover this because it needs either
1446 # typing-extensions or python3.11+ typing.
1447 # `LiteralString` from runtime's point of view is just a string.
1448 # Fallback to regular text.
1449 return text() # type: ignore
1451 # We also have a special case for TypeVars.
1452 # They are represented as instances like `~T` when they come here.
1453 # We need to work with their type instead.
1454 if isinstance(thing, TypeVar) and type(thing) in types._global_type_lookup:
1455 strategy = as_strategy(types._global_type_lookup[type(thing)], thing)
1456 if strategy is not NotImplemented:
1457 return strategy
1459 if not types.is_a_type(thing):
1460 if isinstance(thing, str):
1461 # See https://github.com/HypothesisWorks/hypothesis/issues/3016
1462 # String forward references like "LinkedList" can be converted to
1463 # ForwardRef objects if they are valid Python identifiers.
1464 # See https://github.com/HypothesisWorks/hypothesis/issues/4542
1465 if thing.isidentifier():
1466 return deferred(lambda thing=thing: from_type(typing.ForwardRef(thing)))
1467 raise InvalidArgument(
1468 f"Got {thing!r} as a type annotation, but the forward-reference "
1469 "could not be resolved from a string to a type. Consider using "
1470 "`from __future__ import annotations` instead of forward-reference "
1471 "strings."
1472 )
1473 raise InvalidArgument(f"{thing=} must be a type")
1475 if thing in types.NON_RUNTIME_TYPES:
1476 # Some code like `st.from_type(TypeAlias)` does not make sense.
1477 # Because there are types in python that do not exist in runtime.
1478 raise InvalidArgument(
1479 f"Could not resolve {thing!r} to a strategy, "
1480 f"because there is no such thing as a runtime instance of {thing!r}"
1481 )
1483 # Now that we know `thing` is a type, the first step is to check for an
1484 # explicitly registered strategy. This is the best (and hopefully most
1485 # common) way to resolve a type to a strategy. Note that the value in the
1486 # lookup may be a strategy or a function from type -> strategy; and we
1487 # convert empty results into an explicit error.
1488 try:
1489 if thing in types._global_type_lookup:
1490 strategy = as_strategy(types._global_type_lookup[thing], thing)
1491 if strategy is not NotImplemented:
1492 return strategy
1493 elif (
1494 isinstance(thing, GenericAlias)
1495 and (origin := get_origin(thing)) in types._global_type_lookup
1496 ):
1497 strategy = as_strategy(types._global_type_lookup[origin], thing)
1498 if strategy is not NotImplemented:
1499 return strategy
1500 except TypeError:
1501 # This was originally due to a bizarre divergence in behaviour on Python 3.9.0:
1502 # typing.Callable[[], foo] has __args__ = (foo,) but collections.abc.Callable
1503 # has __args__ = ([], foo); and as a result is non-hashable.
1504 # We've kept it because we turn out to have more type errors from... somewhere.
1505 # FIXME: investigate that, maybe it should be fixed more precisely?
1506 pass
1508 if (hasattr(typing, "_TypedDictMeta") and type(thing) is typing._TypedDictMeta) or (
1509 hasattr(types.typing_extensions, "_TypedDictMeta") # type: ignore
1510 and type(thing) is types.typing_extensions._TypedDictMeta # type: ignore
1511 ): # pragma: no cover
1513 def _get_annotation_arg(key, annotation_type):
1514 try:
1515 return get_args(annotation_type)[0]
1516 except IndexError:
1517 raise InvalidArgument(
1518 f"`{key}: {annotation_type.__name__}` is not a valid type annotation"
1519 ) from None
1521 # Taken from `Lib/typing.py` and modified:
1522 def _get_typeddict_qualifiers(key, annotation_type):
1523 qualifiers = []
1524 annotations = []
1525 while True:
1526 annotation_origin = types.extended_get_origin(annotation_type)
1527 if annotation_origin is Annotated:
1528 if annotation_args := get_args(annotation_type):
1529 annotation_type = annotation_args[0]
1530 annotations.extend(annotation_args[1:])
1531 else:
1532 break
1533 elif annotation_origin in types.RequiredTypes:
1534 qualifiers.append(types.RequiredTypes)
1535 annotation_type = _get_annotation_arg(key, annotation_type)
1536 elif annotation_origin in types.NotRequiredTypes:
1537 qualifiers.append(types.NotRequiredTypes)
1538 annotation_type = _get_annotation_arg(key, annotation_type)
1539 elif annotation_origin in types.ReadOnlyTypes:
1540 qualifiers.append(types.ReadOnlyTypes)
1541 annotation_type = _get_annotation_arg(key, annotation_type)
1542 else:
1543 break
1544 if annotations:
1545 annotation_type = Annotated[(annotation_type, *annotations)]
1546 return set(qualifiers), annotation_type
1548 # The __optional_keys__ attribute may or may not be present, but if there's no
1549 # way to tell and we just have to assume that everything is required.
1550 # See https://github.com/python/cpython/pull/17214 for details.
1551 optional = set(getattr(thing, "__optional_keys__", ()))
1552 required = set(
1553 getattr(thing, "__required_keys__", get_type_hints(thing).keys())
1554 )
1555 anns = {}
1556 for k, v in get_type_hints(thing).items():
1557 qualifiers, v = _get_typeddict_qualifiers(k, v)
1558 # We ignore `ReadOnly` type for now, only unwrap it.
1559 if types.RequiredTypes in qualifiers:
1560 optional.discard(k)
1561 required.add(k)
1562 if types.NotRequiredTypes in qualifiers:
1563 optional.add(k)
1564 required.discard(k)
1566 anns[k] = from_type_guarded(v)
1567 if anns[k] is ...:
1568 anns[k] = _from_type_deferred(v)
1570 if not required.isdisjoint(optional): # pragma: no cover
1571 # It is impossible to cover, because `typing.py` or `typing-extensions`
1572 # won't allow creating incorrect TypedDicts,
1573 # this is just a sanity check from our side.
1574 raise InvalidArgument(
1575 f"Required keys overlap with optional keys in a TypedDict:"
1576 f" {required=}, {optional=}"
1577 )
1578 if (
1579 (not anns)
1580 and thing.__annotations__
1581 and ".<locals>." in getattr(thing, "__qualname__", "")
1582 ):
1583 raise InvalidArgument("Failed to retrieve type annotations for local type")
1584 return fixed_dictionaries( # type: ignore
1585 mapping={k: v for k, v in anns.items() if k in required},
1586 optional={k: v for k, v in anns.items() if k in optional},
1587 )
1589 # If there's no explicitly registered strategy, maybe a subtype of thing
1590 # is registered - if so, we can resolve it to the subclass strategy.
1591 # We'll start by checking if thing is from the typing module,
1592 # because there are several special cases that don't play well with
1593 # subclass and instance checks.
1594 if (
1595 isinstance(thing, types.typing_root_type)
1596 or (isinstance(get_origin(thing), type) and get_args(thing))
1597 or isinstance(thing, typing.ForwardRef)
1598 ):
1599 return types.from_typing_type(thing)
1601 # If it's not from the typing module, we get all registered types that are
1602 # a subclass of `thing` and are not themselves a subtype of any other such
1603 # type. For example, `Number -> integers() | floats()`, but bools() is
1604 # not included because bool is a subclass of int as well as Number.
1605 # Filter to matching subtypes *before* sorting, because computing the repr
1606 # of every registered strategy (just to establish a deterministic order) is
1607 # surprisingly expensive and usually wasted - the matching set is typically
1608 # empty for user-defined types.
1609 matching = [
1610 (k, v)
1611 for k, v in types._global_type_lookup.items()
1612 if isinstance(k, type)
1613 and issubclass(k, thing)
1614 and sum(types.try_issubclass(k, typ) for typ in types._global_type_lookup) == 1
1615 ]
1616 strategies = [
1617 s
1618 for s in (as_strategy(v, thing) for _, v in sorted(matching, key=repr))
1619 if s is not NotImplemented
1620 ]
1621 if any(not s.is_empty for s in strategies):
1622 return one_of(strategies)
1624 # If we don't have a strategy registered for this type or any subtype, we
1625 # may be able to fall back on type annotations.
1626 if issubclass(thing, enum.Enum):
1627 return sampled_from(thing)
1629 # Finally, try to build an instance by calling the type object. Unlike builds(),
1630 # this block *does* try to infer strategies for arguments with default values.
1631 # That's because of the semantic different; builds() -> "call this with ..."
1632 # so we only infer when *not* doing so would be an error; from_type() -> "give
1633 # me arbitrary instances" so the greater variety is acceptable.
1634 # And if it's *too* varied, express your opinions with register_type_strategy()
1635 if not isabstract(thing):
1636 # If we know that builds(thing) will fail, give a better error message
1637 required = required_args(thing)
1638 if required and not (
1639 required.issubset(get_type_hints(thing))
1640 or ((attr := sys.modules.get("attr")) is not None and attr.has(thing))
1641 or is_typed_named_tuple(thing) # weird enough that we have a specific check
1642 ):
1643 raise ResolutionFailed(
1644 f"Could not resolve {thing!r} to a strategy; consider "
1645 "using register_type_strategy"
1646 )
1647 try:
1648 hints = get_type_hints(thing)
1649 params: Mapping[str, Parameter] = get_signature(thing).parameters
1650 except Exception:
1651 params = {}
1653 posonly_args = []
1654 kwargs = {}
1655 for k, p in params.items():
1656 if (
1657 p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD, p.KEYWORD_ONLY)
1658 and k in hints
1659 and k != "return"
1660 ):
1661 ps = from_type_guarded(hints[k])
1662 if p.default is not Parameter.empty and ps is not ...:
1663 ps = just(p.default) | ps
1664 if p.kind is Parameter.POSITIONAL_ONLY:
1665 # builds() doesn't infer strategies for positional args, so:
1666 if ps is ...: # pragma: no cover # rather fiddly to test
1667 if p.default is Parameter.empty:
1668 raise ResolutionFailed(
1669 f"Could not resolve {thing!r} to a strategy; "
1670 "consider using register_type_strategy"
1671 )
1672 ps = just(p.default)
1673 posonly_args.append(ps)
1674 else:
1675 kwargs[k] = ps
1676 if (
1677 params
1678 and not (posonly_args or kwargs)
1679 and not issubclass(thing, BaseException)
1680 ):
1681 from_type_repr = repr_call(from_type, (thing,), {})
1682 builds_repr = repr_call(builds, (thing,), {})
1683 warnings.warn(
1684 f"{from_type_repr} resolved to {builds_repr}, because we could not "
1685 "find any (non-varargs) arguments. Use st.register_type_strategy() "
1686 "to resolve to a strategy which can generate more than one value, "
1687 "or to silence this warning.",
1688 SmallSearchSpaceWarning,
1689 stacklevel=2,
1690 )
1691 return builds(thing, *posonly_args, **kwargs)
1693 # And if it's an abstract type, we'll resolve to a union of subclasses instead.
1694 subclasses = thing.__subclasses__()
1695 if not subclasses:
1696 raise ResolutionFailed(
1697 f"Could not resolve {thing!r} to a strategy, because it is an abstract "
1698 "type without any subclasses. Consider using register_type_strategy"
1699 )
1701 # When subclasses reference `thing` (directly, or via a sibling subclass)
1702 # in their own annotations, naively resolving each subclass would re-resolve
1703 # the entire hierarchy once per reference - which is combinatorially
1704 # expensive for mutually-recursive types. We track the abstract types we're
1705 # currently resolving and defer any recursive reference back to them (by
1706 # returning the cached strategy, so the references share one object - which
1707 # lets recursion in e.g. is_empty checks terminate), so each type is resolved
1708 # only once per pass. We use a guard separate from `_recurse_guard` because
1709 # this catches references regardless of how they reach `_from_type` (e.g. as a
1710 # union arg), and because it must not make `from_type_guarded` treat a
1711 # subclass's required field of type `thing` as unresolvable.
1712 try:
1713 abstract_guard = _abstract_recurse_guard.get()
1714 except LookupError:
1715 _abstract_recurse_guard.set(abstract_guard := set())
1716 if thing in abstract_guard:
1717 return from_type(thing)
1719 abstract_guard.add(thing)
1720 try:
1721 substrategies = []
1722 for sc in subclasses:
1723 try:
1724 substrategies.append(_from_type(sc))
1725 except Exception:
1726 pass
1727 finally:
1728 abstract_guard.discard(thing)
1729 subclass_strategies = one_of(substrategies)
1730 if subclass_strategies.is_empty:
1731 # We're unable to resolve subclasses now, but we might be able to later -
1732 # so we'll just go back to the mixed distribution.
1733 return sampled_from(subclasses).flatmap(_from_type)
1734 return subclass_strategies
1737@cacheable
1738@defines_strategy(force_reusable_values=True)
1739def fractions(
1740 min_value: Real | str | None = None,
1741 max_value: Real | str | None = None,
1742 *,
1743 max_denominator: int | None = None,
1744) -> SearchStrategy[Fraction]:
1745 """Returns a strategy which generates Fractions.
1747 If ``min_value`` is not None then all generated values are no less than
1748 ``min_value``. If ``max_value`` is not None then all generated values are no
1749 greater than ``max_value``. ``min_value`` and ``max_value`` may be anything accepted
1750 by the :class:`~fractions.Fraction` constructor.
1752 If ``max_denominator`` is not None then the denominator of any generated
1753 values is no greater than ``max_denominator``. Note that ``max_denominator`` must
1754 be None or a positive integer.
1756 Examples from this strategy shrink towards smaller denominators, then
1757 closer to zero.
1758 """
1759 min_value = try_convert(Fraction, min_value, "min_value")
1760 max_value = try_convert(Fraction, max_value, "max_value")
1761 # These assertions tell Mypy what happened in try_convert
1762 assert min_value is None or isinstance(min_value, Fraction)
1763 assert max_value is None or isinstance(max_value, Fraction)
1765 check_valid_interval(min_value, max_value, "min_value", "max_value")
1766 check_valid_integer(max_denominator, "max_denominator")
1768 if max_denominator is not None:
1769 if max_denominator < 1:
1770 raise InvalidArgument(f"{max_denominator=} must be >= 1")
1771 if min_value is not None and min_value.denominator > max_denominator:
1772 raise InvalidArgument(
1773 f"The {min_value=} has a denominator greater than the "
1774 f"{max_denominator=}"
1775 )
1776 if max_value is not None and max_value.denominator > max_denominator:
1777 raise InvalidArgument(
1778 f"The {max_value=} has a denominator greater than the "
1779 f"{max_denominator=}"
1780 )
1782 if min_value is not None and min_value == max_value:
1783 return just(min_value)
1785 def dm_func(denom):
1786 """Take denom, construct numerator strategy, and build fraction."""
1787 # Four cases of algebra to get integer bounds and scale factor.
1788 min_num, max_num = None, None
1789 if max_value is None and min_value is None:
1790 pass
1791 elif min_value is None:
1792 max_num = denom * max_value.numerator
1793 denom *= max_value.denominator
1794 elif max_value is None:
1795 min_num = denom * min_value.numerator
1796 denom *= min_value.denominator
1797 else:
1798 low = min_value.numerator * max_value.denominator
1799 high = max_value.numerator * min_value.denominator
1800 scale = min_value.denominator * max_value.denominator
1801 # After calculating our integer bounds and scale factor, we remove
1802 # the gcd to avoid drawing more bytes for the example than needed.
1803 # Note that `div` can be at most equal to `scale`.
1804 div = math.gcd(scale, math.gcd(low, high))
1805 min_num = denom * low // div
1806 max_num = denom * high // div
1807 denom *= scale // div
1809 return builds(
1810 Fraction, integers(min_value=min_num, max_value=max_num), just(denom)
1811 )
1813 if max_denominator is None:
1814 return integers(min_value=1).flatmap(dm_func)
1816 return (
1817 integers(1, max_denominator)
1818 .flatmap(dm_func)
1819 .map(lambda f: f.limit_denominator(max_denominator))
1820 )
1823def _as_finite_decimal(
1824 value: Real | str | None, name: str, allow_infinity: bool | None, places: int | None
1825) -> Decimal | None:
1826 """Convert decimal bounds to decimals, carefully."""
1827 assert name in ("min_value", "max_value")
1828 if value is None:
1829 return None
1830 old = value
1831 if isinstance(value, Fraction):
1832 value = Context(prec=places).divide(value.numerator, value.denominator)
1833 if old != value:
1834 raise InvalidArgument(
1835 f"{old!r} cannot be exactly represented as a decimal with {places=}"
1836 )
1837 if not isinstance(value, Decimal):
1838 with localcontext(Context()): # ensure that default traps are enabled
1839 value = try_convert(Decimal, value, name)
1840 assert isinstance(value, Decimal)
1841 if value.is_nan():
1842 raise InvalidArgument(f"Invalid {name}={value!r}")
1844 # If you are reading this conditional, I am so sorry. I did my best.
1845 finitude_old = value if isinstance(old, str) else old
1846 if math.isfinite(finitude_old) != math.isfinite(value) or (
1847 value.is_finite() and Fraction(str(old)) != Fraction(str(value))
1848 ):
1849 note_deprecation(
1850 f"{old!r} cannot be exactly represented as a decimal with {places=}",
1851 since="2025-11-02",
1852 has_codemod=False,
1853 stacklevel=1,
1854 )
1856 if value.is_finite():
1857 return value
1858 assert value.is_infinite()
1859 if (value < 0 if "min" in name else value > 0) and allow_infinity is not False:
1860 return None
1861 raise InvalidArgument(f"{allow_infinity=}, but {name}={value!r}")
1864@cacheable
1865@defines_strategy(force_reusable_values=True)
1866def decimals(
1867 min_value: Real | str | None = None,
1868 max_value: Real | str | None = None,
1869 *,
1870 allow_nan: bool | None = None,
1871 allow_infinity: bool | None = None,
1872 places: int | None = None,
1873) -> SearchStrategy[Decimal]:
1874 """Generates instances of :class:`python:decimal.Decimal`, which may be:
1876 - A finite rational number, between ``min_value`` and ``max_value``.
1877 - Not a Number, if ``allow_nan`` is True. None means "allow NaN, unless
1878 ``min_value`` and ``max_value`` are not None".
1879 - Positive or negative infinity, if ``max_value`` and ``min_value``
1880 respectively are None, and ``allow_infinity`` is not False. None means
1881 "allow infinity, unless excluded by the min and max values".
1883 Note that where floats have one ``NaN`` value, Decimals have four: signed,
1884 and either *quiet* or *signalling*. See `the decimal module docs
1885 <https://docs.python.org/3/library/decimal.html#special-values>`_ for
1886 more information on special values.
1888 If ``places`` is not None, all finite values drawn from the strategy will
1889 have that number of digits after the decimal place.
1891 Examples from this strategy do not have a well defined shrink order but
1892 try to maximize human readability when shrinking.
1893 """
1894 # Convert min_value and max_value to Decimal values, and validate args
1895 check_valid_integer(places, "places")
1896 if places is not None and places < 0:
1897 raise InvalidArgument(f"{places=} may not be negative")
1898 min_value = _as_finite_decimal(min_value, "min_value", allow_infinity, places)
1899 max_value = _as_finite_decimal(max_value, "max_value", allow_infinity, places)
1900 check_valid_interval(min_value, max_value, "min_value", "max_value")
1901 if allow_infinity and (None not in (min_value, max_value)):
1902 raise InvalidArgument("Cannot allow infinity between finite bounds")
1903 # Set up a strategy for finite decimals. Note that both floating and
1904 # fixed-point decimals require careful handling to remain isolated from
1905 # any external precision context - in short, we always work out the
1906 # required precision for lossless operation and use context methods.
1907 if places is not None:
1908 # Fixed-point decimals are basically integers with a scale factor
1909 def ctx(val):
1910 """Return a context in which this value is lossless."""
1911 precision = ceil(math.log10(abs(val) or 1)) + places + 1
1912 return Context(prec=max([precision, 1]))
1914 def int_to_decimal(val):
1915 context = ctx(val)
1916 return context.quantize(context.multiply(val, factor), factor)
1918 factor = Decimal(10) ** -places
1919 min_num, max_num = None, None
1920 # Work out the integer bounds exactly: limited-precision division can
1921 # round when the bounds have more than `places` fractional digits,
1922 # which would make ceil/floor over- or undershoot the true bound.
1923 if min_value is not None:
1924 min_num = ceil(Fraction(min_value) / Fraction(factor))
1925 if max_value is not None:
1926 max_num = floor(Fraction(max_value) / Fraction(factor))
1927 if min_num is not None and max_num is not None and min_num > max_num:
1928 raise InvalidArgument(
1929 f"There are no decimals with {places} places between "
1930 f"{min_value=} and {max_value=}"
1931 )
1932 strat = integers(min_num, max_num).map(int_to_decimal)
1933 else:
1934 # Otherwise, they're like fractions featuring a power of ten
1935 def fraction_to_decimal(val):
1936 precision = (
1937 ceil(math.log10(abs(val.numerator) or 1) + math.log10(val.denominator))
1938 + 1
1939 )
1940 return Context(prec=precision or 1).divide(
1941 Decimal(val.numerator), val.denominator
1942 )
1944 strat = fractions(min_value, max_value).map(fraction_to_decimal)
1945 # Compose with sampled_from for infinities and NaNs as appropriate
1946 special: list[Decimal] = []
1947 if allow_infinity or (allow_infinity is None and max_value is None):
1948 special.append(Decimal("Infinity"))
1949 if allow_infinity or (allow_infinity is None and min_value is None):
1950 special.append(Decimal("-Infinity"))
1951 if allow_nan or (allow_nan is None and (None in (min_value, max_value))):
1952 special.extend(map(Decimal, ("NaN", "-NaN", "sNaN", "-sNaN")))
1953 return strat | (sampled_from(special) if special else nothing())
1956@defines_strategy(eager=True)
1957def recursive(
1958 base: SearchStrategy[Ex],
1959 extend: Callable[[SearchStrategy[Any]], SearchStrategy[T]],
1960 *,
1961 min_leaves: int | None = None,
1962 max_leaves: int = 100,
1963) -> SearchStrategy[T | Ex]:
1964 """base: A strategy to start from.
1966 extend: A function which takes a strategy and returns a new strategy.
1968 min_leaves: The minimum number of elements to be drawn from base on a given run.
1970 max_leaves: The maximum number of elements to be drawn from base on a given run.
1972 This returns a strategy ``S`` such that ``S = extend(base | S)``. That is,
1973 values may be drawn from base, or from any strategy reachable by mixing
1974 applications of | and extend.
1976 An example may clarify: ``recursive(booleans(), lists)`` would return a
1977 strategy that may return arbitrarily nested and mixed lists of booleans.
1978 So e.g. ``False``, ``[True]``, ``[False, []]``, and ``[[[[True]]]]`` are
1979 all valid values to be drawn from that strategy.
1981 Examples from this strategy shrink by trying to reduce the amount of
1982 recursion and by shrinking according to the shrinking behaviour of base
1983 and the result of extend.
1984 """
1985 return RecursiveStrategy(base, extend, min_leaves, max_leaves)
1988class PermutationStrategy(SearchStrategy):
1989 def __init__(self, values):
1990 super().__init__()
1991 self.values = values
1993 def do_draw(self, data):
1994 result = list(self.values)
1995 fisher_yates_shuffle(data, result)
1996 return result
1998 def _invert(self, value: Any) -> tuple[ChoiceT, ...]:
1999 if not isinstance(value, list) or len(value) != len(self.values):
2000 raise CannotInvert(f"{value!r} is not a list of the expected length")
2001 # Reverse the Fisher-Yates shuffle: walk the intermediate array
2002 # forward, at each step choosing the swap index j whose current
2003 # element equals the target value at this position.
2004 current = list(self.values)
2005 choices: list[ChoiceT] = []
2006 for i, target in enumerate(value[:-1]):
2007 for j in range(i, len(current)):
2008 if equal_values(current[j], target):
2009 choices.append(j)
2010 current[i], current[j] = current[j], current[i]
2011 break
2012 else:
2013 raise CannotInvert(f"{value!r} is not a permutation of {self.values!r}")
2014 # The last position is fixed by the previous swaps - check that the
2015 # input really was a permutation.
2016 if current and not equal_values(current[-1], value[-1]):
2017 raise CannotInvert(f"{value!r} is not a permutation of {self.values!r}")
2018 return tuple(choices)
2021@defines_strategy()
2022def permutations(values: Sequence[T]) -> SearchStrategy[list[T]]:
2023 """Return a strategy which returns permutations of the ordered collection
2024 ``values``.
2026 Examples from this strategy shrink by trying to become closer to the
2027 original order of values.
2028 """
2029 values = check_sample(values, "permutations")
2030 if not values:
2031 return builds(list)
2033 return PermutationStrategy(values)
2036class CompositeStrategy(SearchStrategy):
2037 def __init__(self, definition, args, kwargs):
2038 super().__init__()
2039 self.definition = definition
2040 self.args = args
2041 self.kwargs = kwargs
2043 def do_draw(self, data):
2044 return self.definition(data.draw, *self.args, **self.kwargs)
2046 def calc_label(self) -> int:
2047 return combine_labels(
2048 self.class_label,
2049 calc_label_from_callable(self.definition),
2050 )
2053class DrawFn(Protocol):
2054 """This type only exists so that you can write type hints for functions
2055 decorated with :func:`@composite <hypothesis.strategies.composite>`.
2057 .. code-block:: python
2059 def draw(strategy: SearchStrategy[Ex], label: object = None) -> Ex: ...
2061 @composite
2062 def list_and_index(draw: DrawFn) -> tuple[int, str]:
2063 i = draw(integers()) # type of `i` inferred as 'int'
2064 s = draw(text()) # type of `s` inferred as 'str'
2065 return i, s
2066 """
2068 def __init__(self):
2069 raise TypeError("Protocols cannot be instantiated")
2071 # Protocol overrides our signature for __init__,
2072 # so we override it right back to make the docs look nice.
2073 __signature__: Signature = Signature(parameters=[])
2075 # We define this as a callback protocol because a simple typing.Callable is
2076 # insufficient to fully represent the interface, due to the optional `label`
2077 # parameter.
2078 def __call__(self, strategy: SearchStrategy[Ex], label: object = None) -> Ex:
2079 raise NotImplementedError
2082def _composite(f):
2083 # Wrapped below, using ParamSpec if available
2084 if isinstance(f, (classmethod, staticmethod)):
2085 special_method = type(f)
2086 f = f.__func__
2087 else:
2088 special_method = None
2090 sig = get_signature(f)
2091 params = tuple(sig.parameters.values())
2093 if not (params and "POSITIONAL" in params[0].kind.name):
2094 raise InvalidArgument(
2095 "Functions wrapped with composite must take at least one "
2096 "positional argument."
2097 )
2098 if params[0].default is not sig.empty:
2099 raise InvalidArgument("A default value for initial argument will never be used")
2100 if not (f is typing._overload_dummy or is_first_param_referenced_in_function(f)):
2101 note_deprecation(
2102 "There is no reason to use @st.composite on a function which "
2103 "does not call the provided draw() function internally.",
2104 since="2022-07-17",
2105 has_codemod=False,
2106 )
2107 if get_origin(sig.return_annotation) is SearchStrategy:
2108 ret_repr = repr(sig.return_annotation).replace("hypothesis.strategies.", "st.")
2109 warnings.warn(
2110 f"Return-type annotation is `{ret_repr}`, but the decorated "
2111 "function should return a value (not a strategy)",
2112 HypothesisWarning,
2113 stacklevel=3,
2114 )
2115 if params[0].kind.name != "VAR_POSITIONAL":
2116 params = params[1:]
2117 newsig = sig.replace(
2118 parameters=params,
2119 return_annotation=(
2120 SearchStrategy
2121 if sig.return_annotation is sig.empty
2122 else SearchStrategy[sig.return_annotation]
2123 ),
2124 )
2126 @defines_strategy()
2127 @define_function_signature(f.__name__, f.__doc__, newsig)
2128 def accept(*args, **kwargs):
2129 return CompositeStrategy(f, args, kwargs)
2131 accept.__module__ = f.__module__
2132 accept.__signature__ = newsig
2133 if special_method is not None:
2134 return special_method(accept)
2135 return accept
2138composite_doc = """
2139Defines a strategy that is built out of potentially arbitrarily many other
2140strategies.
2142@composite provides a callable ``draw`` as the first parameter to the decorated
2143function, which can be used to dynamically draw a value from any strategy. For
2144example:
2146.. code-block:: python
2148 from hypothesis import strategies as st, given
2150 @st.composite
2151 def values(draw):
2152 n1 = draw(st.integers())
2153 n2 = draw(st.integers(min_value=n1))
2154 return (n1, n2)
2156 @given(values())
2157 def f(value):
2158 (n1, n2) = value
2159 assert n1 <= n2
2161@composite cannot mix test code and generation code. If you need that, use
2162|st.data|.
2164If :func:`@composite <hypothesis.strategies.composite>` is used to decorate a
2165method or classmethod, the ``draw`` argument must come before ``self`` or
2166``cls``. While we therefore recommend writing strategies as standalone functions
2167and using |st.register_type_strategy| to associate them with a class, methods
2168are supported and the ``@composite`` decorator may be applied either before or
2169after ``@classmethod`` or ``@staticmethod``. See :issue:`2578` and :pull:`2634`
2170for more details.
2172Examples from this strategy shrink by shrinking the output of each draw call.
2173"""
2174if typing.TYPE_CHECKING or ParamSpec is not None:
2175 P = ParamSpec("P")
2177 def composite(
2178 f: Callable[Concatenate[DrawFn, P], Ex],
2179 ) -> Callable[P, SearchStrategy[Ex]]:
2180 return _composite(f)
2182else: # pragma: no cover
2184 @cacheable
2185 def composite(f: Callable[..., Ex]) -> Callable[..., SearchStrategy[Ex]]:
2186 return _composite(f)
2189composite.__doc__ = composite_doc
2192@defines_strategy(force_reusable_values=True)
2193@cacheable
2194def complex_numbers(
2195 *,
2196 min_magnitude: Real = 0,
2197 max_magnitude: Real | None = None,
2198 allow_infinity: bool | None = None,
2199 allow_nan: bool | None = None,
2200 allow_subnormal: bool = True,
2201 width: Literal[32, 64, 128] = 128,
2202) -> SearchStrategy[complex]:
2203 """Returns a strategy that generates :class:`~python:complex`
2204 numbers.
2206 This strategy draws complex numbers with constrained magnitudes.
2207 The ``min_magnitude`` and ``max_magnitude`` parameters should be
2208 non-negative :class:`~python:numbers.Real` numbers; a value
2209 of ``None`` corresponds an infinite upper bound.
2211 If ``min_magnitude`` is nonzero or ``max_magnitude`` is finite, it
2212 is an error to enable ``allow_nan``. If ``max_magnitude`` is finite,
2213 it is an error to enable ``allow_infinity``.
2215 ``allow_infinity``, ``allow_nan``, and ``allow_subnormal`` are
2216 applied to each part of the complex number separately, as for
2217 :func:`~hypothesis.strategies.floats`.
2219 The magnitude constraints are respected up to a relative error
2220 of (around) floating-point epsilon, due to implementation via
2221 the system ``sqrt`` function.
2223 The ``width`` argument specifies the maximum number of bits of precision
2224 required to represent the entire generated complex number.
2225 Valid values are 32, 64 or 128, which correspond to the real and imaginary
2226 components each having width 16, 32 or 64, respectively.
2227 Passing ``width=64`` will still use the builtin 128-bit
2228 :class:`~python:complex` class, but always for values which can be
2229 exactly represented as two 32-bit floats.
2231 Examples from this strategy shrink by shrinking their real and
2232 imaginary parts, as :func:`~hypothesis.strategies.floats`.
2234 If you need to generate complex numbers with particular real and
2235 imaginary parts or relationships between parts, consider using
2236 :func:`builds(complex, ...) <hypothesis.strategies.builds>` or
2237 :func:`@composite <hypothesis.strategies.composite>` respectively.
2238 """
2239 check_valid_magnitude(min_magnitude, "min_magnitude")
2240 check_valid_magnitude(max_magnitude, "max_magnitude")
2241 check_valid_interval(min_magnitude, max_magnitude, "min_magnitude", "max_magnitude")
2242 if max_magnitude == math.inf:
2243 max_magnitude = None
2245 if allow_infinity is None:
2246 allow_infinity = bool(max_magnitude is None)
2247 elif allow_infinity and max_magnitude is not None:
2248 raise InvalidArgument(f"Cannot have {allow_infinity=} with {max_magnitude=}")
2249 if allow_nan is None:
2250 allow_nan = bool(min_magnitude == 0 and max_magnitude is None)
2251 elif allow_nan and not (min_magnitude == 0 and max_magnitude is None):
2252 raise InvalidArgument(
2253 f"Cannot have {allow_nan=}, {min_magnitude=}, {max_magnitude=}"
2254 )
2255 check_type(bool, allow_subnormal, "allow_subnormal")
2256 if width not in (32, 64, 128):
2257 raise InvalidArgument(
2258 f"{width=}, but must be 32, 64 or 128 (other complex dtypes "
2259 "such as complex192 or complex256 are not supported)"
2260 # For numpy, these types would be supported (but not by CPython):
2261 # https://numpy.org/doc/stable/reference/arrays.scalars.html#complex-floating-point-types
2262 )
2263 component_width = width // 2
2264 allow_kw = {
2265 "allow_nan": allow_nan,
2266 "allow_infinity": allow_infinity,
2267 # If we have a nonzero normal min_magnitude and draw a zero imaginary part,
2268 # then allow_subnormal=True would be an error with the min_value to the floats()
2269 # strategy for the real part. We therefore replace True with None.
2270 "allow_subnormal": None if allow_subnormal else allow_subnormal,
2271 "width": component_width,
2272 }
2274 if min_magnitude == 0 and max_magnitude is None:
2275 # In this simple but common case, there are no constraints on the
2276 # magnitude and therefore no relationship between the real and
2277 # imaginary parts.
2278 return builds(complex, floats(**allow_kw), floats(**allow_kw)) # type: ignore
2280 @composite
2281 def constrained_complex(draw):
2282 # We downcast drawn floats to the desired (component) width so we
2283 # guarantee the resulting complex values are representable. Note
2284 # truncating the mantissa bits with float_of() cannot increase the
2285 # magnitude of a float, so we are guaranteed to stay within the allowed
2286 # range. See https://github.com/HypothesisWorks/hypothesis/issues/3573
2288 # Draw the imaginary part, and determine the maximum real part given
2289 # this and the max_magnitude
2290 if max_magnitude is None:
2291 zi = draw(floats(**allow_kw))
2292 rmax = None
2293 else:
2294 zi = draw(
2295 floats(
2296 -float_of(max_magnitude, component_width),
2297 float_of(max_magnitude, component_width),
2298 **allow_kw,
2299 )
2300 )
2301 rmax = float_of(cathetus(max_magnitude, zi), component_width)
2302 # Draw the real part from the allowed range given the imaginary part
2303 if min_magnitude == 0 or math.fabs(zi) >= min_magnitude:
2304 zr = draw(floats(None if rmax is None else -rmax, rmax, **allow_kw))
2305 else:
2306 rmin = float_of(cathetus(min_magnitude, zi), component_width)
2307 zr = draw(floats(rmin, rmax, **allow_kw))
2308 # Order of conditions carefully tuned so that for a given pair of
2309 # magnitude arguments, we always either draw or do not draw the bool
2310 # (crucial for good shrinking behaviour) but only invert when needed.
2311 if min_magnitude > 0 and draw(booleans()) and math.fabs(zi) <= min_magnitude:
2312 zr = -zr
2313 return complex(zr, zi)
2315 return constrained_complex()
2318@defines_strategy(eager=True)
2319def shared(
2320 base: SearchStrategy[Ex],
2321 *,
2322 key: Hashable | None = None,
2323) -> SearchStrategy[Ex]:
2324 """Returns a strategy that draws a single shared value per run, drawn from
2325 base. Any two shared instances with the same key will share the same value,
2326 otherwise the identity of this strategy will be used. That is:
2328 >>> s = integers() # or any other strategy
2329 >>> x = shared(s)
2330 >>> y = shared(s)
2332 In the above x and y may draw different (or potentially the same) values.
2333 In the following they will always draw the same:
2335 >>> x = shared(s, key="hi")
2336 >>> y = shared(s, key="hi")
2338 Examples from this strategy shrink as per their base strategy.
2339 """
2340 return SharedStrategy(base, key)
2343@composite
2344def _maybe_nil_uuids(draw, uuid):
2345 # Equivalent to `random_uuids | just(...)`, with a stronger bias to the former.
2346 if draw(data()).conjecture_data.draw_boolean(1 / 64):
2347 return UUID("00000000-0000-0000-0000-000000000000")
2348 return uuid
2351@cacheable
2352@defines_strategy(force_reusable_values=True)
2353def uuids(
2354 *, version: Literal[1, 2, 3, 4, 5] | None = None, allow_nil: bool = False
2355) -> SearchStrategy[UUID]:
2356 """Returns a strategy that generates :class:`UUIDs <uuid.UUID>`.
2358 If the optional version argument is given, value is passed through
2359 to :class:`~python:uuid.UUID` and only UUIDs of that version will
2360 be generated.
2362 If ``allow_nil`` is True, generate the nil UUID much more often.
2363 Otherwise, all returned values from this will be unique, so e.g. if you do
2364 ``lists(uuids())`` the resulting list will never contain duplicates.
2366 Examples from this strategy don't have any meaningful shrink order.
2367 """
2368 check_type(bool, allow_nil, "allow_nil")
2369 if version not in (None, 1, 2, 3, 4, 5):
2370 raise InvalidArgument(
2371 f"{version=}, but version must be in "
2372 "(None, 1, 2, 3, 4, 5) to pass to the uuid.UUID constructor."
2373 )
2374 random_uuids = shared(
2375 randoms(use_true_random=True), key="hypothesis.strategies.uuids.generator"
2376 ).map(lambda r: UUID(version=version, int=r.getrandbits(128)))
2378 if allow_nil:
2379 if version is not None:
2380 raise InvalidArgument("The nil UUID is not of any version")
2381 return random_uuids.flatmap(_maybe_nil_uuids)
2382 return random_uuids
2385class RunnerStrategy(SearchStrategy):
2386 def __init__(self, default):
2387 super().__init__()
2388 self.default = default
2390 def do_draw(self, data):
2391 if data.hypothesis_runner is not_set:
2392 if self.default is not_set:
2393 raise InvalidArgument(
2394 "Cannot use runner() strategy with no "
2395 "associated runner or explicit default."
2396 )
2397 return self.default
2398 return data.hypothesis_runner
2401@defines_strategy(force_reusable_values=True)
2402def runner(*, default: Any = not_set) -> SearchStrategy[Any]:
2403 """A strategy for getting "the current test runner", whatever that may be.
2404 The exact meaning depends on the entry point, but it will usually be the
2405 associated 'self' value for it.
2407 If you are using this in a rule for stateful testing, this strategy
2408 will return the instance of the :class:`~hypothesis.stateful.RuleBasedStateMachine`
2409 that the rule is running for.
2411 If there is no current test runner and a default is provided, return
2412 that default. If no default is provided, raises InvalidArgument.
2414 Examples from this strategy do not shrink (because there is only one).
2415 """
2416 return RunnerStrategy(default)
2419class DataObject:
2420 """This type only exists so that you can write type hints for tests using
2421 the :func:`~hypothesis.strategies.data` strategy. Do not use it directly!
2422 """
2424 # Note that "only exists" here really means "is only exported to users",
2425 # but we want to treat it as "semi-stable", not document it as "public API".
2427 def __init__(self, data: ConjectureData) -> None:
2428 self.count = 0
2429 self.conjecture_data = data
2431 __signature__ = Signature() # hide internals from Sphinx introspection
2433 def __repr__(self) -> str:
2434 return "data(...)"
2436 def draw(self, strategy: SearchStrategy[Ex], label: Any = None) -> Ex:
2437 """Like :obj:`~hypothesis.strategies.DrawFn`."""
2438 check_strategy(strategy, "strategy")
2439 self.count += 1
2440 desc = f"Draw {self.count}{'' if label is None else f' ({label})'}"
2441 with (
2442 self.conjecture_data.track_arg_span() as span_index,
2443 deprecate_random_in_strategy("{}from {!r}", desc, strategy),
2444 ):
2445 result = self.conjecture_data.draw(strategy, observe_as=f"generate:{desc}")
2447 # optimization to avoid needless printer.pretty
2448 if should_note():
2449 printer = RepresentationPrinter(context=current_build_context())
2450 printer.text(f"{desc}: ")
2451 if self.conjecture_data.provider.avoid_realization:
2452 printer.text("<symbolic>")
2453 else:
2454 printer.pretty(result)
2455 if comment := self.conjecture_data.span_comments.get(span_index):
2456 printer.text(f" # {comment}")
2457 note(printer.getvalue())
2458 return result
2461class DataStrategy(SearchStrategy):
2462 def do_draw(self, data):
2463 if data._shared_data_strategy is None:
2464 data._shared_data_strategy = DataObject(data)
2465 return data._shared_data_strategy
2467 def __repr__(self) -> str:
2468 return "data()"
2470 def map(self, f):
2471 self.__not_a_first_class_strategy("map")
2473 def filter(self, condition: Callable[[Ex], Any]) -> NoReturn:
2474 self.__not_a_first_class_strategy("filter")
2476 def flatmap(self, f):
2477 self.__not_a_first_class_strategy("flatmap")
2479 def example(self) -> NoReturn:
2480 self.__not_a_first_class_strategy("example")
2482 def __not_a_first_class_strategy(self, name: str) -> NoReturn:
2483 raise InvalidArgument(
2484 f"Cannot call {name} on a DataStrategy. You should probably "
2485 "be using @composite for whatever it is you're trying to do."
2486 )
2489@cacheable
2490@defines_strategy(eager=True)
2491def data() -> SearchStrategy[DataObject]:
2492 """
2493 Provides an object ``data`` with a ``data.draw`` function which acts like
2494 the ``draw`` callable provided by |st.composite|, in that it can be used
2495 to dynamically draw values from strategies. |st.data| is more powerful
2496 than |st.composite|, because it allows you to mix generation and test code.
2498 Here's an example of dynamically generating values using |st.data|:
2500 .. code-block:: python
2502 from hypothesis import strategies as st, given
2504 @given(st.data())
2505 def test_values(data):
2506 n1 = data.draw(st.integers())
2507 n2 = data.draw(st.integers(min_value=n1))
2508 assert n1 + 1 <= n2
2510 If the test fails, each draw will be printed with the |minimal failing test case|.
2511 e.g. the above is wrong (it has a boundary condition error), so will print:
2513 .. code-block:: pycon
2515 Failing test case: test_values(data=data(...))
2516 Draw 1: 0
2517 Draw 2: 0
2519 Optionally, you can provide a label to identify values generated by each call
2520 to ``data.draw()``. These labels can be used to identify values in the
2521 output of a failing test case.
2523 For instance:
2525 .. code-block:: python
2527 @given(st.data())
2528 def test_draw_sequentially(data):
2529 x = data.draw(st.integers(), label="First number")
2530 y = data.draw(st.integers(min_value=x), label="Second number")
2531 assert x < y
2533 will produce:
2535 .. code-block:: pycon
2537 Failing test case: test_draw_sequentially(data=data(...))
2538 Draw 1 (First number): 0
2539 Draw 2 (Second number): 0
2541 Examples from this strategy shrink by shrinking the output of each draw call.
2542 """
2543 return DataStrategy()
2546if sys.version_info < (3, 12):
2547 # TypeAliasType is new in 3.12
2548 RegisterTypeT: TypeAlias = type[Ex]
2549else:
2550 from typing import TypeAliasType
2552 # see https://github.com/HypothesisWorks/hypothesis/issues/4410
2553 RegisterTypeT: TypeAlias = type[Ex] | TypeAliasType
2556def register_type_strategy(
2557 custom_type: RegisterTypeT,
2558 strategy: SearchStrategy[Ex] | Callable[[type[Ex]], SearchStrategy[Ex]],
2559) -> None:
2560 """Add an entry to the global type-to-strategy lookup.
2562 This lookup is used in :func:`~hypothesis.strategies.builds` and
2563 |@given|.
2565 :func:`~hypothesis.strategies.builds` will be used automatically for
2566 classes with type annotations on ``__init__`` , so you only need to
2567 register a strategy if one or more arguments need to be more tightly
2568 defined than their type-based default, or if you want to supply a strategy
2569 for an argument with a default value.
2571 ``strategy`` may be a search strategy, or a function that takes a type and
2572 returns a strategy (useful for generic types). The function may return
2573 :data:`NotImplemented` to conditionally not provide a strategy for the type
2574 (the type will still be resolved by other methods, if possible, as if the
2575 function was not registered).
2577 Note that you may not register a parametrised generic type (such as
2578 ``MyCollection[int]``) directly, because the resolution logic does not
2579 handle this case correctly. Instead, you may register a *function* for
2580 ``MyCollection`` and `inspect the type parameters within that function
2581 <https://stackoverflow.com/q/48572831>`__.
2582 """
2583 # TODO: We would like to move this to the top level, but pending some major
2584 # refactoring it's hard to do without creating circular imports.
2585 from hypothesis.strategies._internal import types
2587 if not types.is_a_type(custom_type):
2588 raise InvalidArgument(f"{custom_type=} must be a type")
2589 if custom_type in types.NON_RUNTIME_TYPES:
2590 raise InvalidArgument(
2591 f"{custom_type=} is not allowed to be registered, "
2592 f"because there is no such thing as a runtime instance of {custom_type!r}"
2593 )
2594 if not (isinstance(strategy, SearchStrategy) or callable(strategy)):
2595 raise InvalidArgument(
2596 f"{strategy=} must be a SearchStrategy, or a function that takes "
2597 "a generic type and returns a specific SearchStrategy"
2598 )
2599 if isinstance(strategy, SearchStrategy):
2600 with warnings.catch_warnings():
2601 warnings.simplefilter("error", HypothesisSideeffectWarning)
2603 # Calling is_empty forces materialization of lazy strategies. If this is done at import
2604 # time, lazy strategies will warn about it; here, we force that warning to raise to
2605 # avoid the materialization. Ideally, we'd just check if the strategy is lazy, but the
2606 # lazy strategy may be wrapped underneath another strategy so that's complicated.
2607 try:
2608 if strategy.is_empty:
2609 raise InvalidArgument(f"{strategy=} must not be empty")
2610 except HypothesisSideeffectWarning: # pragma: no cover
2611 pass
2612 if types.has_type_arguments(custom_type):
2613 raise InvalidArgument(
2614 f"Cannot register generic type {custom_type!r}, because it has type "
2615 "arguments which would not be handled. Instead, register a function "
2616 f"for {get_origin(custom_type)!r} which can inspect specific type "
2617 "objects and return a strategy."
2618 )
2619 if (
2620 "pydantic.generics" in sys.modules
2621 and isinstance(custom_type, type)
2622 and issubclass(custom_type, sys.modules["pydantic.generics"].GenericModel)
2623 and not re.search(r"[A-Za-z_]+\[.+\]", repr(custom_type))
2624 and callable(strategy)
2625 ): # pragma: no cover
2626 # See https://github.com/HypothesisWorks/hypothesis/issues/2940
2627 raise InvalidArgument(
2628 f"Cannot register a function for {custom_type!r}, because parametrized "
2629 "`pydantic.generics.GenericModel` subclasses aren't actually generic "
2630 "types at runtime. In this case, you should register a strategy "
2631 "directly for each parametrized form that you anticipate using."
2632 )
2634 types._global_type_lookup[custom_type] = strategy
2635 from_type.__clear_cache() # type: ignore
2638@cacheable
2639@defines_strategy(eager=True)
2640def deferred(definition: Callable[[], SearchStrategy[Ex]]) -> SearchStrategy[Ex]:
2641 """A deferred strategy allows you to write a strategy that references other
2642 strategies that have not yet been defined. This allows for the easy
2643 definition of recursive and mutually recursive strategies.
2645 The definition argument should be a zero-argument function that returns a
2646 strategy. It will be evaluated the first time the strategy is used to
2647 produce an example.
2649 Example usage:
2651 >>> import hypothesis.strategies as st
2652 >>> x = st.deferred(lambda: st.booleans() | st.tuples(x, x))
2653 >>> x.example()
2654 (((False, (True, True)), (False, True)), (True, True))
2655 >>> x.example()
2656 True
2658 Mutual recursion also works fine:
2660 >>> a = st.deferred(lambda: st.booleans() | b)
2661 >>> b = st.deferred(lambda: st.tuples(a, a))
2662 >>> a.example()
2663 True
2664 >>> b.example()
2665 (False, (False, ((False, True), False)))
2667 Examples from this strategy shrink as they normally would from the strategy
2668 returned by the definition.
2669 """
2670 return DeferredStrategy(definition)
2673def domains() -> SearchStrategy[str]:
2674 import hypothesis.provisional
2676 return hypothesis.provisional.domains()
2679@defines_strategy(force_reusable_values=True)
2680def emails(
2681 *, domains: SearchStrategy[str] = LazyStrategy(domains, (), {})
2682) -> SearchStrategy[str]:
2683 """A strategy for generating email addresses as unicode strings. The
2684 address format is specified in :rfc:`5322#section-3.4.1`. Values shrink
2685 towards shorter local-parts and host domains.
2687 If ``domains`` is given then it must be a strategy that generates domain
2688 names for the emails, defaulting to :func:`~hypothesis.provisional.domains`.
2690 This strategy is useful for generating "user data" for tests, as
2691 mishandling of email addresses is a common source of bugs.
2692 """
2693 local_chars = string.ascii_letters + string.digits + "!#$%&'*+-/=^_`{|}~"
2694 local_part = text(local_chars, min_size=1, max_size=64)
2695 # TODO: include dot-atoms, quoted strings, escaped chars, etc in local part
2696 return builds("{}@{}".format, local_part, domains).filter(
2697 lambda addr: len(addr) <= 254
2698 )
2701def _functions(*, like, returns, pure):
2702 # Wrapped up to use ParamSpec below
2703 check_type(bool, pure, "pure")
2704 if not callable(like):
2705 raise InvalidArgument(
2706 "The first argument to functions() must be a callable to imitate, "
2707 f"but got non-callable like={nicerepr(like)!r}"
2708 )
2709 if pure and (
2710 iscoroutinefunction(like)
2711 or isgeneratorfunction(like)
2712 or isasyncgenfunction(like)
2713 ):
2714 raise InvalidArgument(
2715 f"pure=True is invalid for like={nicerepr(like)!r}, because async "
2716 "functions are for non-deterministic IO and generators are consumed "
2717 "by iteration, so returning a cached value makes no sense"
2718 )
2719 is_gen = isgeneratorfunction(like) or isasyncgenfunction(like)
2720 if returns in (None, ...):
2721 hints = get_type_hints(like)
2722 if is_gen:
2723 # The return annotation describes the iterator, so e.g. yield
2724 # integers for `-> Iterator[int]` or `-> AsyncIterator[int]`.
2725 allowed = (
2726 (AsyncIterator, AsyncIterable, AsyncGenerator)
2727 if isasyncgenfunction(like)
2728 else (Iterator, Iterable, Generator)
2729 )
2730 ret = hints.get("return")
2731 # normalize eg Iterator[bool] to Iterator while keeping Iterator as Iterator.
2732 kind = get_origin(ret) or ret
2733 if ret is not None and kind not in allowed:
2734 options = ", ".join(t.__name__ for t in allowed)
2735 raise InvalidArgument(
2736 f"Cannot infer the yield type of like={nicerepr(like)!r} "
2737 f"from its return annotation {ret!r}. Expected one of "
2738 f"{options}. Alternatively, pass returns= to specify the yield type "
2739 "explicitly."
2740 )
2741 args = get_args(ret)
2742 returns = from_type(args[0]) if args else none()
2743 else:
2744 # Passing `None` has never been *documented* as working, but it
2745 # still did from May 2020 to Jan 2022 so we'll avoid breaking it
2746 # without cause.
2747 returns = from_type(hints.get("return", type(None)))
2748 check_strategy(returns, "returns")
2749 if is_gen:
2750 # Generated generator functions draw a list of values to yield up front.
2751 returns = lists(returns)
2752 return FunctionStrategy(like, returns, pure)
2755if typing.TYPE_CHECKING or ParamSpec is not None:
2757 @overload
2758 def functions(*, pure: bool = ...) -> SearchStrategy[Callable[[], None]]: ...
2760 @overload
2761 def functions(
2762 *,
2763 like: Callable[P, T],
2764 pure: bool = ...,
2765 ) -> SearchStrategy[Callable[P, T]]: ...
2767 @overload
2768 def functions(
2769 *,
2770 returns: SearchStrategy[T],
2771 pure: bool = ...,
2772 ) -> SearchStrategy[Callable[[], T]]: ...
2774 @overload
2775 def functions(
2776 *,
2777 like: Callable[P, Any],
2778 returns: SearchStrategy[T],
2779 pure: bool = ...,
2780 ) -> SearchStrategy[Callable[P, T]]: ...
2782 @defines_strategy()
2783 def functions(*, like=lambda: None, returns=..., pure=False):
2784 # We shouldn't need overloads here, but mypy disallows default args for
2785 # generics: https://github.com/python/mypy/issues/3737
2786 """functions(*, like=lambda: None, returns=..., pure=False)
2788 A strategy for functions, which can be used in callbacks.
2790 The generated functions will mimic the interface of ``like``, which must
2791 be a callable (including a class, method, or function). The return value
2792 for the function is drawn from the ``returns`` argument, which must be a
2793 strategy. If ``returns`` is not passed, we attempt to infer a strategy
2794 from the return-type annotation if present, falling back to :func:`~none`.
2796 If ``like`` is an async function, a generator function, or an async
2797 generator function, the generated function will be of the same kind.
2798 Awaiting a generated async function returns a value drawn from
2799 ``returns``, while generated generator functions draw a list of
2800 values from ``returns`` up front and then yield from it - so a
2801 return-type annotation like ``Iterator[int]`` or ``AsyncIterator[int]``
2802 means we infer ``returns=integers()``. ``pure=True`` is only
2803 supported when ``like`` is a plain function.
2805 Generated async functions and async generators follow Trio-style
2806 checkpoint semantics, using :pypi:`anyio` or :pypi:`sniffio` if
2807 imported to find the right way to checkpoint, and falling back to
2808 :mod:`asyncio` otherwise.
2810 If ``pure=True``, all arguments passed to the generated function must be
2811 hashable, and if passed identical arguments the original return value will
2812 be returned again - *not* regenerated, so beware mutable values.
2814 If ``pure=False``, generated functions do not validate their arguments, and
2815 may return a different value if called again with the same arguments.
2817 Generated functions can only be called within the scope of the ``@given``
2818 which created them.
2819 """
2820 return _functions(like=like, returns=returns, pure=pure)
2822else: # pragma: no cover
2824 @defines_strategy()
2825 def functions(
2826 *,
2827 like: Callable[..., Any] = lambda: None,
2828 returns: SearchStrategy[Any] | EllipsisType = ...,
2829 pure: bool = False,
2830 ) -> SearchStrategy[Callable[..., Any]]:
2831 """functions(*, like=lambda: None, returns=..., pure=False)
2833 A strategy for functions, which can be used in callbacks.
2835 The generated functions will mimic the interface of ``like``, which must
2836 be a callable (including a class, method, or function). The return value
2837 for the function is drawn from the ``returns`` argument, which must be a
2838 strategy. If ``returns`` is not passed, we attempt to infer a strategy
2839 from the return-type annotation if present, falling back to :func:`~none`.
2841 If ``like`` is an async function, a generator function, or an async
2842 generator function, the generated function will be of the same kind.
2843 Awaiting a generated async function returns a value drawn from
2844 ``returns``, while generated generator functions draw a list of
2845 values from ``returns`` up front and then yield from it - so a
2846 return-type annotation like ``Iterator[int]`` or ``AsyncIterator[int]``
2847 means we infer ``returns=integers()``. ``pure=True`` is only
2848 supported when ``like`` is a plain function.
2850 Generated async functions and async generators follow Trio-style
2851 checkpoint semantics, using :pypi:`anyio` or :pypi:`sniffio` if
2852 imported to find the right way to checkpoint, and falling back to
2853 :mod:`asyncio` otherwise.
2855 If ``pure=True``, all arguments passed to the generated function must be
2856 hashable, and if passed identical arguments the original return value will
2857 be returned again - *not* regenerated, so beware mutable values.
2859 If ``pure=False``, generated functions do not validate their arguments, and
2860 may return a different value if called again with the same arguments.
2862 Generated functions can only be called within the scope of the ``@given``
2863 which created them.
2864 """
2865 return _functions(like=like, returns=returns, pure=pure)
2868@composite
2869def slices(draw: Any, size: int) -> slice:
2870 """Generates slices that will select indices up to the supplied size
2872 Generated slices will have start and stop indices that range from -size to size - 1
2873 and will step in the appropriate direction. Slices should only produce an empty selection
2874 if the start and end are the same.
2876 Examples from this strategy shrink toward 0 and smaller values
2877 """
2878 check_valid_size(size, "size")
2879 if size == 0:
2880 step = draw(none() | integers().filter(bool))
2881 return slice(None, None, step)
2882 # For slices start is inclusive and stop is exclusive
2883 start = draw(integers(0, size - 1) | none())
2884 stop = draw(integers(0, size) | none())
2886 # Limit step size to be reasonable
2887 if start is None and stop is None:
2888 max_step = size
2889 elif start is None:
2890 max_step = stop
2891 elif stop is None:
2892 max_step = start
2893 else:
2894 max_step = abs(start - stop)
2896 step = draw(integers(1, max_step or 1))
2898 if (draw(booleans()) and start == stop) or (stop or 0) < (start or 0):
2899 step *= -1
2901 if draw(booleans()) and start is not None:
2902 start -= size
2903 if draw(booleans()) and stop is not None:
2904 stop -= size
2905 if (not draw(booleans())) and step == 1:
2906 step = None
2908 return slice(start, stop, step)