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