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 Callable, 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 EllipsisType, FunctionType, GenericAlias
29from typing import (
30 Annotated,
31 Any,
32 AnyStr,
33 Concatenate,
34 Literal,
35 NewType,
36 NoReturn,
37 ParamSpec,
38 Protocol,
39 TypeAlias,
40 TypeVar,
41 cast,
42 get_args,
43 get_origin,
44 overload,
45)
46from uuid import UUID
48from hypothesis._settings import note_deprecation
49from hypothesis.control import (
50 cleanup,
51 current_build_context,
52 deprecate_random_in_strategy,
53 note,
54 should_note,
55)
56from hypothesis.errors import (
57 HypothesisSideeffectWarning,
58 HypothesisWarning,
59 InvalidArgument,
60 ResolutionFailed,
61 RewindRecursive,
62 SmallSearchSpaceWarning,
63)
64from hypothesis.internal.cathetus import cathetus
65from hypothesis.internal.charmap import (
66 Categories,
67 CategoryName,
68 as_general_categories,
69 categories as all_categories,
70)
71from hypothesis.internal.compat import (
72 bit_count,
73 ceil,
74 floor,
75 get_type_hints,
76 is_typed_named_tuple,
77)
78from hypothesis.internal.conjecture.data import ConjectureData
79from hypothesis.internal.conjecture.utils import (
80 calc_label_from_callable,
81 calc_label_from_name,
82 check_sample,
83 combine_labels,
84 identity,
85)
86from hypothesis.internal.entropy import get_seeder_and_restorer
87from hypothesis.internal.floats import float_of
88from hypothesis.internal.reflection import (
89 define_function_signature,
90 get_pretty_function_description,
91 get_signature,
92 is_first_param_referenced_in_function,
93 nicerepr,
94 repr_call,
95 required_args,
96)
97from hypothesis.internal.validation import (
98 check_type,
99 check_valid_integer,
100 check_valid_interval,
101 check_valid_magnitude,
102 check_valid_size,
103 check_valid_sizes,
104 try_convert,
105)
106from hypothesis.strategies._internal import SearchStrategy, check_strategy
107from hypothesis.strategies._internal.collections import (
108 FixedDictStrategy,
109 ListStrategy,
110 TupleStrategy,
111 UniqueListStrategy,
112 UniqueSampledListStrategy,
113 tuples,
114)
115from hypothesis.strategies._internal.deferred import DeferredStrategy
116from hypothesis.strategies._internal.functions import FunctionStrategy
117from hypothesis.strategies._internal.lazy import LazyStrategy, unwrap_strategies
118from hypothesis.strategies._internal.misc import BooleansStrategy, just, none, nothing
119from hypothesis.strategies._internal.numbers import (
120 IntegersStrategy,
121 Real,
122 floats,
123 integers,
124)
125from hypothesis.strategies._internal.recursive import RecursiveStrategy
126from hypothesis.strategies._internal.shared import SharedStrategy
127from hypothesis.strategies._internal.strategies import (
128 Ex,
129 SampledFromStrategy,
130 T,
131 one_of,
132)
133from hypothesis.strategies._internal.strings import (
134 BytesStrategy,
135 OneCharStringStrategy,
136 TextStrategy,
137 _check_is_single_character,
138)
139from hypothesis.strategies._internal.utils import cacheable, defines_strategy
140from hypothesis.utils.conventions import not_set
141from hypothesis.vendor.pretty import RepresentationPrinter
144@cacheable
145@defines_strategy(force_reusable_values=True)
146def booleans() -> SearchStrategy[bool]:
147 """Returns a strategy which generates instances of :class:`python:bool`.
149 Examples from this strategy will shrink towards ``False`` (i.e.
150 shrinking will replace ``True`` with ``False`` where possible).
151 """
152 return BooleansStrategy()
155@overload
156def sampled_from(elements: Sequence[T]) -> SearchStrategy[T]: # pragma: no cover
157 ...
160@overload
161def sampled_from(elements: type[enum.Enum]) -> SearchStrategy[Any]: # pragma: no cover
162 # `SearchStrategy[Enum]` is unreliable due to metaclass issues.
163 ...
166@overload
167def sampled_from(
168 elements: type[enum.Enum] | Sequence[Any],
169) -> SearchStrategy[Any]: # pragma: no cover
170 ...
173@defines_strategy(eager="try")
174def sampled_from(
175 elements: type[enum.Enum] | Sequence[Any],
176) -> SearchStrategy[Any]:
177 """Returns a strategy which generates any value present in ``elements``.
179 Note that as with :func:`~hypothesis.strategies.just`, values will not be
180 copied and thus you should be careful of using mutable data.
182 ``sampled_from`` supports ordered collections, as well as
183 :class:`~python:enum.Enum` objects. :class:`~python:enum.Flag` objects
184 may also generate any combination of their members.
186 Examples from this strategy shrink by replacing them with values earlier in
187 the list. So e.g. ``sampled_from([10, 1])`` will shrink by trying to replace
188 1 values with 10, and ``sampled_from([1, 10])`` will shrink by trying to
189 replace 10 values with 1.
191 It is an error to sample from an empty sequence, because returning :func:`nothing`
192 makes it too easy to silently drop parts of compound strategies. If you need
193 that behaviour, use ``sampled_from(seq) if seq else nothing()``.
194 """
195 values = check_sample(elements, "sampled_from")
196 force_repr = None
197 # check_sample converts to tuple unconditionally, but we want to preserve
198 # square braces for list reprs.
199 # This will not cover custom sequence implementations which return different
200 # braces (or other, more unusual things) for their reprs, but this is a tradeoff
201 # between repr accuracy and greedily-evaluating all sequence reprs (at great
202 # cost for large sequences).
203 force_repr_braces = ("[", "]") if isinstance(elements, list) else None
204 if isinstance(elements, type) and issubclass(elements, enum.Enum):
205 force_repr = f"sampled_from({elements.__module__}.{elements.__name__})"
207 if isclass(elements) and issubclass(elements, enum.Flag):
208 # Combinations of enum.Flag members (including empty) are also members. We generate these
209 # dynamically, because static allocation takes O(2^n) memory. LazyStrategy is used for the
210 # ease of force_repr.
211 # Add all named values, both flag bits (== list(elements)) and aliases. The aliases are
212 # necessary for full coverage for flags that would fail enum.NAMED_FLAGS check, and they
213 # are also nice values to shrink to.
214 flags = sorted(
215 set(elements.__members__.values()),
216 key=lambda v: (bit_count(v.value), v.value),
217 )
218 # Finally, try to construct the empty state if it is not named. It's placed at the
219 # end so that we shrink to named values.
220 flags_with_empty = flags
221 if not flags or flags[0].value != 0:
222 try:
223 flags_with_empty = [*flags, elements(0)]
224 except TypeError: # pragma: no cover
225 # Happens on some python versions (at least 3.12) when there are no named values
226 pass
227 inner = [
228 # Consider one or no named flags set, with shrink-to-named-flag behaviour.
229 # Special cases (length zero or one) are handled by the inner sampled_from.
230 sampled_from(flags_with_empty),
231 ]
232 if len(flags) > 1:
233 inner += [
234 # Uniform distribution over number of named flags or combinations set. The overlap
235 # at r=1 is intentional, it may lead to oversampling but gives consistent shrinking
236 # behaviour.
237 integers(min_value=1, max_value=len(flags))
238 .flatmap(lambda r: sets(sampled_from(flags), min_size=r, max_size=r))
239 .map(lambda s: elements(reduce(operator.or_, s))),
240 ]
241 return LazyStrategy(one_of, args=inner, kwargs={}, force_repr=force_repr)
242 if not values:
244 def has_annotations(elements):
245 if sys.version_info[:2] < (3, 14):
246 return vars(elements).get("__annotations__")
247 else: # pragma: no cover # covered by 3.14 tests
248 import annotationlib
250 return bool(annotationlib.get_annotations(elements))
252 if (
253 isinstance(elements, type)
254 and issubclass(elements, enum.Enum)
255 and has_annotations(elements)
256 ):
257 # See https://github.com/HypothesisWorks/hypothesis/issues/2923
258 raise InvalidArgument(
259 f"Cannot sample from {elements.__module__}.{elements.__name__} "
260 "because it contains no elements. It does however have annotations, "
261 "so maybe you tried to write an enum as if it was a dataclass?"
262 )
263 raise InvalidArgument("Cannot sample from a length-zero sequence.")
264 if len(values) == 1:
265 return just(values[0])
266 return SampledFromStrategy(
267 values, force_repr=force_repr, force_repr_braces=force_repr_braces
268 )
271def _gets_first_item(fn: Callable) -> bool:
272 # Introspection for either `itemgetter(0)`, or `lambda x: x[0]`
273 if isinstance(fn, FunctionType):
274 s = get_pretty_function_description(fn)
275 return bool(re.fullmatch(s, r"lambda ([a-z]+): \1\[0\]"))
276 return isinstance(fn, operator.itemgetter) and repr(fn) == "operator.itemgetter(0)"
279@cacheable
280@defines_strategy()
281def lists(
282 elements: SearchStrategy[Ex],
283 *,
284 min_size: int = 0,
285 max_size: int | None = None,
286 unique_by: (
287 None | Callable[[Ex], Hashable] | tuple[Callable[[Ex], Hashable], ...]
288 ) = None,
289 unique: bool = False,
290) -> SearchStrategy[list[Ex]]:
291 """Returns a list containing values drawn from elements with length in the
292 interval [min_size, max_size] (no bounds in that direction if these are
293 None). If max_size is 0, only the empty list will be drawn.
295 If ``unique`` is True (or something that evaluates to True), we compare direct
296 object equality, as if unique_by was ``lambda x: x``. This comparison only
297 works for hashable types.
299 If ``unique_by`` is not None it must be a callable or tuple of callables
300 returning a hashable type when given a value drawn from elements. The
301 resulting list will satisfy the condition that for ``i`` != ``j``,
302 ``unique_by(result[i])`` != ``unique_by(result[j])``.
304 If ``unique_by`` is a tuple of callables the uniqueness will be respective
305 to each callable.
307 For example, the following will produce two columns of integers with both
308 columns being unique respectively.
310 .. code-block:: pycon
312 >>> twoints = st.tuples(st.integers(), st.integers())
313 >>> st.lists(twoints, unique_by=(lambda x: x[0], lambda x: x[1]))
315 Examples from this strategy shrink by trying to remove elements from the
316 list, and by shrinking each individual element of the list.
317 """
318 check_valid_sizes(min_size, max_size)
319 check_strategy(elements, "elements")
320 if unique:
321 if unique_by is not None:
322 raise InvalidArgument(
323 "cannot specify both unique and unique_by "
324 "(you probably only want to set unique_by)"
325 )
326 else:
327 unique_by = identity
329 if max_size == 0:
330 return builds(list)
331 if unique_by is not None:
332 if not (callable(unique_by) or isinstance(unique_by, tuple)):
333 raise InvalidArgument(
334 f"{unique_by=} is not a callable or tuple of callables"
335 )
336 if callable(unique_by):
337 unique_by = (unique_by,)
338 if len(unique_by) == 0:
339 raise InvalidArgument("unique_by is empty")
340 for i, f in enumerate(unique_by):
341 if not callable(f):
342 raise InvalidArgument(f"unique_by[{i}]={f!r} is not a callable")
343 # Note that lazy strategies automatically unwrap when passed to a defines_strategy
344 # function.
345 tuple_suffixes = None
346 if (
347 # We're generating a list of tuples unique by the first element, perhaps
348 # via st.dictionaries(), and this will be more efficient if we rearrange
349 # our strategy somewhat to draw the first element then draw add the rest.
350 isinstance(elements, TupleStrategy)
351 and len(elements.element_strategies) >= 1
352 and all(_gets_first_item(fn) for fn in unique_by)
353 ):
354 unique_by = (identity,)
355 tuple_suffixes = TupleStrategy(elements.element_strategies[1:])
356 elements = elements.element_strategies[0]
358 # UniqueSampledListStrategy offers a substantial performance improvement for
359 # unique arrays with few possible elements, e.g. of eight-bit integer types.
360 if (
361 isinstance(elements, IntegersStrategy)
362 and elements.start is not None
363 and elements.end is not None
364 and (elements.end - elements.start) <= 255
365 ):
366 elements = SampledFromStrategy(
367 sorted(range(elements.start, elements.end + 1), key=abs) # type: ignore
368 if elements.end < 0 or elements.start > 0
369 else (
370 list(range(elements.end + 1))
371 + list(range(-1, elements.start - 1, -1))
372 )
373 )
375 if isinstance(elements, SampledFromStrategy):
376 element_count = len(elements.elements)
377 if min_size > element_count:
378 raise InvalidArgument(
379 f"Cannot create a collection of {min_size=} unique "
380 f"elements with values drawn from only {element_count} distinct "
381 "elements"
382 )
384 if max_size is not None:
385 max_size = min(max_size, element_count)
386 else:
387 max_size = element_count
389 return UniqueSampledListStrategy(
390 elements=elements,
391 max_size=max_size,
392 min_size=min_size,
393 keys=unique_by,
394 tuple_suffixes=tuple_suffixes,
395 )
397 return UniqueListStrategy(
398 elements=elements,
399 max_size=max_size,
400 min_size=min_size,
401 keys=unique_by,
402 tuple_suffixes=tuple_suffixes,
403 )
404 return ListStrategy(elements, min_size=min_size, max_size=max_size)
407@cacheable
408@defines_strategy()
409def sets(
410 elements: SearchStrategy[Ex],
411 *,
412 min_size: int = 0,
413 max_size: int | None = None,
414) -> SearchStrategy[set[Ex]]:
415 """This has the same behaviour as lists, but returns sets instead.
417 Note that Hypothesis cannot tell if values are drawn from elements
418 are hashable until running the test, so you can define a strategy
419 for sets of an unhashable type but it will fail at test time.
421 Examples from this strategy shrink by trying to remove elements from the
422 set, and by shrinking each individual element of the set.
423 """
424 return lists(
425 elements=elements, min_size=min_size, max_size=max_size, unique=True
426 ).map(set)
429@cacheable
430@defines_strategy()
431def frozensets(
432 elements: SearchStrategy[Ex],
433 *,
434 min_size: int = 0,
435 max_size: int | None = None,
436) -> SearchStrategy[frozenset[Ex]]:
437 """This is identical to the sets function but instead returns
438 frozensets."""
439 return lists(
440 elements=elements, min_size=min_size, max_size=max_size, unique=True
441 ).map(frozenset)
444class PrettyIter:
445 def __init__(self, values):
446 self._values = values
447 self._iter = iter(self._values)
449 def __iter__(self):
450 return self._iter
452 def __next__(self):
453 return next(self._iter)
455 def __repr__(self) -> str:
456 return f"iter({self._values!r})"
459@defines_strategy()
460def iterables(
461 elements: SearchStrategy[Ex],
462 *,
463 min_size: int = 0,
464 max_size: int | None = None,
465 unique_by: (
466 None | Callable[[Ex], Hashable] | tuple[Callable[[Ex], Hashable], ...]
467 ) = None,
468 unique: bool = False,
469) -> SearchStrategy[Iterable[Ex]]:
470 """This has the same behaviour as lists, but returns iterables instead.
472 Some iterables cannot be indexed (e.g. sets) and some do not have a
473 fixed length (e.g. generators). This strategy produces iterators,
474 which cannot be indexed and do not have a fixed length. This ensures
475 that you do not accidentally depend on sequence behaviour.
476 """
477 return lists(
478 elements=elements,
479 min_size=min_size,
480 max_size=max_size,
481 unique_by=unique_by,
482 unique=unique,
483 ).map(PrettyIter)
486# this type definition is imprecise, in multiple ways:
487# * mapping and optional can be of different types:
488# s: dict[str | int, int] = st.fixed_dictionaries(
489# {"a": st.integers()}, optional={1: st.integers()}
490# )
491# * the values in either mapping or optional need not all be of the same type:
492# s: dict[str, int | bool] = st.fixed_dictionaries(
493# {"a": st.integers(), "b": st.booleans()}
494# )
495# * the arguments may be of any dict-compatible type, in which case the return
496# value will be of that type instead of dit
497#
498# Overloads may help here, but I doubt we'll be able to satisfy all these
499# constraints.
500#
501# Here's some platonic ideal test cases for revealed_types.py, with the understanding
502# that some may not be achievable:
503#
504# ("fixed_dictionaries({'a': booleans()})", "dict[str, bool]"),
505# ("fixed_dictionaries({'a': booleans(), 'b': integers()})", "dict[str, bool | int]"),
506# ("fixed_dictionaries({}, optional={'a': booleans()})", "dict[str, bool]"),
507# (
508# "fixed_dictionaries({'a': booleans()}, optional={1: booleans()})",
509# "dict[str | int, bool]",
510# ),
511# (
512# "fixed_dictionaries({'a': booleans()}, optional={1: integers()})",
513# "dict[str | int, bool | int]",
514# ),
517@defines_strategy()
518def fixed_dictionaries(
519 mapping: dict[T, SearchStrategy[Ex]],
520 *,
521 optional: dict[T, SearchStrategy[Ex]] | None = None,
522) -> SearchStrategy[dict[T, Ex]]:
523 """Generates a dictionary of the same type as mapping with a fixed set of
524 keys mapping to strategies. ``mapping`` must be a dict subclass.
526 Generated values have all keys present in mapping, in iteration order,
527 with the corresponding values drawn from mapping[key].
529 If ``optional`` is passed, the generated value *may or may not* contain each
530 key from ``optional`` and a value drawn from the corresponding strategy.
531 Generated values may contain optional keys in an arbitrary order.
533 Examples from this strategy shrink by shrinking each individual value in
534 the generated dictionary, and omitting optional key-value pairs.
535 """
536 check_type(dict, mapping, "mapping")
537 for k, v in mapping.items():
538 check_strategy(v, f"mapping[{k!r}]")
540 if optional is not None:
541 check_type(dict, optional, "optional")
542 for k, v in optional.items():
543 check_strategy(v, f"optional[{k!r}]")
544 if type(mapping) != type(optional):
545 raise InvalidArgument(
546 f"Got arguments of different types: "
547 f"mapping={nicerepr(type(mapping))}, "
548 f"optional={nicerepr(type(optional))}"
549 )
550 if set(mapping) & set(optional):
551 raise InvalidArgument(
552 "The following keys were in both mapping and optional, "
553 f"which is invalid: {set(mapping) & set(optional)!r}"
554 )
556 return FixedDictStrategy(mapping, optional=optional)
559_get_first_item = operator.itemgetter(0)
562@cacheable
563@defines_strategy()
564def dictionaries(
565 keys: SearchStrategy[Ex],
566 values: SearchStrategy[T],
567 *,
568 dict_class: type = dict,
569 min_size: int = 0,
570 max_size: int | None = None,
571) -> SearchStrategy[dict[Ex, T]]:
572 # Describing the exact dict_class to Mypy drops the key and value types,
573 # so we report Dict[K, V] instead of Mapping[Any, Any] for now. Sorry!
574 """Generates dictionaries of type ``dict_class`` with keys drawn from the ``keys``
575 argument and values drawn from the ``values`` argument.
577 The size parameters have the same interpretation as for
578 :func:`~hypothesis.strategies.lists`.
580 Examples from this strategy shrink by trying to remove keys from the
581 generated dictionary, and by shrinking each generated key and value.
582 """
583 check_valid_sizes(min_size, max_size)
584 if max_size == 0:
585 return fixed_dictionaries(dict_class())
586 check_strategy(keys, "keys")
587 check_strategy(values, "values")
589 return lists(
590 tuples(keys, values),
591 min_size=min_size,
592 max_size=max_size,
593 unique_by=_get_first_item,
594 ).map(dict_class)
597@cacheable
598@defines_strategy(force_reusable_values=True)
599def characters(
600 *,
601 codec: str | None = None,
602 min_codepoint: int | None = None,
603 max_codepoint: int | None = None,
604 categories: Collection[CategoryName] | None = None,
605 exclude_categories: Collection[CategoryName] | None = None,
606 exclude_characters: Collection[str] | None = None,
607 include_characters: Collection[str] | None = None,
608 # Note: these arguments are deprecated aliases for backwards compatibility
609 blacklist_categories: Collection[CategoryName] | None = None,
610 whitelist_categories: Collection[CategoryName] | None = None,
611 blacklist_characters: Collection[str] | None = None,
612 whitelist_characters: Collection[str] | None = None,
613) -> SearchStrategy[str]:
614 r"""Generates characters, length-one :class:`python:str`\ ings,
615 following specified filtering rules.
617 - When no filtering rules are specified, any character can be produced.
618 - If ``min_codepoint`` or ``max_codepoint`` is specified, then only
619 characters having a codepoint in that range will be produced.
620 - If ``categories`` is specified, then only characters from those
621 Unicode categories will be produced. This is a further restriction,
622 characters must also satisfy ``min_codepoint`` and ``max_codepoint``.
623 - If ``exclude_categories`` is specified, then any character from those
624 categories will not be produced. You must not pass both ``categories``
625 and ``exclude_categories``; these arguments are alternative ways to
626 specify exactly the same thing.
627 - If ``include_characters`` is specified, then any additional characters
628 in that list will also be produced.
629 - If ``exclude_characters`` is specified, then any characters in
630 that list will be not be produced. Any overlap between
631 ``include_characters`` and ``exclude_characters`` will raise an
632 exception.
633 - If ``codec`` is specified, only characters in the specified `codec encodings`_
634 will be produced.
636 The ``_codepoint`` arguments must be integers between zero and
637 :obj:`python:sys.maxunicode`. The ``_characters`` arguments must be
638 collections of length-one unicode strings, such as a unicode string.
640 The ``_categories`` arguments must be used to specify either the
641 one-letter Unicode major category or the two-letter Unicode
642 `general category`_. For example, ``('Nd', 'Lu')`` signifies "Number,
643 decimal digit" and "Letter, uppercase". A single letter ('major category')
644 can be given to match all corresponding categories, for example ``'P'``
645 for characters in any punctuation category.
647 We allow codecs from the :mod:`codecs` module and their aliases, platform
648 specific and user-registered codecs if they are available, and
649 `python-specific text encodings`_ (but not text or binary transforms).
650 ``include_characters`` which cannot be encoded using this codec will
651 raise an exception. If non-encodable codepoints or categories are
652 explicitly allowed, the ``codec`` argument will exclude them without
653 raising an exception.
655 .. _general category: https://en.wikipedia.org/wiki/Unicode_character_property
656 .. _codec encodings: https://docs.python.org/3/library/codecs.html#encodings-and-unicode
657 .. _python-specific text encodings: https://docs.python.org/3/library/codecs.html#python-specific-encodings
659 Examples from this strategy shrink towards the codepoint for ``'0'``,
660 or the first allowable codepoint after it if ``'0'`` is excluded.
661 """
662 check_valid_size(min_codepoint, "min_codepoint")
663 check_valid_size(max_codepoint, "max_codepoint")
664 check_valid_interval(min_codepoint, max_codepoint, "min_codepoint", "max_codepoint")
665 categories = cast(Categories | None, categories)
666 if categories is not None and exclude_categories is not None:
667 raise InvalidArgument(
668 f"Pass at most one of {categories=} and {exclude_categories=} - "
669 "these arguments both specify which categories are allowed, so it "
670 "doesn't make sense to use both in a single call."
671 )
673 # Handle deprecation of whitelist/blacklist arguments
674 has_old_arg = any(v is not None for k, v in locals().items() if "list" in k)
675 has_new_arg = any(v is not None for k, v in locals().items() if "lude" in k)
676 if has_old_arg and has_new_arg:
677 raise InvalidArgument(
678 "The deprecated blacklist/whitelist arguments cannot be used in "
679 "the same call as their replacement include/exclude arguments."
680 )
681 if blacklist_categories is not None:
682 exclude_categories = blacklist_categories
683 if whitelist_categories is not None:
684 categories = whitelist_categories
685 if blacklist_characters is not None:
686 exclude_characters = blacklist_characters
687 if whitelist_characters is not None:
688 include_characters = whitelist_characters
690 if (
691 min_codepoint is None
692 and max_codepoint is None
693 and categories is None
694 and exclude_categories is None
695 and include_characters is not None
696 and codec is None
697 ):
698 raise InvalidArgument(
699 "Nothing is excluded by other arguments, so passing only "
700 f"{include_characters=} would have no effect. "
701 "Also pass categories=(), or use "
702 f"sampled_from({include_characters!r}) instead."
703 )
704 exclude_characters = exclude_characters or ""
705 include_characters = include_characters or ""
706 if not_one_char := [c for c in exclude_characters if len(c) != 1]:
707 raise InvalidArgument(
708 "Elements of exclude_characters are required to be a single character, "
709 f"but {not_one_char!r} passed in {exclude_characters=} was not."
710 )
711 if not_one_char := [c for c in include_characters if len(c) != 1]:
712 raise InvalidArgument(
713 "Elements of include_characters are required to be a single character, "
714 f"but {not_one_char!r} passed in {include_characters=} was not."
715 )
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: Collection[str] | SearchStrategy[str] = characters(codec="utf-8"),
796 *,
797 min_size: int = 0,
798 max_size: int | None = 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: bytes | Pattern[bytes],
869 *,
870 fullmatch: bool = False,
871) -> SearchStrategy[bytes]: # pragma: no cover
872 ...
875@overload
876def from_regex(
877 regex: str | Pattern[str],
878 *,
879 fullmatch: bool = False,
880 alphabet: str | SearchStrategy[str] = characters(codec="utf-8"),
881) -> SearchStrategy[str]: # pragma: no cover
882 ...
885@cacheable
886@defines_strategy()
887def from_regex(
888 regex: AnyStr | Pattern[AnyStr],
889 *,
890 fullmatch: bool = False,
891 alphabet: 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: int | None = 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 calc_label(self) -> int:
1047 return combine_labels(
1048 self.class_label,
1049 calc_label_from_callable(self.target),
1050 *[strat.label for strat in self.args],
1051 *[calc_label_from_name(k) for k in self.kwargs],
1052 *[strat.label for strat in self.kwargs.values()],
1053 )
1055 def do_draw(self, data: ConjectureData) -> Ex:
1056 args = [data.draw(s) for s in self.args]
1057 kwargs = {k: data.draw(v) for k, v in self.kwargs.items()}
1058 try:
1059 obj = self.target(*args, **kwargs)
1060 except TypeError as err:
1061 if (
1062 isinstance(self.target, type)
1063 and issubclass(self.target, enum.Enum)
1064 and not (self.args or self.kwargs)
1065 ):
1066 name = self.target.__module__ + "." + self.target.__qualname__
1067 raise InvalidArgument(
1068 f"Calling {name} with no arguments raised an error - "
1069 f"try using sampled_from({name}) instead of builds({name})"
1070 ) from err
1071 if not (self.args or self.kwargs):
1072 from .types import is_generic_type
1074 if isinstance(self.target, NewType) or is_generic_type(self.target):
1075 raise InvalidArgument(
1076 f"Calling {self.target!r} with no arguments raised an "
1077 f"error - try using from_type({self.target!r}) instead "
1078 f"of builds({self.target!r})"
1079 ) from err
1080 if getattr(self.target, "__no_type_check__", None) is True:
1081 # Note: could use PEP-678 __notes__ here. Migrate over once we're
1082 # using an `exceptiongroup` backport with support for that.
1083 raise TypeError(
1084 "This might be because the @no_type_check decorator prevented "
1085 "Hypothesis from inferring a strategy for some required arguments."
1086 ) from err
1087 raise
1089 current_build_context().record_call(obj, self.target, args=args, kwargs=kwargs)
1090 return obj
1092 def do_validate(self) -> None:
1093 tuples(*self.args).validate()
1094 fixed_dictionaries(self.kwargs).validate()
1096 def __repr__(self) -> str:
1097 bits = [get_pretty_function_description(self.target)]
1098 bits.extend(map(repr, self.args))
1099 bits.extend(f"{k}={v!r}" for k, v in self.kwargs.items())
1100 return f"builds({', '.join(bits)})"
1103@cacheable
1104@defines_strategy()
1105def builds(
1106 target: Callable[..., Ex],
1107 /,
1108 *args: SearchStrategy[Any],
1109 **kwargs: SearchStrategy[Any] | EllipsisType,
1110) -> SearchStrategy[Ex]:
1111 """Generates values by drawing from ``args`` and ``kwargs`` and passing
1112 them to the callable (provided as the first positional argument) in the
1113 appropriate argument position.
1115 e.g. ``builds(target, integers(), flag=booleans())`` would draw an
1116 integer ``i`` and a boolean ``b`` and call ``target(i, flag=b)``.
1118 If the callable has type annotations, they will be used to infer a strategy
1119 for required arguments that were not passed to builds. You can also tell
1120 builds to infer a strategy for an optional argument by passing ``...``
1121 (:obj:`python:Ellipsis`) as a keyword argument to builds, instead of a strategy for
1122 that argument to the callable.
1124 If the callable is a class defined with :pypi:`attrs`, missing required
1125 arguments will be inferred from the attribute on a best-effort basis,
1126 e.g. by checking :ref:`attrs standard validators <attrs:api-validators>`.
1127 Dataclasses are handled natively by the inference from type hints.
1129 Examples from this strategy shrink by shrinking the argument values to
1130 the callable.
1131 """
1132 if not callable(target):
1133 from hypothesis.strategies._internal.types import is_a_union
1135 # before 3.14, unions were callable, so it got an error message in
1136 # BuildsStrategy.do_draw. In 3.14+, unions are not callable, so
1137 # we error earlier here instead.
1138 suggestion = (
1139 f" Try using from_type({target}) instead?" if is_a_union(target) else ""
1140 )
1141 raise InvalidArgument(
1142 "The first positional argument to builds() must be a callable "
1143 f"target to construct.{suggestion}"
1144 )
1146 if ... in args: # type: ignore # we only annotated the allowed types
1147 # Avoid an implementation nightmare juggling tuples and worse things
1148 raise InvalidArgument(
1149 "... was passed as a positional argument to "
1150 "builds(), but is only allowed as a keyword arg"
1151 )
1152 required = required_args(target, args, kwargs)
1153 to_infer = {k for k, v in kwargs.items() if v is ...}
1154 if required or to_infer:
1155 if (
1156 isinstance(target, type)
1157 and (attr := sys.modules.get("attr")) is not None
1158 and attr.has(target)
1159 ): # pragma: no cover # covered by our attrs tests in check-niche
1160 # Use our custom introspection for attrs classes
1161 from hypothesis.strategies._internal.attrs import from_attrs
1163 return from_attrs(target, args, kwargs, required | to_infer)
1164 # Otherwise, try using type hints
1165 hints = get_type_hints(target)
1166 if to_infer - set(hints):
1167 badargs = ", ".join(sorted(to_infer - set(hints)))
1168 raise InvalidArgument(
1169 f"passed ... for {badargs}, but we cannot infer a strategy "
1170 "because these arguments have no type annotation"
1171 )
1172 infer_for = {k: v for k, v in hints.items() if k in (required | to_infer)}
1173 if infer_for:
1174 from hypothesis.strategies._internal.types import _global_type_lookup
1176 for kw, t in infer_for.items():
1177 if t in _global_type_lookup:
1178 kwargs[kw] = from_type(t)
1179 else:
1180 # We defer resolution of these type annotations so that the obvious
1181 # approach to registering recursive types just works. I.e.,
1182 # if we're inside `register_type_strategy(cls, builds(cls, ...))`
1183 # and `...` contains recursion on `cls`. See
1184 # https://github.com/HypothesisWorks/hypothesis/issues/3026
1185 kwargs[kw] = deferred(lambda t=t: from_type(t)) # type: ignore
1187 # validated by handling all EllipsisType in the to_infer case
1188 kwargs = cast(dict[str, SearchStrategy], kwargs)
1189 return BuildsStrategy(target, args, kwargs)
1192@cacheable
1193@defines_strategy(eager=True)
1194def from_type(thing: type[T]) -> SearchStrategy[T]:
1195 """Looks up the appropriate search strategy for the given type.
1197 |st.from_type| is used internally to fill in missing arguments to
1198 |st.builds| and can be used interactively
1199 to explore what strategies are available or to debug type resolution.
1201 You can use |st.register_type_strategy| to
1202 handle your custom types, or to globally redefine certain strategies -
1203 for example excluding NaN from floats, or use timezone-aware instead of
1204 naive time and datetime strategies.
1206 |st.from_type| looks up a strategy in the following order:
1208 1. If ``thing`` is in the default lookup mapping or user-registered lookup,
1209 return the corresponding strategy. The default lookup covers all types
1210 with Hypothesis strategies, including extras where possible.
1211 2. If ``thing`` is from the :mod:`python:typing` module, return the
1212 corresponding strategy (special logic).
1213 3. If ``thing`` has one or more subtypes in the merged lookup, return
1214 the union of the strategies for those types that are not subtypes of
1215 other elements in the lookup.
1216 4. Finally, if ``thing`` has type annotations for all required arguments,
1217 and is not an abstract class, it is resolved via
1218 |st.builds|.
1219 5. Because :mod:`abstract types <python:abc>` cannot be instantiated,
1220 we treat abstract types as the union of their concrete subclasses.
1221 Note that this lookup works via inheritance but not via
1222 :obj:`~python:abc.ABCMeta.register`, so you may still need to use
1223 |st.register_type_strategy|.
1225 There is a valuable recipe for leveraging |st.from_type| to generate
1226 "everything except" values from a specified type. I.e.
1228 .. code-block:: python
1230 def everything_except(excluded_types):
1231 return (
1232 from_type(type)
1233 .flatmap(from_type)
1234 .filter(lambda x: not isinstance(x, excluded_types))
1235 )
1237 For example, ``everything_except(int)`` returns a strategy that can
1238 generate anything that |st.from_type| can ever generate, except for
1239 instances of |int|, and excluding instances of types
1240 added via |st.register_type_strategy|.
1242 This is useful when writing tests which check that invalid input is
1243 rejected in a certain way.
1244 """
1245 try:
1246 with warnings.catch_warnings():
1247 warnings.simplefilter("error")
1248 return _from_type(thing)
1249 except Exception:
1250 return _from_type_deferred(thing)
1253def _from_type_deferred(thing: type[Ex]) -> SearchStrategy[Ex]:
1254 # This tricky little dance is because we want to show the repr of the actual
1255 # underlying strategy wherever possible, as a form of user education, but
1256 # would prefer to fall back to the default "from_type(...)" repr instead of
1257 # "deferred(...)" for recursive types or invalid arguments.
1258 try:
1259 thing_repr = nicerepr(thing)
1260 if hasattr(thing, "__module__"):
1261 module_prefix = f"{thing.__module__}."
1262 if not thing_repr.startswith(module_prefix):
1263 thing_repr = module_prefix + thing_repr
1264 repr_ = f"from_type({thing_repr})"
1265 except Exception: # pragma: no cover
1266 repr_ = None
1267 return LazyStrategy(
1268 lambda thing: deferred(lambda: _from_type(thing)),
1269 (thing,),
1270 {},
1271 force_repr=repr_,
1272 )
1275_recurse_guard: ContextVar = ContextVar("recurse_guard")
1278def _from_type(thing: type[Ex]) -> SearchStrategy[Ex]:
1279 # TODO: We would like to move this to the top level, but pending some major
1280 # refactoring it's hard to do without creating circular imports.
1281 from hypothesis.strategies._internal import types
1283 def as_strategy(strat_or_callable, thing):
1284 # User-provided strategies need some validation, and callables even more
1285 # of it. We do this in three places, hence the helper function
1286 if not isinstance(strat_or_callable, SearchStrategy):
1287 assert callable(strat_or_callable) # Validated in register_type_strategy
1288 strategy = strat_or_callable(thing)
1289 else:
1290 strategy = strat_or_callable
1291 if strategy is NotImplemented:
1292 return NotImplemented
1293 if not isinstance(strategy, SearchStrategy):
1294 raise ResolutionFailed(
1295 f"Error: {thing} was registered for {nicerepr(strat_or_callable)}, "
1296 f"but returned non-strategy {strategy!r}"
1297 )
1298 if strategy.is_empty:
1299 raise ResolutionFailed(f"Error: {thing!r} resolved to an empty strategy")
1300 return strategy
1302 def from_type_guarded(thing):
1303 """Returns the result of producer, or ... if recursion on thing is encountered"""
1304 try:
1305 recurse_guard = _recurse_guard.get()
1306 except LookupError:
1307 # We can't simply define the contextvar with default=[], as the
1308 # default object would be shared across contexts
1309 _recurse_guard.set(recurse_guard := [])
1310 if thing in recurse_guard:
1311 raise RewindRecursive(thing)
1312 recurse_guard.append(thing)
1313 try:
1314 return _from_type(thing)
1315 except RewindRecursive as rr:
1316 if rr.target != thing:
1317 raise
1318 return ... # defer resolution
1319 finally:
1320 recurse_guard.pop()
1322 # Let registered extra modules handle their own recognized types first, before
1323 # e.g. Unions are resolved
1324 try:
1325 known = thing in types._global_type_lookup
1326 except TypeError:
1327 # thing is not always hashable!
1328 pass
1329 else:
1330 if not known:
1331 for module, resolver in types._global_extra_lookup.items():
1332 if module in sys.modules:
1333 strat = resolver(thing)
1334 if strat is not None:
1335 return strat
1337 if isinstance(thing, NewType):
1338 # Check if we have an explicitly registered strategy for this thing,
1339 # resolve it so, and otherwise resolve as for the base type.
1340 if thing in types._global_type_lookup:
1341 strategy = as_strategy(types._global_type_lookup[thing], thing)
1342 if strategy is not NotImplemented:
1343 return strategy
1344 return _from_type(thing.__supertype__)
1345 if types.is_a_type_alias_type(thing): # pragma: no cover # covered by 3.12+ tests
1346 if thing in types._global_type_lookup:
1347 strategy = as_strategy(types._global_type_lookup[thing], thing)
1348 if strategy is not NotImplemented:
1349 return strategy
1350 return _from_type(thing.__value__) # type: ignore
1351 if types.is_a_union(thing):
1352 args = sorted(thing.__args__, key=types.type_sorting_key) # type: ignore
1353 return one_of([_from_type(t) for t in args])
1354 if thing in types.LiteralStringTypes: # pragma: no cover
1355 # We can't really cover this because it needs either
1356 # typing-extensions or python3.11+ typing.
1357 # `LiteralString` from runtime's point of view is just a string.
1358 # Fallback to regular text.
1359 return text() # type: ignore
1361 # We also have a special case for TypeVars.
1362 # They are represented as instances like `~T` when they come here.
1363 # We need to work with their type instead.
1364 if isinstance(thing, TypeVar) and type(thing) in types._global_type_lookup:
1365 strategy = as_strategy(types._global_type_lookup[type(thing)], thing)
1366 if strategy is not NotImplemented:
1367 return strategy
1369 if not types.is_a_type(thing):
1370 if isinstance(thing, str):
1371 # See https://github.com/HypothesisWorks/hypothesis/issues/3016
1372 raise InvalidArgument(
1373 f"Got {thing!r} as a type annotation, but the forward-reference "
1374 "could not be resolved from a string to a type. Consider using "
1375 "`from __future__ import annotations` instead of forward-reference "
1376 "strings."
1377 )
1378 raise InvalidArgument(f"{thing=} must be a type") # pragma: no cover
1380 if thing in types.NON_RUNTIME_TYPES:
1381 # Some code like `st.from_type(TypeAlias)` does not make sense.
1382 # Because there are types in python that do not exist in runtime.
1383 raise InvalidArgument(
1384 f"Could not resolve {thing!r} to a strategy, "
1385 f"because there is no such thing as a runtime instance of {thing!r}"
1386 )
1388 # Now that we know `thing` is a type, the first step is to check for an
1389 # explicitly registered strategy. This is the best (and hopefully most
1390 # common) way to resolve a type to a strategy. Note that the value in the
1391 # lookup may be a strategy or a function from type -> strategy; and we
1392 # convert empty results into an explicit error.
1393 try:
1394 if thing in types._global_type_lookup:
1395 strategy = as_strategy(types._global_type_lookup[thing], thing)
1396 if strategy is not NotImplemented:
1397 return strategy
1398 elif (
1399 isinstance(thing, GenericAlias)
1400 and (to := get_origin(thing)) in types._global_type_lookup
1401 ):
1402 strategy = as_strategy(types._global_type_lookup[to], thing)
1403 if strategy is not NotImplemented:
1404 return strategy
1405 except TypeError: # pragma: no cover
1406 # This was originally due to a bizarre divergence in behaviour on Python 3.9.0:
1407 # typing.Callable[[], foo] has __args__ = (foo,) but collections.abc.Callable
1408 # has __args__ = ([], foo); and as a result is non-hashable.
1409 # We've kept it because we turn out to have more type errors from... somewhere.
1410 # FIXME: investigate that, maybe it should be fixed more precisely?
1411 pass
1413 if (hasattr(typing, "_TypedDictMeta") and type(thing) is typing._TypedDictMeta) or (
1414 hasattr(types.typing_extensions, "_TypedDictMeta") # type: ignore
1415 and type(thing) is types.typing_extensions._TypedDictMeta # type: ignore
1416 ): # pragma: no cover
1418 def _get_annotation_arg(key, annotation_type):
1419 try:
1420 return get_args(annotation_type)[0]
1421 except IndexError:
1422 raise InvalidArgument(
1423 f"`{key}: {annotation_type.__name__}` is not a valid type annotation"
1424 ) from None
1426 # Taken from `Lib/typing.py` and modified:
1427 def _get_typeddict_qualifiers(key, annotation_type):
1428 qualifiers = []
1429 annotations = []
1430 while True:
1431 annotation_origin = types.extended_get_origin(annotation_type)
1432 if annotation_origin is Annotated:
1433 if annotation_args := get_args(annotation_type):
1434 annotation_type = annotation_args[0]
1435 annotations.extend(annotation_args[1:])
1436 else:
1437 break
1438 elif annotation_origin in types.RequiredTypes:
1439 qualifiers.append(types.RequiredTypes)
1440 annotation_type = _get_annotation_arg(key, annotation_type)
1441 elif annotation_origin in types.NotRequiredTypes:
1442 qualifiers.append(types.NotRequiredTypes)
1443 annotation_type = _get_annotation_arg(key, annotation_type)
1444 elif annotation_origin in types.ReadOnlyTypes:
1445 qualifiers.append(types.ReadOnlyTypes)
1446 annotation_type = _get_annotation_arg(key, annotation_type)
1447 else:
1448 break
1449 if annotations:
1450 annotation_type = Annotated[(annotation_type, *annotations)]
1451 return set(qualifiers), annotation_type
1453 # The __optional_keys__ attribute may or may not be present, but if there's no
1454 # way to tell and we just have to assume that everything is required.
1455 # See https://github.com/python/cpython/pull/17214 for details.
1456 optional = set(getattr(thing, "__optional_keys__", ()))
1457 required = set(
1458 getattr(thing, "__required_keys__", get_type_hints(thing).keys())
1459 )
1460 anns = {}
1461 for k, v in get_type_hints(thing).items():
1462 qualifiers, v = _get_typeddict_qualifiers(k, v)
1463 # We ignore `ReadOnly` type for now, only unwrap it.
1464 if types.RequiredTypes in qualifiers:
1465 optional.discard(k)
1466 required.add(k)
1467 if types.NotRequiredTypes in qualifiers:
1468 optional.add(k)
1469 required.discard(k)
1471 anns[k] = from_type_guarded(v)
1472 if anns[k] is ...:
1473 anns[k] = _from_type_deferred(v)
1475 if not required.isdisjoint(optional): # pragma: no cover
1476 # It is impossible to cover, because `typing.py` or `typing-extensions`
1477 # won't allow creating incorrect TypedDicts,
1478 # this is just a sanity check from our side.
1479 raise InvalidArgument(
1480 f"Required keys overlap with optional keys in a TypedDict:"
1481 f" {required=}, {optional=}"
1482 )
1483 if (
1484 (not anns)
1485 and thing.__annotations__
1486 and ".<locals>." in getattr(thing, "__qualname__", "")
1487 ):
1488 raise InvalidArgument("Failed to retrieve type annotations for local type")
1489 return fixed_dictionaries( # type: ignore
1490 mapping={k: v for k, v in anns.items() if k in required},
1491 optional={k: v for k, v in anns.items() if k in optional},
1492 )
1494 # If there's no explicitly registered strategy, maybe a subtype of thing
1495 # is registered - if so, we can resolve it to the subclass strategy.
1496 # We'll start by checking if thing is from from the typing module,
1497 # because there are several special cases that don't play well with
1498 # subclass and instance checks.
1499 if (
1500 isinstance(thing, types.typing_root_type)
1501 or (isinstance(get_origin(thing), type) and get_args(thing))
1502 or isinstance(thing, typing.ForwardRef)
1503 ):
1504 return types.from_typing_type(thing)
1506 # If it's not from the typing module, we get all registered types that are
1507 # a subclass of `thing` and are not themselves a subtype of any other such
1508 # type. For example, `Number -> integers() | floats()`, but bools() is
1509 # not included because bool is a subclass of int as well as Number.
1510 strategies = [
1511 s
1512 for s in (
1513 as_strategy(v, thing)
1514 for k, v in sorted(types._global_type_lookup.items(), key=repr)
1515 if isinstance(k, type)
1516 and issubclass(k, thing)
1517 and sum(types.try_issubclass(k, typ) for typ in types._global_type_lookup)
1518 == 1
1519 )
1520 if s is not NotImplemented
1521 ]
1522 if any(not s.is_empty for s in strategies):
1523 return one_of(strategies)
1525 # If we don't have a strategy registered for this type or any subtype, we
1526 # may be able to fall back on type annotations.
1527 if issubclass(thing, enum.Enum):
1528 return sampled_from(thing)
1530 # Finally, try to build an instance by calling the type object. Unlike builds(),
1531 # this block *does* try to infer strategies for arguments with default values.
1532 # That's because of the semantic different; builds() -> "call this with ..."
1533 # so we only infer when *not* doing so would be an error; from_type() -> "give
1534 # me arbitrary instances" so the greater variety is acceptable.
1535 # And if it's *too* varied, express your opinions with register_type_strategy()
1536 if not isabstract(thing):
1537 # If we know that builds(thing) will fail, give a better error message
1538 required = required_args(thing)
1539 if required and not (
1540 required.issubset(get_type_hints(thing))
1541 or ((attr := sys.modules.get("attr")) is not None and attr.has(thing))
1542 or is_typed_named_tuple(thing) # weird enough that we have a specific check
1543 ):
1544 raise ResolutionFailed(
1545 f"Could not resolve {thing!r} to a strategy; consider "
1546 "using register_type_strategy"
1547 )
1548 try:
1549 hints = get_type_hints(thing)
1550 params = get_signature(thing).parameters
1551 except Exception:
1552 params = {} # type: ignore
1554 posonly_args = []
1555 kwargs = {}
1556 for k, p in params.items():
1557 if (
1558 p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD, p.KEYWORD_ONLY)
1559 and k in hints
1560 and k != "return"
1561 ):
1562 ps = from_type_guarded(hints[k])
1563 if p.default is not Parameter.empty and ps is not ...:
1564 ps = just(p.default) | ps
1565 if p.kind is Parameter.POSITIONAL_ONLY:
1566 # builds() doesn't infer strategies for positional args, so:
1567 if ps is ...: # pragma: no cover # rather fiddly to test
1568 if p.default is Parameter.empty:
1569 raise ResolutionFailed(
1570 f"Could not resolve {thing!r} to a strategy; "
1571 "consider using register_type_strategy"
1572 )
1573 ps = just(p.default)
1574 posonly_args.append(ps)
1575 else:
1576 kwargs[k] = ps
1577 if (
1578 params
1579 and not (posonly_args or kwargs)
1580 and not issubclass(thing, BaseException)
1581 ):
1582 from_type_repr = repr_call(from_type, (thing,), {})
1583 builds_repr = repr_call(builds, (thing,), {})
1584 warnings.warn(
1585 f"{from_type_repr} resolved to {builds_repr}, because we could not "
1586 "find any (non-varargs) arguments. Use st.register_type_strategy() "
1587 "to resolve to a strategy which can generate more than one value, "
1588 "or silence this warning.",
1589 SmallSearchSpaceWarning,
1590 stacklevel=2,
1591 )
1592 return builds(thing, *posonly_args, **kwargs)
1594 # And if it's an abstract type, we'll resolve to a union of subclasses instead.
1595 subclasses = thing.__subclasses__()
1596 if not subclasses:
1597 raise ResolutionFailed(
1598 f"Could not resolve {thing!r} to a strategy, because it is an abstract "
1599 "type without any subclasses. Consider using register_type_strategy"
1600 )
1602 subclass_strategies: SearchStrategy = nothing()
1603 for sc in subclasses:
1604 try:
1605 subclass_strategies |= _from_type(sc)
1606 except Exception:
1607 pass
1608 if subclass_strategies.is_empty:
1609 # We're unable to resolve subclasses now, but we might be able to later -
1610 # so we'll just go back to the mixed distribution.
1611 return sampled_from(subclasses).flatmap(_from_type)
1612 return subclass_strategies
1615@cacheable
1616@defines_strategy(force_reusable_values=True)
1617def fractions(
1618 min_value: Real | str | None = None,
1619 max_value: Real | str | None = None,
1620 *,
1621 max_denominator: int | None = None,
1622) -> SearchStrategy[Fraction]:
1623 """Returns a strategy which generates Fractions.
1625 If ``min_value`` is not None then all generated values are no less than
1626 ``min_value``. If ``max_value`` is not None then all generated values are no
1627 greater than ``max_value``. ``min_value`` and ``max_value`` may be anything accepted
1628 by the :class:`~fractions.Fraction` constructor.
1630 If ``max_denominator`` is not None then the denominator of any generated
1631 values is no greater than ``max_denominator``. Note that ``max_denominator`` must
1632 be None or a positive integer.
1634 Examples from this strategy shrink towards smaller denominators, then
1635 closer to zero.
1636 """
1637 min_value = try_convert(Fraction, min_value, "min_value")
1638 max_value = try_convert(Fraction, max_value, "max_value")
1639 # These assertions tell Mypy what happened in try_convert
1640 assert min_value is None or isinstance(min_value, Fraction)
1641 assert max_value is None or isinstance(max_value, Fraction)
1643 check_valid_interval(min_value, max_value, "min_value", "max_value")
1644 check_valid_integer(max_denominator, "max_denominator")
1646 if max_denominator is not None:
1647 if max_denominator < 1:
1648 raise InvalidArgument(f"{max_denominator=} must be >= 1")
1649 if min_value is not None and min_value.denominator > max_denominator:
1650 raise InvalidArgument(
1651 f"The {min_value=} has a denominator greater than the "
1652 f"{max_denominator=}"
1653 )
1654 if max_value is not None and max_value.denominator > max_denominator:
1655 raise InvalidArgument(
1656 f"The {max_value=} has a denominator greater than the "
1657 f"{max_denominator=}"
1658 )
1660 if min_value is not None and min_value == max_value:
1661 return just(min_value)
1663 def dm_func(denom):
1664 """Take denom, construct numerator strategy, and build fraction."""
1665 # Four cases of algebra to get integer bounds and scale factor.
1666 min_num, max_num = None, None
1667 if max_value is None and min_value is None:
1668 pass
1669 elif min_value is None:
1670 max_num = denom * max_value.numerator
1671 denom *= max_value.denominator
1672 elif max_value is None:
1673 min_num = denom * min_value.numerator
1674 denom *= min_value.denominator
1675 else:
1676 low = min_value.numerator * max_value.denominator
1677 high = max_value.numerator * min_value.denominator
1678 scale = min_value.denominator * max_value.denominator
1679 # After calculating our integer bounds and scale factor, we remove
1680 # the gcd to avoid drawing more bytes for the example than needed.
1681 # Note that `div` can be at most equal to `scale`.
1682 div = math.gcd(scale, math.gcd(low, high))
1683 min_num = denom * low // div
1684 max_num = denom * high // div
1685 denom *= scale // div
1687 return builds(
1688 Fraction, integers(min_value=min_num, max_value=max_num), just(denom)
1689 )
1691 if max_denominator is None:
1692 return integers(min_value=1).flatmap(dm_func)
1694 return (
1695 integers(1, max_denominator)
1696 .flatmap(dm_func)
1697 .map(lambda f: f.limit_denominator(max_denominator))
1698 )
1701def _as_finite_decimal(
1702 value: Real | str | None, name: str, allow_infinity: bool | None, places: int | None
1703) -> Decimal | None:
1704 """Convert decimal bounds to decimals, carefully."""
1705 assert name in ("min_value", "max_value")
1706 if value is None:
1707 return None
1708 old = value
1709 if isinstance(value, Fraction):
1710 value = Context(prec=places).divide(value.numerator, value.denominator)
1711 if old != value:
1712 raise InvalidArgument(
1713 f"{old!r} cannot be exactly represented as a decimal with {places=}"
1714 )
1715 if not isinstance(value, Decimal):
1716 with localcontext(Context()): # ensure that default traps are enabled
1717 value = try_convert(Decimal, value, name)
1718 assert isinstance(value, Decimal)
1719 if value.is_nan():
1720 raise InvalidArgument(f"Invalid {name}={value!r}")
1722 # If you are reading this conditional, I am so sorry. I did my best.
1723 finitude_old = value if isinstance(old, str) else old
1724 if math.isfinite(finitude_old) != math.isfinite(value) or (
1725 value.is_finite() and Fraction(str(old)) != Fraction(str(value))
1726 ):
1727 note_deprecation(
1728 f"{old!r} cannot be exactly represented as a decimal with {places=}",
1729 since="2025-11-02",
1730 has_codemod=False,
1731 stacklevel=1,
1732 )
1734 if value.is_finite():
1735 return value
1736 assert value.is_infinite()
1737 if (value < 0 if "min" in name else value > 0) and allow_infinity is not False:
1738 return None
1739 raise InvalidArgument(f"{allow_infinity=}, but {name}={value!r}")
1742@cacheable
1743@defines_strategy(force_reusable_values=True)
1744def decimals(
1745 min_value: Real | str | None = None,
1746 max_value: Real | str | None = None,
1747 *,
1748 allow_nan: bool | None = None,
1749 allow_infinity: bool | None = None,
1750 places: int | None = None,
1751) -> SearchStrategy[Decimal]:
1752 """Generates instances of :class:`python:decimal.Decimal`, which may be:
1754 - A finite rational number, between ``min_value`` and ``max_value``.
1755 - Not a Number, if ``allow_nan`` is True. None means "allow NaN, unless
1756 ``min_value`` and ``max_value`` are not None".
1757 - Positive or negative infinity, if ``max_value`` and ``min_value``
1758 respectively are None, and ``allow_infinity`` is not False. None means
1759 "allow infinity, unless excluded by the min and max values".
1761 Note that where floats have one ``NaN`` value, Decimals have four: signed,
1762 and either *quiet* or *signalling*. See `the decimal module docs
1763 <https://docs.python.org/3/library/decimal.html#special-values>`_ for
1764 more information on special values.
1766 If ``places`` is not None, all finite values drawn from the strategy will
1767 have that number of digits after the decimal place.
1769 Examples from this strategy do not have a well defined shrink order but
1770 try to maximize human readability when shrinking.
1771 """
1772 # Convert min_value and max_value to Decimal values, and validate args
1773 check_valid_integer(places, "places")
1774 if places is not None and places < 0:
1775 raise InvalidArgument(f"{places=} may not be negative")
1776 min_value = _as_finite_decimal(min_value, "min_value", allow_infinity, places)
1777 max_value = _as_finite_decimal(max_value, "max_value", allow_infinity, places)
1778 check_valid_interval(min_value, max_value, "min_value", "max_value")
1779 if allow_infinity and (None not in (min_value, max_value)):
1780 raise InvalidArgument("Cannot allow infinity between finite bounds")
1781 # Set up a strategy for finite decimals. Note that both floating and
1782 # fixed-point decimals require careful handling to remain isolated from
1783 # any external precision context - in short, we always work out the
1784 # required precision for lossless operation and use context methods.
1785 if places is not None:
1786 # Fixed-point decimals are basically integers with a scale factor
1787 def ctx(val):
1788 """Return a context in which this value is lossless."""
1789 precision = ceil(math.log10(abs(val) or 1)) + places + 1
1790 return Context(prec=max([precision, 1]))
1792 def int_to_decimal(val):
1793 context = ctx(val)
1794 return context.quantize(context.multiply(val, factor), factor)
1796 factor = Decimal(10) ** -places
1797 min_num, max_num = None, None
1798 if min_value is not None:
1799 min_num = ceil(ctx(min_value).divide(min_value, factor))
1800 if max_value is not None:
1801 max_num = floor(ctx(max_value).divide(max_value, factor))
1802 if min_num is not None and max_num is not None and min_num > max_num:
1803 raise InvalidArgument(
1804 f"There are no decimals with {places} places between "
1805 f"{min_value=} and {max_value=}"
1806 )
1807 strat = integers(min_num, max_num).map(int_to_decimal)
1808 else:
1809 # Otherwise, they're like fractions featuring a power of ten
1810 def fraction_to_decimal(val):
1811 precision = (
1812 ceil(math.log10(abs(val.numerator) or 1) + math.log10(val.denominator))
1813 + 1
1814 )
1815 return Context(prec=precision or 1).divide(
1816 Decimal(val.numerator), val.denominator
1817 )
1819 strat = fractions(min_value, max_value).map(fraction_to_decimal)
1820 # Compose with sampled_from for infinities and NaNs as appropriate
1821 special: list[Decimal] = []
1822 if allow_infinity or (allow_infinity is None and max_value is None):
1823 special.append(Decimal("Infinity"))
1824 if allow_infinity or (allow_infinity is None and min_value is None):
1825 special.append(Decimal("-Infinity"))
1826 if allow_nan or (allow_nan is None and (None in (min_value, max_value))):
1827 special.extend(map(Decimal, ("NaN", "-NaN", "sNaN", "-sNaN")))
1828 return strat | (sampled_from(special) if special else nothing())
1831@defines_strategy(eager=True)
1832def recursive(
1833 base: SearchStrategy[Ex],
1834 extend: Callable[[SearchStrategy[Any]], SearchStrategy[T]],
1835 *,
1836 max_leaves: int = 100,
1837) -> SearchStrategy[T | Ex]:
1838 """base: A strategy to start from.
1840 extend: A function which takes a strategy and returns a new strategy.
1842 max_leaves: The maximum number of elements to be drawn from base on a given
1843 run.
1845 This returns a strategy ``S`` such that ``S = extend(base | S)``. That is,
1846 values may be drawn from base, or from any strategy reachable by mixing
1847 applications of | and extend.
1849 An example may clarify: ``recursive(booleans(), lists)`` would return a
1850 strategy that may return arbitrarily nested and mixed lists of booleans.
1851 So e.g. ``False``, ``[True]``, ``[False, []]``, and ``[[[[True]]]]`` are
1852 all valid values to be drawn from that strategy.
1854 Examples from this strategy shrink by trying to reduce the amount of
1855 recursion and by shrinking according to the shrinking behaviour of base
1856 and the result of extend.
1858 """
1860 return RecursiveStrategy(base, extend, max_leaves)
1863class PermutationStrategy(SearchStrategy):
1864 def __init__(self, values):
1865 super().__init__()
1866 self.values = values
1868 def do_draw(self, data):
1869 # Reversed Fisher-Yates shuffle: swap each element with itself or with
1870 # a later element. This shrinks i==j for each element, i.e. to no
1871 # change. We don't consider the last element as it's always a no-op.
1872 result = list(self.values)
1873 for i in range(len(result) - 1):
1874 j = data.draw_integer(i, len(result) - 1)
1875 result[i], result[j] = result[j], result[i]
1876 return result
1879@defines_strategy()
1880def permutations(values: Sequence[T]) -> SearchStrategy[list[T]]:
1881 """Return a strategy which returns permutations of the ordered collection
1882 ``values``.
1884 Examples from this strategy shrink by trying to become closer to the
1885 original order of values.
1886 """
1887 values = check_sample(values, "permutations")
1888 if not values:
1889 return builds(list)
1891 return PermutationStrategy(values)
1894class CompositeStrategy(SearchStrategy):
1895 def __init__(self, definition, args, kwargs):
1896 super().__init__()
1897 self.definition = definition
1898 self.args = args
1899 self.kwargs = kwargs
1901 def do_draw(self, data):
1902 return self.definition(data.draw, *self.args, **self.kwargs)
1904 def calc_label(self) -> int:
1905 return combine_labels(
1906 self.class_label,
1907 calc_label_from_callable(self.definition),
1908 )
1911class DrawFn(Protocol):
1912 """This type only exists so that you can write type hints for functions
1913 decorated with :func:`@composite <hypothesis.strategies.composite>`.
1915 .. code-block:: python
1917 def draw(strategy: SearchStrategy[Ex], label: object = None) -> Ex: ...
1919 @composite
1920 def list_and_index(draw: DrawFn) -> tuple[int, str]:
1921 i = draw(integers()) # type of `i` inferred as 'int'
1922 s = draw(text()) # type of `s` inferred as 'str'
1923 return i, s
1924 """
1926 def __init__(self):
1927 raise TypeError("Protocols cannot be instantiated") # pragma: no cover
1929 # Protocol overrides our signature for __init__,
1930 # so we override it right back to make the docs look nice.
1931 __signature__: Signature = Signature(parameters=[])
1933 # We define this as a callback protocol because a simple typing.Callable is
1934 # insufficient to fully represent the interface, due to the optional `label`
1935 # parameter.
1936 def __call__(self, strategy: SearchStrategy[Ex], label: object = None) -> Ex:
1937 raise NotImplementedError
1940def _composite(f):
1941 # Wrapped below, using ParamSpec if available
1942 if isinstance(f, (classmethod, staticmethod)):
1943 special_method = type(f)
1944 f = f.__func__
1945 else:
1946 special_method = None
1948 sig = get_signature(f)
1949 params = tuple(sig.parameters.values())
1951 if not (params and "POSITIONAL" in params[0].kind.name):
1952 raise InvalidArgument(
1953 "Functions wrapped with composite must take at least one "
1954 "positional argument."
1955 )
1956 if params[0].default is not sig.empty:
1957 raise InvalidArgument("A default value for initial argument will never be used")
1958 if not (f is typing._overload_dummy or is_first_param_referenced_in_function(f)):
1959 note_deprecation(
1960 "There is no reason to use @st.composite on a function which "
1961 "does not call the provided draw() function internally.",
1962 since="2022-07-17",
1963 has_codemod=False,
1964 )
1965 if get_origin(sig.return_annotation) is SearchStrategy:
1966 ret_repr = repr(sig.return_annotation).replace("hypothesis.strategies.", "st.")
1967 warnings.warn(
1968 f"Return-type annotation is `{ret_repr}`, but the decorated "
1969 "function should return a value (not a strategy)",
1970 HypothesisWarning,
1971 stacklevel=3,
1972 )
1973 if params[0].kind.name != "VAR_POSITIONAL":
1974 params = params[1:]
1975 newsig = sig.replace(
1976 parameters=params,
1977 return_annotation=(
1978 SearchStrategy
1979 if sig.return_annotation is sig.empty
1980 else SearchStrategy[sig.return_annotation]
1981 ),
1982 )
1984 @defines_strategy()
1985 @define_function_signature(f.__name__, f.__doc__, newsig)
1986 def accept(*args, **kwargs):
1987 return CompositeStrategy(f, args, kwargs)
1989 accept.__module__ = f.__module__
1990 accept.__signature__ = newsig
1991 if special_method is not None:
1992 return special_method(accept)
1993 return accept
1996composite_doc = """
1997Defines a strategy that is built out of potentially arbitrarily many other
1998strategies.
2000@composite provides a callable ``draw`` as the first parameter to the decorated
2001function, which can be used to dynamically draw a value from any strategy. For
2002example:
2004.. code-block:: python
2006 from hypothesis import strategies as st, given
2008 @st.composite
2009 def values(draw):
2010 n1 = draw(st.integers())
2011 n2 = draw(st.integers(min_value=n1))
2012 return (n1, n2)
2014 @given(values())
2015 def f(value):
2016 (n1, n2) = value
2017 assert n1 <= n2
2019@composite cannot mix test code and generation code. If you need that, use
2020|st.data|.
2022If :func:`@composite <hypothesis.strategies.composite>` is used to decorate a
2023method or classmethod, the ``draw`` argument must come before ``self`` or
2024``cls``. While we therefore recommend writing strategies as standalone functions
2025and using |st.register_type_strategy| to associate them with a class, methods
2026are supported and the ``@composite`` decorator may be applied either before or
2027after ``@classmethod`` or ``@staticmethod``. See :issue:`2578` and :pull:`2634`
2028for more details.
2030Examples from this strategy shrink by shrinking the output of each draw call.
2031"""
2032if typing.TYPE_CHECKING or ParamSpec is not None:
2033 P = ParamSpec("P")
2035 def composite(
2036 f: Callable[Concatenate[DrawFn, P], Ex],
2037 ) -> Callable[P, SearchStrategy[Ex]]:
2038 return _composite(f)
2040else: # pragma: no cover
2042 @cacheable
2043 def composite(f: Callable[..., Ex]) -> Callable[..., SearchStrategy[Ex]]:
2044 return _composite(f)
2047composite.__doc__ = composite_doc
2050@defines_strategy(force_reusable_values=True)
2051@cacheable
2052def complex_numbers(
2053 *,
2054 min_magnitude: Real = 0,
2055 max_magnitude: Real | None = None,
2056 allow_infinity: bool | None = None,
2057 allow_nan: bool | None = None,
2058 allow_subnormal: bool = True,
2059 width: Literal[32, 64, 128] = 128,
2060) -> SearchStrategy[complex]:
2061 """Returns a strategy that generates :class:`~python:complex`
2062 numbers.
2064 This strategy draws complex numbers with constrained magnitudes.
2065 The ``min_magnitude`` and ``max_magnitude`` parameters should be
2066 non-negative :class:`~python:numbers.Real` numbers; a value
2067 of ``None`` corresponds an infinite upper bound.
2069 If ``min_magnitude`` is nonzero or ``max_magnitude`` is finite, it
2070 is an error to enable ``allow_nan``. If ``max_magnitude`` is finite,
2071 it is an error to enable ``allow_infinity``.
2073 ``allow_infinity``, ``allow_nan``, and ``allow_subnormal`` are
2074 applied to each part of the complex number separately, as for
2075 :func:`~hypothesis.strategies.floats`.
2077 The magnitude constraints are respected up to a relative error
2078 of (around) floating-point epsilon, due to implementation via
2079 the system ``sqrt`` function.
2081 The ``width`` argument specifies the maximum number of bits of precision
2082 required to represent the entire generated complex number.
2083 Valid values are 32, 64 or 128, which correspond to the real and imaginary
2084 components each having width 16, 32 or 64, respectively.
2085 Passing ``width=64`` will still use the builtin 128-bit
2086 :class:`~python:complex` class, but always for values which can be
2087 exactly represented as two 32-bit floats.
2089 Examples from this strategy shrink by shrinking their real and
2090 imaginary parts, as :func:`~hypothesis.strategies.floats`.
2092 If you need to generate complex numbers with particular real and
2093 imaginary parts or relationships between parts, consider using
2094 :func:`builds(complex, ...) <hypothesis.strategies.builds>` or
2095 :func:`@composite <hypothesis.strategies.composite>` respectively.
2096 """
2097 check_valid_magnitude(min_magnitude, "min_magnitude")
2098 check_valid_magnitude(max_magnitude, "max_magnitude")
2099 check_valid_interval(min_magnitude, max_magnitude, "min_magnitude", "max_magnitude")
2100 if max_magnitude == math.inf:
2101 max_magnitude = None
2103 if allow_infinity is None:
2104 allow_infinity = bool(max_magnitude is None)
2105 elif allow_infinity and max_magnitude is not None:
2106 raise InvalidArgument(f"Cannot have {allow_infinity=} with {max_magnitude=}")
2107 if allow_nan is None:
2108 allow_nan = bool(min_magnitude == 0 and max_magnitude is None)
2109 elif allow_nan and not (min_magnitude == 0 and max_magnitude is None):
2110 raise InvalidArgument(
2111 f"Cannot have {allow_nan=}, {min_magnitude=}, {max_magnitude=}"
2112 )
2113 check_type(bool, allow_subnormal, "allow_subnormal")
2114 if width not in (32, 64, 128):
2115 raise InvalidArgument(
2116 f"{width=}, but must be 32, 64 or 128 (other complex dtypes "
2117 "such as complex192 or complex256 are not supported)"
2118 # For numpy, these types would be supported (but not by CPython):
2119 # https://numpy.org/doc/stable/reference/arrays.scalars.html#complex-floating-point-types
2120 )
2121 component_width = width // 2
2122 allow_kw = {
2123 "allow_nan": allow_nan,
2124 "allow_infinity": allow_infinity,
2125 # If we have a nonzero normal min_magnitude and draw a zero imaginary part,
2126 # then allow_subnormal=True would be an error with the min_value to the floats()
2127 # strategy for the real part. We therefore replace True with None.
2128 "allow_subnormal": None if allow_subnormal else allow_subnormal,
2129 "width": component_width,
2130 }
2132 if min_magnitude == 0 and max_magnitude is None:
2133 # In this simple but common case, there are no constraints on the
2134 # magnitude and therefore no relationship between the real and
2135 # imaginary parts.
2136 return builds(complex, floats(**allow_kw), floats(**allow_kw)) # type: ignore
2138 @composite
2139 def constrained_complex(draw):
2140 # We downcast drawn floats to the desired (component) width so we
2141 # guarantee the resulting complex values are representable. Note
2142 # truncating the mantissa bits with float_of() cannot increase the
2143 # magnitude of a float, so we are guaranteed to stay within the allowed
2144 # range. See https://github.com/HypothesisWorks/hypothesis/issues/3573
2146 # Draw the imaginary part, and determine the maximum real part given
2147 # this and the max_magnitude
2148 if max_magnitude is None:
2149 zi = draw(floats(**allow_kw))
2150 rmax = None
2151 else:
2152 zi = draw(
2153 floats(
2154 -float_of(max_magnitude, component_width),
2155 float_of(max_magnitude, component_width),
2156 **allow_kw,
2157 )
2158 )
2159 rmax = float_of(cathetus(max_magnitude, zi), component_width)
2160 # Draw the real part from the allowed range given the imaginary part
2161 if min_magnitude == 0 or math.fabs(zi) >= min_magnitude:
2162 zr = draw(floats(None if rmax is None else -rmax, rmax, **allow_kw))
2163 else:
2164 rmin = float_of(cathetus(min_magnitude, zi), component_width)
2165 zr = draw(floats(rmin, rmax, **allow_kw))
2166 # Order of conditions carefully tuned so that for a given pair of
2167 # magnitude arguments, we always either draw or do not draw the bool
2168 # (crucial for good shrinking behaviour) but only invert when needed.
2169 if min_magnitude > 0 and draw(booleans()) and math.fabs(zi) <= min_magnitude:
2170 zr = -zr
2171 return complex(zr, zi)
2173 return constrained_complex()
2176@defines_strategy(eager=True)
2177def shared(
2178 base: SearchStrategy[Ex],
2179 *,
2180 key: Hashable | None = None,
2181) -> SearchStrategy[Ex]:
2182 """Returns a strategy that draws a single shared value per run, drawn from
2183 base. Any two shared instances with the same key will share the same value,
2184 otherwise the identity of this strategy will be used. That is:
2186 >>> s = integers() # or any other strategy
2187 >>> x = shared(s)
2188 >>> y = shared(s)
2190 In the above x and y may draw different (or potentially the same) values.
2191 In the following they will always draw the same:
2193 >>> x = shared(s, key="hi")
2194 >>> y = shared(s, key="hi")
2196 Examples from this strategy shrink as per their base strategy.
2197 """
2198 return SharedStrategy(base, key)
2201@composite
2202def _maybe_nil_uuids(draw, uuid):
2203 # Equivalent to `random_uuids | just(...)`, with a stronger bias to the former.
2204 if draw(data()).conjecture_data.draw_boolean(1 / 64):
2205 return UUID("00000000-0000-0000-0000-000000000000")
2206 return uuid
2209@cacheable
2210@defines_strategy(force_reusable_values=True)
2211def uuids(
2212 *, version: Literal[1, 2, 3, 4, 5] | None = None, allow_nil: bool = False
2213) -> SearchStrategy[UUID]:
2214 """Returns a strategy that generates :class:`UUIDs <uuid.UUID>`.
2216 If the optional version argument is given, value is passed through
2217 to :class:`~python:uuid.UUID` and only UUIDs of that version will
2218 be generated.
2220 If ``allow_nil`` is True, generate the nil UUID much more often.
2221 Otherwise, all returned values from this will be unique, so e.g. if you do
2222 ``lists(uuids())`` the resulting list will never contain duplicates.
2224 Examples from this strategy don't have any meaningful shrink order.
2225 """
2226 check_type(bool, allow_nil, "allow_nil")
2227 if version not in (None, 1, 2, 3, 4, 5):
2228 raise InvalidArgument(
2229 f"{version=}, but version must be in "
2230 "(None, 1, 2, 3, 4, 5) to pass to the uuid.UUID constructor."
2231 )
2232 random_uuids = shared(
2233 randoms(use_true_random=True), key="hypothesis.strategies.uuids.generator"
2234 ).map(lambda r: UUID(version=version, int=r.getrandbits(128)))
2236 if allow_nil:
2237 if version is not None:
2238 raise InvalidArgument("The nil UUID is not of any version")
2239 return random_uuids.flatmap(_maybe_nil_uuids)
2240 return random_uuids
2243class RunnerStrategy(SearchStrategy):
2244 def __init__(self, default):
2245 super().__init__()
2246 self.default = default
2248 def do_draw(self, data):
2249 if data.hypothesis_runner is not_set:
2250 if self.default is not_set:
2251 raise InvalidArgument(
2252 "Cannot use runner() strategy with no "
2253 "associated runner or explicit default."
2254 )
2255 return self.default
2256 return data.hypothesis_runner
2259@defines_strategy(force_reusable_values=True)
2260def runner(*, default: Any = not_set) -> SearchStrategy[Any]:
2261 """A strategy for getting "the current test runner", whatever that may be.
2262 The exact meaning depends on the entry point, but it will usually be the
2263 associated 'self' value for it.
2265 If you are using this in a rule for stateful testing, this strategy
2266 will return the instance of the :class:`~hypothesis.stateful.RuleBasedStateMachine`
2267 that the rule is running for.
2269 If there is no current test runner and a default is provided, return
2270 that default. If no default is provided, raises InvalidArgument.
2272 Examples from this strategy do not shrink (because there is only one).
2273 """
2274 return RunnerStrategy(default)
2277class DataObject:
2278 """This type only exists so that you can write type hints for tests using
2279 the :func:`~hypothesis.strategies.data` strategy. Do not use it directly!
2280 """
2282 # Note that "only exists" here really means "is only exported to users",
2283 # but we want to treat it as "semi-stable", not document it as "public API".
2285 def __init__(self, data: ConjectureData) -> None:
2286 self.count = 0
2287 self.conjecture_data = data
2289 __signature__ = Signature() # hide internals from Sphinx introspection
2291 def __repr__(self) -> str:
2292 return "data(...)"
2294 def draw(self, strategy: SearchStrategy[Ex], label: Any = None) -> Ex:
2295 """Like :obj:`~hypothesis.strategies.DrawFn`."""
2296 check_strategy(strategy, "strategy")
2297 self.count += 1
2298 desc = f"Draw {self.count}{'' if label is None else f' ({label})'}"
2299 with deprecate_random_in_strategy("{}from {!r}", desc, strategy):
2300 result = self.conjecture_data.draw(strategy, observe_as=f"generate:{desc}")
2302 # optimization to avoid needless printer.pretty
2303 if should_note():
2304 printer = RepresentationPrinter(context=current_build_context())
2305 printer.text(f"{desc}: ")
2306 if self.conjecture_data.provider.avoid_realization:
2307 printer.text("<symbolic>")
2308 else:
2309 printer.pretty(result)
2310 note(printer.getvalue())
2311 return result
2314class DataStrategy(SearchStrategy):
2315 def do_draw(self, data):
2316 if data._shared_data_strategy is None:
2317 data._shared_data_strategy = DataObject(data)
2318 return data._shared_data_strategy
2320 def __repr__(self) -> str:
2321 return "data()"
2323 def map(self, f):
2324 self.__not_a_first_class_strategy("map")
2326 def filter(self, condition: Callable[[Ex], Any]) -> NoReturn:
2327 self.__not_a_first_class_strategy("filter")
2329 def flatmap(self, f):
2330 self.__not_a_first_class_strategy("flatmap")
2332 def example(self) -> NoReturn:
2333 self.__not_a_first_class_strategy("example")
2335 def __not_a_first_class_strategy(self, name: str) -> NoReturn:
2336 raise InvalidArgument(
2337 f"Cannot call {name} on a DataStrategy. You should probably "
2338 "be using @composite for whatever it is you're trying to do."
2339 )
2342@cacheable
2343@defines_strategy(eager=True)
2344def data() -> SearchStrategy[DataObject]:
2345 """
2346 Provides an object ``data`` with a ``data.draw`` function which acts like
2347 the ``draw`` callable provided by |st.composite|, in that it can be used
2348 to dynamically draw values from strategies. |st.data| is more powerful
2349 than |st.composite|, because it allows you to mix generation and test code.
2351 Here's an example of dynamically generating values using |st.data|:
2353 .. code-block:: python
2355 from hypothesis import strategies as st, given
2357 @given(st.data())
2358 def test_values(data):
2359 n1 = data.draw(st.integers())
2360 n2 = data.draw(st.integers(min_value=n1))
2361 assert n1 + 1 <= n2
2363 If the test fails, each draw will be printed with the falsifying example.
2364 e.g. the above is wrong (it has a boundary condition error), so will print:
2366 .. code-block:: pycon
2368 Falsifying example: test_values(data=data(...))
2369 Draw 1: 0
2370 Draw 2: 0
2372 Optionally, you can provide a label to identify values generated by each call
2373 to ``data.draw()``. These labels can be used to identify values in the
2374 output of a falsifying example.
2376 For instance:
2378 .. code-block:: python
2380 @given(st.data())
2381 def test_draw_sequentially(data):
2382 x = data.draw(st.integers(), label="First number")
2383 y = data.draw(st.integers(min_value=x), label="Second number")
2384 assert x < y
2386 will produce:
2388 .. code-block:: pycon
2390 Falsifying example: test_draw_sequentially(data=data(...))
2391 Draw 1 (First number): 0
2392 Draw 2 (Second number): 0
2394 Examples from this strategy shrink by shrinking the output of each draw call.
2395 """
2396 return DataStrategy()
2399if sys.version_info < (3, 12):
2400 # TypeAliasType is new in 3.12
2401 RegisterTypeT: TypeAlias = type[Ex]
2402else: # pragma: no cover # covered by test_mypy.py
2403 from typing import TypeAliasType
2405 # see https://github.com/HypothesisWorks/hypothesis/issues/4410
2406 RegisterTypeT: TypeAlias = type[Ex] | TypeAliasType
2409def register_type_strategy(
2410 custom_type: RegisterTypeT,
2411 strategy: SearchStrategy[Ex] | Callable[[type[Ex]], SearchStrategy[Ex]],
2412) -> None:
2413 """Add an entry to the global type-to-strategy lookup.
2415 This lookup is used in :func:`~hypothesis.strategies.builds` and
2416 |@given|.
2418 :func:`~hypothesis.strategies.builds` will be used automatically for
2419 classes with type annotations on ``__init__`` , so you only need to
2420 register a strategy if one or more arguments need to be more tightly
2421 defined than their type-based default, or if you want to supply a strategy
2422 for an argument with a default value.
2424 ``strategy`` may be a search strategy, or a function that takes a type and
2425 returns a strategy (useful for generic types). The function may return
2426 :data:`NotImplemented` to conditionally not provide a strategy for the type
2427 (the type will still be resolved by other methods, if possible, as if the
2428 function was not registered).
2430 Note that you may not register a parametrised generic type (such as
2431 ``MyCollection[int]``) directly, because the resolution logic does not
2432 handle this case correctly. Instead, you may register a *function* for
2433 ``MyCollection`` and `inspect the type parameters within that function
2434 <https://stackoverflow.com/q/48572831>`__.
2435 """
2436 # TODO: We would like to move this to the top level, but pending some major
2437 # refactoring it's hard to do without creating circular imports.
2438 from hypothesis.strategies._internal import types
2440 if not types.is_a_type(custom_type):
2441 raise InvalidArgument(f"{custom_type=} must be a type")
2442 if custom_type in types.NON_RUNTIME_TYPES:
2443 raise InvalidArgument(
2444 f"{custom_type=} is not allowed to be registered, "
2445 f"because there is no such thing as a runtime instance of {custom_type!r}"
2446 )
2447 if not (isinstance(strategy, SearchStrategy) or callable(strategy)):
2448 raise InvalidArgument(
2449 f"{strategy=} must be a SearchStrategy, or a function that takes "
2450 "a generic type and returns a specific SearchStrategy"
2451 )
2452 if isinstance(strategy, SearchStrategy):
2453 with warnings.catch_warnings():
2454 warnings.simplefilter("error", HypothesisSideeffectWarning)
2456 # Calling is_empty forces materialization of lazy strategies. If this is done at import
2457 # time, lazy strategies will warn about it; here, we force that warning to raise to
2458 # avoid the materialization. Ideally, we'd just check if the strategy is lazy, but the
2459 # lazy strategy may be wrapped underneath another strategy so that's complicated.
2460 try:
2461 if strategy.is_empty:
2462 raise InvalidArgument(f"{strategy=} must not be empty")
2463 except HypothesisSideeffectWarning: # pragma: no cover
2464 pass
2465 if types.has_type_arguments(custom_type):
2466 raise InvalidArgument(
2467 f"Cannot register generic type {custom_type!r}, because it has type "
2468 "arguments which would not be handled. Instead, register a function "
2469 f"for {get_origin(custom_type)!r} which can inspect specific type "
2470 "objects and return a strategy."
2471 )
2472 if (
2473 "pydantic.generics" in sys.modules
2474 and issubclass(custom_type, sys.modules["pydantic.generics"].GenericModel)
2475 and not re.search(r"[A-Za-z_]+\[.+\]", repr(custom_type))
2476 and callable(strategy)
2477 ): # pragma: no cover
2478 # See https://github.com/HypothesisWorks/hypothesis/issues/2940
2479 raise InvalidArgument(
2480 f"Cannot register a function for {custom_type!r}, because parametrized "
2481 "`pydantic.generics.GenericModel` subclasses aren't actually generic "
2482 "types at runtime. In this case, you should register a strategy "
2483 "directly for each parametrized form that you anticipate using."
2484 )
2486 types._global_type_lookup[custom_type] = strategy
2487 from_type.__clear_cache() # type: ignore
2490@cacheable
2491@defines_strategy(eager=True)
2492def deferred(definition: Callable[[], SearchStrategy[Ex]]) -> SearchStrategy[Ex]:
2493 """A deferred strategy allows you to write a strategy that references other
2494 strategies that have not yet been defined. This allows for the easy
2495 definition of recursive and mutually recursive strategies.
2497 The definition argument should be a zero-argument function that returns a
2498 strategy. It will be evaluated the first time the strategy is used to
2499 produce an example.
2501 Example usage:
2503 >>> import hypothesis.strategies as st
2504 >>> x = st.deferred(lambda: st.booleans() | st.tuples(x, x))
2505 >>> x.example()
2506 (((False, (True, True)), (False, True)), (True, True))
2507 >>> x.example()
2508 True
2510 Mutual recursion also works fine:
2512 >>> a = st.deferred(lambda: st.booleans() | b)
2513 >>> b = st.deferred(lambda: st.tuples(a, a))
2514 >>> a.example()
2515 True
2516 >>> b.example()
2517 (False, (False, ((False, True), False)))
2519 Examples from this strategy shrink as they normally would from the strategy
2520 returned by the definition.
2521 """
2522 return DeferredStrategy(definition)
2525def domains() -> SearchStrategy[str]:
2526 import hypothesis.provisional
2528 return hypothesis.provisional.domains()
2531@defines_strategy(force_reusable_values=True)
2532def emails(
2533 *, domains: SearchStrategy[str] = LazyStrategy(domains, (), {})
2534) -> SearchStrategy[str]:
2535 """A strategy for generating email addresses as unicode strings. The
2536 address format is specified in :rfc:`5322#section-3.4.1`. Values shrink
2537 towards shorter local-parts and host domains.
2539 If ``domains`` is given then it must be a strategy that generates domain
2540 names for the emails, defaulting to :func:`~hypothesis.provisional.domains`.
2542 This strategy is useful for generating "user data" for tests, as
2543 mishandling of email addresses is a common source of bugs.
2544 """
2545 local_chars = string.ascii_letters + string.digits + "!#$%&'*+-/=^_`{|}~"
2546 local_part = text(local_chars, min_size=1, max_size=64)
2547 # TODO: include dot-atoms, quoted strings, escaped chars, etc in local part
2548 return builds("{}@{}".format, local_part, domains).filter(
2549 lambda addr: len(addr) <= 254
2550 )
2553def _functions(*, like, returns, pure):
2554 # Wrapped up to use ParamSpec below
2555 check_type(bool, pure, "pure")
2556 if not callable(like):
2557 raise InvalidArgument(
2558 "The first argument to functions() must be a callable to imitate, "
2559 f"but got non-callable like={nicerepr(like)!r}"
2560 )
2561 if returns in (None, ...):
2562 # Passing `None` has never been *documented* as working, but it still
2563 # did from May 2020 to Jan 2022 so we'll avoid breaking it without cause.
2564 hints = get_type_hints(like)
2565 returns = from_type(hints.get("return", type(None)))
2566 check_strategy(returns, "returns")
2567 return FunctionStrategy(like, returns, pure)
2570if typing.TYPE_CHECKING or ParamSpec is not None:
2572 @overload
2573 def functions(
2574 *, pure: bool = ...
2575 ) -> SearchStrategy[Callable[[], None]]: # pragma: no cover
2576 ...
2578 @overload
2579 def functions(
2580 *,
2581 like: Callable[P, T],
2582 pure: bool = ...,
2583 ) -> SearchStrategy[Callable[P, T]]: # pragma: no cover
2584 ...
2586 @overload
2587 def functions(
2588 *,
2589 returns: SearchStrategy[T],
2590 pure: bool = ...,
2591 ) -> SearchStrategy[Callable[[], T]]: # pragma: no cover
2592 ...
2594 @overload
2595 def functions(
2596 *,
2597 like: Callable[P, Any],
2598 returns: SearchStrategy[T],
2599 pure: bool = ...,
2600 ) -> SearchStrategy[Callable[P, T]]: # pragma: no cover
2601 ...
2603 @defines_strategy()
2604 def functions(*, like=lambda: None, returns=..., pure=False):
2605 # We shouldn't need overloads here, but mypy disallows default args for
2606 # generics: https://github.com/python/mypy/issues/3737
2607 """functions(*, like=lambda: None, returns=..., pure=False)
2609 A strategy for functions, which can be used in callbacks.
2611 The generated functions will mimic the interface of ``like``, which must
2612 be a callable (including a class, method, or function). The return value
2613 for the function is drawn from the ``returns`` argument, which must be a
2614 strategy. If ``returns`` is not passed, we attempt to infer a strategy
2615 from the return-type annotation if present, falling back to :func:`~none`.
2617 If ``pure=True``, all arguments passed to the generated function must be
2618 hashable, and if passed identical arguments the original return value will
2619 be returned again - *not* regenerated, so beware mutable values.
2621 If ``pure=False``, generated functions do not validate their arguments, and
2622 may return a different value if called again with the same arguments.
2624 Generated functions can only be called within the scope of the ``@given``
2625 which created them.
2626 """
2627 return _functions(like=like, returns=returns, pure=pure)
2629else: # pragma: no cover
2631 @defines_strategy()
2632 def functions(
2633 *,
2634 like: Callable[..., Any] = lambda: None,
2635 returns: SearchStrategy[Any] | EllipsisType = ...,
2636 pure: bool = False,
2637 ) -> SearchStrategy[Callable[..., Any]]:
2638 """functions(*, like=lambda: None, returns=..., pure=False)
2640 A strategy for functions, which can be used in callbacks.
2642 The generated functions will mimic the interface of ``like``, which must
2643 be a callable (including a class, method, or function). The return value
2644 for the function is drawn from the ``returns`` argument, which must be a
2645 strategy. If ``returns`` is not passed, we attempt to infer a strategy
2646 from the return-type annotation if present, falling back to :func:`~none`.
2648 If ``pure=True``, all arguments passed to the generated function must be
2649 hashable, and if passed identical arguments the original return value will
2650 be returned again - *not* regenerated, so beware mutable values.
2652 If ``pure=False``, generated functions do not validate their arguments, and
2653 may return a different value if called again with the same arguments.
2655 Generated functions can only be called within the scope of the ``@given``
2656 which created them.
2657 """
2658 return _functions(like=like, returns=returns, pure=pure)
2661@composite
2662def slices(draw: Any, size: int) -> slice:
2663 """Generates slices that will select indices up to the supplied size
2665 Generated slices will have start and stop indices that range from -size to size - 1
2666 and will step in the appropriate direction. Slices should only produce an empty selection
2667 if the start and end are the same.
2669 Examples from this strategy shrink toward 0 and smaller values
2670 """
2671 check_valid_size(size, "size")
2672 if size == 0:
2673 step = draw(none() | integers().filter(bool))
2674 return slice(None, None, step)
2675 # For slices start is inclusive and stop is exclusive
2676 start = draw(integers(0, size - 1) | none())
2677 stop = draw(integers(0, size) | none())
2679 # Limit step size to be reasonable
2680 if start is None and stop is None:
2681 max_step = size
2682 elif start is None:
2683 max_step = stop
2684 elif stop is None:
2685 max_step = start
2686 else:
2687 max_step = abs(start - stop)
2689 step = draw(integers(1, max_step or 1))
2691 if (draw(booleans()) and start == stop) or (stop or 0) < (start or 0):
2692 step *= -1
2694 if draw(booleans()) and start is not None:
2695 start -= size
2696 if draw(booleans()) and stop is not None:
2697 stop -= size
2698 if (not draw(booleans())) and step == 1:
2699 step = None
2701 return slice(start, stop, step)