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