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 contextvars import ContextVar
22from decimal import Context, Decimal, localcontext
23from fractions import Fraction
24from functools import lru_cache, reduce
25from inspect import Parameter, Signature, isabstract, isclass
26from types import FunctionType
27from typing import (
28 Any,
29 AnyStr,
30 Callable,
31 Collection,
32 Dict,
33 FrozenSet,
34 Hashable,
35 Iterable,
36 List,
37 Literal,
38 Optional,
39 Pattern,
40 Protocol,
41 Sequence,
42 Set,
43 Tuple,
44 Type,
45 TypeVar,
46 Union,
47 get_args,
48 get_origin,
49 overload,
50)
51from uuid import UUID
53import attr
55from hypothesis._settings import note_deprecation
56from hypothesis.control import (
57 RandomSeeder,
58 cleanup,
59 current_build_context,
60 deprecate_random_in_strategy,
61 note,
62)
63from hypothesis.errors import (
64 HypothesisSideeffectWarning,
65 HypothesisWarning,
66 InvalidArgument,
67 ResolutionFailed,
68 RewindRecursive,
69 SmallSearchSpaceWarning,
70)
71from hypothesis.internal.cathetus import cathetus
72from hypothesis.internal.charmap import (
73 as_general_categories,
74 categories as all_categories,
75)
76from hypothesis.internal.compat import (
77 Concatenate,
78 ParamSpec,
79 bit_count,
80 ceil,
81 floor,
82 get_type_hints,
83 is_typed_named_tuple,
84)
85from hypothesis.internal.conjecture.utils import calc_label_from_cls, check_sample
86from hypothesis.internal.entropy import get_seeder_and_restorer
87from hypothesis.internal.floats import float_of
88from hypothesis.internal.observability import TESTCASE_CALLBACKS
89from hypothesis.internal.reflection import (
90 define_function_signature,
91 get_pretty_function_description,
92 get_signature,
93 is_first_param_referenced_in_function,
94 nicerepr,
95 repr_call,
96 required_args,
97)
98from hypothesis.internal.validation import (
99 check_type,
100 check_valid_integer,
101 check_valid_interval,
102 check_valid_magnitude,
103 check_valid_size,
104 check_valid_sizes,
105 try_convert,
106)
107from hypothesis.strategies._internal import SearchStrategy, check_strategy
108from hypothesis.strategies._internal.collections import (
109 FixedAndOptionalKeysDictStrategy,
110 FixedKeysDictStrategy,
111 ListStrategy,
112 TupleStrategy,
113 UniqueListStrategy,
114 UniqueSampledListStrategy,
115 tuples,
116)
117from hypothesis.strategies._internal.deferred import DeferredStrategy
118from hypothesis.strategies._internal.functions import FunctionStrategy
119from hypothesis.strategies._internal.lazy import LazyStrategy, unwrap_strategies
120from hypothesis.strategies._internal.misc import BooleansStrategy, just, none, nothing
121from hypothesis.strategies._internal.numbers import (
122 IntegersStrategy,
123 Real,
124 floats,
125 integers,
126)
127from hypothesis.strategies._internal.recursive import RecursiveStrategy
128from hypothesis.strategies._internal.shared import SharedStrategy
129from hypothesis.strategies._internal.strategies import (
130 Ex,
131 Ex_Inv,
132 SampledFromStrategy,
133 T,
134 one_of,
135)
136from hypothesis.strategies._internal.strings import (
137 BytesStrategy,
138 OneCharStringStrategy,
139 TextStrategy,
140)
141from hypothesis.strategies._internal.utils import (
142 cacheable,
143 defines_strategy,
144 to_jsonable,
145)
146from hypothesis.utils.conventions import not_set
147from hypothesis.vendor.pretty import RepresentationPrinter
149if sys.version_info >= (3, 10):
150 from types import EllipsisType as EllipsisType
151 from typing import TypeAlias as TypeAlias
152elif typing.TYPE_CHECKING: # pragma: no cover
153 from builtins import ellipsis as EllipsisType
155 from typing_extensions import TypeAlias
156else:
157 EllipsisType = type(Ellipsis) # pragma: no cover
160@cacheable
161@defines_strategy(force_reusable_values=True)
162def booleans() -> SearchStrategy[bool]:
163 """Returns a strategy which generates instances of :class:`python:bool`.
165 Examples from this strategy will shrink towards ``False`` (i.e.
166 shrinking will replace ``True`` with ``False`` where possible).
167 """
168 return BooleansStrategy()
171@overload
172def sampled_from(elements: Sequence[T]) -> SearchStrategy[T]: # pragma: no cover
173 ...
176@overload
177def sampled_from(elements: Type[enum.Enum]) -> SearchStrategy[Any]: # pragma: no cover
178 # `SearchStrategy[Enum]` is unreliable due to metaclass issues.
179 ...
182@overload
183def sampled_from(
184 elements: Union[Type[enum.Enum], Sequence[Any]]
185) -> SearchStrategy[Any]: # pragma: no cover
186 ...
189@defines_strategy(try_non_lazy=True)
190def sampled_from(
191 elements: Union[Type[enum.Enum], Sequence[Any]]
192) -> SearchStrategy[Any]:
193 """Returns a strategy which generates any value present in ``elements``.
195 Note that as with :func:`~hypothesis.strategies.just`, values will not be
196 copied and thus you should be careful of using mutable data.
198 ``sampled_from`` supports ordered collections, as well as
199 :class:`~python:enum.Enum` objects. :class:`~python:enum.Flag` objects
200 may also generate any combination of their members.
202 Examples from this strategy shrink by replacing them with values earlier in
203 the list. So e.g. ``sampled_from([10, 1])`` will shrink by trying to replace
204 1 values with 10, and ``sampled_from([1, 10])`` will shrink by trying to
205 replace 10 values with 1.
207 It is an error to sample from an empty sequence, because returning :func:`nothing`
208 makes it too easy to silently drop parts of compound strategies. If you need
209 that behaviour, use ``sampled_from(seq) if seq else nothing()``.
210 """
211 values = check_sample(elements, "sampled_from")
212 try:
213 if isinstance(elements, type) and issubclass(elements, enum.Enum):
214 repr_ = f"sampled_from({elements.__module__}.{elements.__name__})"
215 else:
216 repr_ = f"sampled_from({elements!r})"
217 except Exception: # pragma: no cover
218 repr_ = None
219 if isclass(elements) and issubclass(elements, enum.Flag):
220 # Combinations of enum.Flag members (including empty) are also members. We generate these
221 # dynamically, because static allocation takes O(2^n) memory. LazyStrategy is used for the
222 # ease of force_repr.
223 # Add all named values, both flag bits (== list(elements)) and aliases. The aliases are
224 # necessary for full coverage for flags that would fail enum.NAMED_FLAGS check, and they
225 # are also nice values to shrink to.
226 flags = sorted(
227 set(elements.__members__.values()),
228 key=lambda v: (bit_count(v.value), v.value),
229 )
230 # Finally, try to construct the empty state if it is not named. It's placed at the
231 # end so that we shrink to named values.
232 flags_with_empty = flags
233 if not flags or flags[0].value != 0:
234 try:
235 flags_with_empty = [*flags, elements(0)]
236 except TypeError: # pragma: no cover
237 # Happens on some python versions (at least 3.12) when there are no named values
238 pass
239 inner = [
240 # Consider one or no named flags set, with shrink-to-named-flag behaviour.
241 # Special cases (length zero or one) are handled by the inner sampled_from.
242 sampled_from(flags_with_empty),
243 ]
244 if len(flags) > 1:
245 inner += [
246 # Uniform distribution over number of named flags or combinations set. The overlap
247 # at r=1 is intentional, it may lead to oversampling but gives consistent shrinking
248 # behaviour.
249 integers(min_value=1, max_value=len(flags))
250 .flatmap(lambda r: sets(sampled_from(flags), min_size=r, max_size=r))
251 .map(lambda s: elements(reduce(operator.or_, s))),
252 ]
253 return LazyStrategy(one_of, args=inner, kwargs={}, force_repr=repr_)
254 if not values:
255 if (
256 isinstance(elements, type)
257 and issubclass(elements, enum.Enum)
258 and vars(elements).get("__annotations__")
259 ):
260 # See https://github.com/HypothesisWorks/hypothesis/issues/2923
261 raise InvalidArgument(
262 f"Cannot sample from {elements.__module__}.{elements.__name__} "
263 "because it contains no elements. It does however have annotations, "
264 "so maybe you tried to write an enum as if it was a dataclass?"
265 )
266 raise InvalidArgument("Cannot sample from a length-zero sequence.")
267 if len(values) == 1:
268 return just(values[0])
269 return SampledFromStrategy(values, repr_)
272def identity(x):
273 return x
276@cacheable
277@defines_strategy()
278def lists(
279 elements: SearchStrategy[Ex],
280 *,
281 min_size: int = 0,
282 max_size: Optional[int] = None,
283 unique_by: Union[
284 None,
285 Callable[[Ex], Hashable],
286 Tuple[Callable[[Ex], Hashable], ...],
287 ] = None,
288 unique: bool = False,
289) -> SearchStrategy[List[Ex]]:
290 """Returns a list containing values drawn from elements with length in the
291 interval [min_size, max_size] (no bounds in that direction if these are
292 None). If max_size is 0, only the empty list will be drawn.
294 If ``unique`` is True (or something that evaluates to True), we compare direct
295 object equality, as if unique_by was ``lambda x: x``. This comparison only
296 works for hashable types.
298 If ``unique_by`` is not None it must be a callable or tuple of callables
299 returning a hashable type when given a value drawn from elements. The
300 resulting list will satisfy the condition that for ``i`` != ``j``,
301 ``unique_by(result[i])`` != ``unique_by(result[j])``.
303 If ``unique_by`` is a tuple of callables the uniqueness will be respective
304 to each callable.
306 For example, the following will produce two columns of integers with both
307 columns being unique respectively.
309 .. code-block:: pycon
311 >>> twoints = st.tuples(st.integers(), st.integers())
312 >>> st.lists(twoints, unique_by=(lambda x: x[0], lambda x: x[1]))
314 Examples from this strategy shrink by trying to remove elements from the
315 list, and by shrinking each individual element of the list.
316 """
317 check_valid_sizes(min_size, max_size)
318 check_strategy(elements, "elements")
319 if unique:
320 if unique_by is not None:
321 raise InvalidArgument(
322 "cannot specify both unique and unique_by "
323 "(you probably only want to set unique_by)"
324 )
325 else:
326 unique_by = identity
328 if max_size == 0:
329 return builds(list)
330 if unique_by is not None:
331 if not (callable(unique_by) or isinstance(unique_by, tuple)):
332 raise InvalidArgument(
333 f"{unique_by=} is not a callable or tuple of callables"
334 )
335 if callable(unique_by):
336 unique_by = (unique_by,)
337 if len(unique_by) == 0:
338 raise InvalidArgument("unique_by is empty")
339 for i, f in enumerate(unique_by):
340 if not callable(f):
341 raise InvalidArgument(f"unique_by[{i}]={f!r} is not a callable")
342 # Note that lazy strategies automatically unwrap when passed to a defines_strategy
343 # function.
344 tuple_suffixes = None
345 if (
346 # We're generating a list of tuples unique by the first element, perhaps
347 # via st.dictionaries(), and this will be more efficient if we rearrange
348 # our strategy somewhat to draw the first element then draw add the rest.
349 isinstance(elements, TupleStrategy)
350 and len(elements.element_strategies) >= 1
351 and len(unique_by) == 1
352 and (
353 # Introspection for either `itemgetter(0)`, or `lambda x: x[0]`
354 isinstance(unique_by[0], operator.itemgetter)
355 and repr(unique_by[0]) == "operator.itemgetter(0)"
356 or isinstance(unique_by[0], FunctionType)
357 and re.fullmatch(
358 get_pretty_function_description(unique_by[0]),
359 r"lambda ([a-z]+): \1\[0\]",
360 )
361 )
362 ):
363 unique_by = (identity,)
364 tuple_suffixes = TupleStrategy(elements.element_strategies[1:])
365 elements = elements.element_strategies[0]
367 # UniqueSampledListStrategy offers a substantial performance improvement for
368 # unique arrays with few possible elements, e.g. of eight-bit integer types.
369 if (
370 isinstance(elements, IntegersStrategy)
371 and None not in (elements.start, elements.end)
372 and (elements.end - elements.start) <= 255
373 ):
374 elements = SampledFromStrategy(
375 sorted(range(elements.start, elements.end + 1), key=abs)
376 if elements.end < 0 or elements.start > 0
377 else list(range(elements.end + 1))
378 + list(range(-1, elements.start - 1, -1))
379 )
381 if isinstance(elements, SampledFromStrategy):
382 element_count = len(elements.elements)
383 if min_size > element_count:
384 raise InvalidArgument(
385 f"Cannot create a collection of {min_size=} unique "
386 f"elements with values drawn from only {element_count} distinct "
387 "elements"
388 )
390 if max_size is not None:
391 max_size = min(max_size, element_count)
392 else:
393 max_size = element_count
395 return UniqueSampledListStrategy(
396 elements=elements,
397 max_size=max_size,
398 min_size=min_size,
399 keys=unique_by,
400 tuple_suffixes=tuple_suffixes,
401 )
403 return UniqueListStrategy(
404 elements=elements,
405 max_size=max_size,
406 min_size=min_size,
407 keys=unique_by,
408 tuple_suffixes=tuple_suffixes,
409 )
410 return ListStrategy(elements, min_size=min_size, max_size=max_size)
413@cacheable
414@defines_strategy()
415def sets(
416 elements: SearchStrategy[Ex],
417 *,
418 min_size: int = 0,
419 max_size: Optional[int] = None,
420) -> SearchStrategy[Set[Ex]]:
421 """This has the same behaviour as lists, but returns sets instead.
423 Note that Hypothesis cannot tell if values are drawn from elements
424 are hashable until running the test, so you can define a strategy
425 for sets of an unhashable type but it will fail at test time.
427 Examples from this strategy shrink by trying to remove elements from the
428 set, and by shrinking each individual element of the set.
429 """
430 return lists(
431 elements=elements, min_size=min_size, max_size=max_size, unique=True
432 ).map(set)
435@cacheable
436@defines_strategy()
437def frozensets(
438 elements: SearchStrategy[Ex],
439 *,
440 min_size: int = 0,
441 max_size: Optional[int] = None,
442) -> SearchStrategy[FrozenSet[Ex]]:
443 """This is identical to the sets function but instead returns
444 frozensets."""
445 return lists(
446 elements=elements, min_size=min_size, max_size=max_size, unique=True
447 ).map(frozenset)
450class PrettyIter:
451 def __init__(self, values):
452 self._values = values
453 self._iter = iter(self._values)
455 def __iter__(self):
456 return self._iter
458 def __next__(self):
459 return next(self._iter)
461 def __repr__(self):
462 return f"iter({self._values!r})"
465@defines_strategy()
466def iterables(
467 elements: SearchStrategy[Ex],
468 *,
469 min_size: int = 0,
470 max_size: Optional[int] = None,
471 unique_by: Union[
472 None,
473 Callable[[Ex], Hashable],
474 Tuple[Callable[[Ex], Hashable], ...],
475 ] = None,
476 unique: bool = False,
477) -> SearchStrategy[Iterable[Ex]]:
478 """This has the same behaviour as lists, but returns iterables instead.
480 Some iterables cannot be indexed (e.g. sets) and some do not have a
481 fixed length (e.g. generators). This strategy produces iterators,
482 which cannot be indexed and do not have a fixed length. This ensures
483 that you do not accidentally depend on sequence behaviour.
484 """
485 return lists(
486 elements=elements,
487 min_size=min_size,
488 max_size=max_size,
489 unique_by=unique_by,
490 unique=unique,
491 ).map(PrettyIter)
494@defines_strategy()
495def fixed_dictionaries(
496 mapping: Dict[T, SearchStrategy[Ex]],
497 *,
498 optional: Optional[Dict[T, SearchStrategy[Ex]]] = None,
499) -> SearchStrategy[Dict[T, Ex]]:
500 """Generates a dictionary of the same type as mapping with a fixed set of
501 keys mapping to strategies. ``mapping`` must be a dict subclass.
503 Generated values have all keys present in mapping, in iteration order,
504 with the corresponding values drawn from mapping[key].
506 If ``optional`` is passed, the generated value *may or may not* contain each
507 key from ``optional`` and a value drawn from the corresponding strategy.
508 Generated values may contain optional keys in an arbitrary order.
510 Examples from this strategy shrink by shrinking each individual value in
511 the generated dictionary, and omitting optional key-value pairs.
512 """
513 check_type(dict, mapping, "mapping")
514 for k, v in mapping.items():
515 check_strategy(v, f"mapping[{k!r}]")
516 if optional is not None:
517 check_type(dict, optional, "optional")
518 for k, v in optional.items():
519 check_strategy(v, f"optional[{k!r}]")
520 if type(mapping) != type(optional):
521 raise InvalidArgument(
522 "Got arguments of different types: mapping=%s, optional=%s"
523 % (nicerepr(type(mapping)), nicerepr(type(optional)))
524 )
525 if set(mapping) & set(optional):
526 raise InvalidArgument(
527 "The following keys were in both mapping and optional, "
528 f"which is invalid: {set(mapping) & set(optional)!r}"
529 )
530 return FixedAndOptionalKeysDictStrategy(mapping, optional)
531 return FixedKeysDictStrategy(mapping)
534@cacheable
535@defines_strategy()
536def dictionaries(
537 keys: SearchStrategy[Ex],
538 values: SearchStrategy[T],
539 *,
540 dict_class: type = dict,
541 min_size: int = 0,
542 max_size: Optional[int] = None,
543) -> SearchStrategy[Dict[Ex, T]]:
544 # Describing the exact dict_class to Mypy drops the key and value types,
545 # so we report Dict[K, V] instead of Mapping[Any, Any] for now. Sorry!
546 """Generates dictionaries of type ``dict_class`` with keys drawn from the ``keys``
547 argument and values drawn from the ``values`` argument.
549 The size parameters have the same interpretation as for
550 :func:`~hypothesis.strategies.lists`.
552 Examples from this strategy shrink by trying to remove keys from the
553 generated dictionary, and by shrinking each generated key and value.
554 """
555 check_valid_sizes(min_size, max_size)
556 if max_size == 0:
557 return fixed_dictionaries(dict_class())
558 check_strategy(keys, "keys")
559 check_strategy(values, "values")
561 return lists(
562 tuples(keys, values),
563 min_size=min_size,
564 max_size=max_size,
565 unique_by=operator.itemgetter(0),
566 ).map(dict_class)
569# See https://en.wikipedia.org/wiki/Unicode_character_property#General_Category
570CategoryName: "TypeAlias" = Literal[
571 "L", # Letter
572 "Lu", # Letter, uppercase
573 "Ll", # Letter, lowercase
574 "Lt", # Letter, titlecase
575 "Lm", # Letter, modifier
576 "Lo", # Letter, other
577 "M", # Mark
578 "Mn", # Mark, nonspacing
579 "Mc", # Mark, spacing combining
580 "Me", # Mark, enclosing
581 "N", # Number
582 "Nd", # Number, decimal digit
583 "Nl", # Number, letter
584 "No", # Number, other
585 "P", # Punctuation
586 "Pc", # Punctuation, connector
587 "Pd", # Punctuation, dash
588 "Ps", # Punctuation, open
589 "Pe", # Punctuation, close
590 "Pi", # Punctuation, initial quote
591 "Pf", # Punctuation, final quote
592 "Po", # Punctuation, other
593 "S", # Symbol
594 "Sm", # Symbol, math
595 "Sc", # Symbol, currency
596 "Sk", # Symbol, modifier
597 "So", # Symbol, other
598 "Z", # Separator
599 "Zs", # Separator, space
600 "Zl", # Separator, line
601 "Zp", # Separator, paragraph
602 "C", # Other
603 "Cc", # Other, control
604 "Cf", # Other, format
605 "Cs", # Other, surrogate
606 "Co", # Other, private use
607 "Cn", # Other, not assigned
608]
611@cacheable
612@defines_strategy(force_reusable_values=True)
613def characters(
614 *,
615 codec: Optional[str] = None,
616 min_codepoint: Optional[int] = None,
617 max_codepoint: Optional[int] = None,
618 categories: Optional[Collection[CategoryName]] = None,
619 exclude_categories: Optional[Collection[CategoryName]] = None,
620 exclude_characters: Optional[Collection[str]] = None,
621 include_characters: Optional[Collection[str]] = None,
622 # Note: these arguments are deprecated aliases for backwards compatibility
623 blacklist_categories: Optional[Collection[CategoryName]] = None,
624 whitelist_categories: Optional[Collection[CategoryName]] = None,
625 blacklist_characters: Optional[Collection[str]] = None,
626 whitelist_characters: Optional[Collection[str]] = None,
627) -> SearchStrategy[str]:
628 r"""Generates characters, length-one :class:`python:str`\ ings,
629 following specified filtering rules.
631 - When no filtering rules are specified, any character can be produced.
632 - If ``min_codepoint`` or ``max_codepoint`` is specified, then only
633 characters having a codepoint in that range will be produced.
634 - If ``categories`` is specified, then only characters from those
635 Unicode categories will be produced. This is a further restriction,
636 characters must also satisfy ``min_codepoint`` and ``max_codepoint``.
637 - If ``exclude_categories`` is specified, then any character from those
638 categories will not be produced. You must not pass both ``categories``
639 and ``exclude_categories``; these arguments are alternative ways to
640 specify exactly the same thing.
641 - If ``include_characters`` is specified, then any additional characters
642 in that list will also be produced.
643 - If ``exclude_characters`` is specified, then any characters in
644 that list will be not be produced. Any overlap between
645 ``include_characters`` and ``exclude_characters`` will raise an
646 exception.
647 - If ``codec`` is specified, only characters in the specified `codec encodings`_
648 will be produced.
650 The ``_codepoint`` arguments must be integers between zero and
651 :obj:`python:sys.maxunicode`. The ``_characters`` arguments must be
652 collections of length-one unicode strings, such as a unicode string.
654 The ``_categories`` arguments must be used to specify either the
655 one-letter Unicode major category or the two-letter Unicode
656 `general category`_. For example, ``('Nd', 'Lu')`` signifies "Number,
657 decimal digit" and "Letter, uppercase". A single letter ('major category')
658 can be given to match all corresponding categories, for example ``'P'``
659 for characters in any punctuation category.
661 We allow codecs from the :mod:`codecs` module and their aliases, platform
662 specific and user-registered codecs if they are available, and
663 `python-specific text encodings`_ (but not text or binary transforms).
664 ``include_characters`` which cannot be encoded using this codec will
665 raise an exception. If non-encodable codepoints or categories are
666 explicitly allowed, the ``codec`` argument will exclude them without
667 raising an exception.
669 .. _general category: https://wikipedia.org/wiki/Unicode_character_property
670 .. _codec encodings: https://docs.python.org/3/library/codecs.html#encodings-and-unicode
671 .. _python-specific text encodings: https://docs.python.org/3/library/codecs.html#python-specific-encodings
673 Examples from this strategy shrink towards the codepoint for ``'0'``,
674 or the first allowable codepoint after it if ``'0'`` is excluded.
675 """
676 check_valid_size(min_codepoint, "min_codepoint")
677 check_valid_size(max_codepoint, "max_codepoint")
678 check_valid_interval(min_codepoint, max_codepoint, "min_codepoint", "max_codepoint")
680 if categories is not None and exclude_categories is not None:
681 raise InvalidArgument(
682 f"Pass at most one of {categories=} and {exclude_categories=} - "
683 "these arguments both specify which categories are allowed, so it "
684 "doesn't make sense to use both in a single call."
685 )
687 # Handle deprecation of whitelist/blacklist arguments
688 has_old_arg = any(v is not None for k, v in locals().items() if "list" in k)
689 has_new_arg = any(v is not None for k, v in locals().items() if "lude" in k)
690 if has_old_arg and has_new_arg:
691 raise InvalidArgument(
692 "The deprecated blacklist/whitelist arguments cannot be used in "
693 "the same call as their replacement include/exclude arguments."
694 )
695 if blacklist_categories is not None:
696 exclude_categories = blacklist_categories
697 if whitelist_categories is not None:
698 categories = whitelist_categories
699 if blacklist_characters is not None:
700 exclude_characters = blacklist_characters
701 if whitelist_characters is not None:
702 include_characters = whitelist_characters
704 if (
705 min_codepoint is None
706 and max_codepoint is None
707 and categories is None
708 and exclude_categories is None
709 and include_characters is not None
710 and codec is None
711 ):
712 raise InvalidArgument(
713 "Nothing is excluded by other arguments, so passing only "
714 f"{include_characters=} would have no effect. "
715 "Also pass categories=(), or use "
716 f"sampled_from({include_characters!r}) instead."
717 )
718 exclude_characters = exclude_characters or ""
719 include_characters = include_characters or ""
720 overlap = set(exclude_characters).intersection(include_characters)
721 if overlap:
722 raise InvalidArgument(
723 f"Characters {sorted(overlap)!r} are present in both "
724 f"{include_characters=} and {exclude_characters=}"
725 )
726 categories = as_general_categories(categories, "categories")
727 exclude_categories = as_general_categories(exclude_categories, "exclude_categories")
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# Cache size is limited by sys.maxunicode, but passing None makes it slightly faster.
793@lru_cache(maxsize=None)
794def _check_is_single_character(c):
795 # In order to mitigate the performance cost of this check, we use a shared cache,
796 # even at the cost of showing the culprit strategy in the error message.
797 if not isinstance(c, str):
798 type_ = get_pretty_function_description(type(c))
799 raise InvalidArgument(f"Got non-string {c!r} (type {type_})")
800 if len(c) != 1:
801 raise InvalidArgument(f"Got {c!r} (length {len(c)} != 1)")
802 return c
805@cacheable
806@defines_strategy(force_reusable_values=True)
807def text(
808 alphabet: Union[Collection[str], SearchStrategy[str]] = characters(codec="utf-8"),
809 *,
810 min_size: int = 0,
811 max_size: Optional[int] = None,
812) -> SearchStrategy[str]:
813 """Generates strings with characters drawn from ``alphabet``, which should
814 be a collection of length one strings or a strategy generating such strings.
816 The default alphabet strategy can generate the full unicode range but
817 excludes surrogate characters because they are invalid in the UTF-8
818 encoding. You can use :func:`~hypothesis.strategies.characters` without
819 arguments to find surrogate-related bugs such as :bpo:`34454`.
821 ``min_size`` and ``max_size`` have the usual interpretations.
822 Note that Python measures string length by counting codepoints: U+00C5
823 ``Å`` is a single character, while U+0041 U+030A ``Å`` is two - the ``A``,
824 and a combining ring above.
826 Examples from this strategy shrink towards shorter strings, and with the
827 characters in the text shrinking as per the alphabet strategy.
828 This strategy does not :func:`~python:unicodedata.normalize` examples,
829 so generated strings may be in any or none of the 'normal forms'.
830 """
831 check_valid_sizes(min_size, max_size)
832 if isinstance(alphabet, SearchStrategy):
833 char_strategy = unwrap_strategies(alphabet)
834 if isinstance(char_strategy, SampledFromStrategy):
835 # Check this via the up-front validation logic below, and incidentally
836 # convert into a `characters()` strategy for standard text shrinking.
837 return text(char_strategy.elements, min_size=min_size, max_size=max_size)
838 elif not isinstance(char_strategy, OneCharStringStrategy):
839 char_strategy = char_strategy.map(_check_is_single_character)
840 else:
841 non_string = [c for c in alphabet if not isinstance(c, str)]
842 if non_string:
843 raise InvalidArgument(
844 "The following elements in alphabet are not unicode "
845 f"strings: {non_string!r}"
846 )
847 not_one_char = [c for c in alphabet if len(c) != 1]
848 if not_one_char:
849 raise InvalidArgument(
850 "The following elements in alphabet are not of length one, "
851 f"which leads to violation of size constraints: {not_one_char!r}"
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 return TextStrategy(char_strategy, min_size=min_size, max_size=max_size)
863@overload
864def from_regex(
865 regex: Union[bytes, Pattern[bytes]],
866 *,
867 fullmatch: bool = False,
868) -> SearchStrategy[bytes]: # pragma: no cover
869 ...
872@overload
873def from_regex(
874 regex: Union[str, Pattern[str]],
875 *,
876 fullmatch: bool = False,
877 alphabet: Union[str, SearchStrategy[str]] = characters(codec="utf-8"),
878) -> SearchStrategy[str]: # pragma: no cover
879 ...
882@cacheable
883@defines_strategy()
884def from_regex(
885 regex: Union[AnyStr, Pattern[AnyStr]],
886 *,
887 fullmatch: bool = False,
888 alphabet: Union[str, SearchStrategy[str], None] = None,
889) -> SearchStrategy[AnyStr]:
890 r"""Generates strings that contain a match for the given regex (i.e. ones
891 for which :func:`python:re.search` will return a non-None result).
893 ``regex`` may be a pattern or :func:`compiled regex <python:re.compile>`.
894 Both byte-strings and unicode strings are supported, and will generate
895 examples of the same type.
897 You can use regex flags such as :obj:`python:re.IGNORECASE` or
898 :obj:`python:re.DOTALL` to control generation. Flags can be passed either
899 in compiled regex or inside the pattern with a ``(?iLmsux)`` group.
901 Some regular expressions are only partly supported - the underlying
902 strategy checks local matching and relies on filtering to resolve
903 context-dependent expressions. Using too many of these constructs may
904 cause health-check errors as too many examples are filtered out. This
905 mainly includes (positive or negative) lookahead and lookbehind groups.
907 If you want the generated string to match the whole regex you should use
908 boundary markers. So e.g. ``r"\A.\Z"`` will return a single character
909 string, while ``"."`` will return any string, and ``r"\A.$"`` will return
910 a single character optionally followed by a ``"\n"``.
911 Alternatively, passing ``fullmatch=True`` will ensure that the whole
912 string is a match, as if you had used the ``\A`` and ``\Z`` markers.
914 The ``alphabet=`` argument constrains the characters in the generated
915 string, as for :func:`text`, and is only supported for unicode strings.
917 Examples from this strategy shrink towards shorter strings and lower
918 character values, with exact behaviour that may depend on the pattern.
919 """
920 check_type((str, bytes, re.Pattern), regex, "regex")
921 check_type(bool, fullmatch, "fullmatch")
922 pattern = regex.pattern if isinstance(regex, re.Pattern) else regex
923 if alphabet is not None:
924 check_type((str, SearchStrategy), alphabet, "alphabet")
925 if not isinstance(pattern, str):
926 raise InvalidArgument("alphabet= is not supported for bytestrings")
928 if isinstance(alphabet, str):
929 alphabet = characters(categories=(), include_characters=alphabet)
930 char_strategy = unwrap_strategies(alphabet)
931 if isinstance(char_strategy, SampledFromStrategy):
932 alphabet = characters(
933 categories=(),
934 include_characters=alphabet.elements, # type: ignore
935 )
936 elif not isinstance(char_strategy, OneCharStringStrategy):
937 raise InvalidArgument(
938 f"{alphabet=} must be a sampled_from() or characters() strategy"
939 )
940 elif isinstance(pattern, str):
941 alphabet = characters(codec="utf-8")
943 # TODO: We would like to move this to the top level, but pending some major
944 # refactoring it's hard to do without creating circular imports.
945 from hypothesis.strategies._internal.regex import regex_strategy
947 return regex_strategy(regex, fullmatch, alphabet=alphabet)
950@cacheable
951@defines_strategy(force_reusable_values=True)
952def binary(
953 *,
954 min_size: int = 0,
955 max_size: Optional[int] = None,
956) -> SearchStrategy[bytes]:
957 """Generates :class:`python:bytes`.
959 The generated :class:`python:bytes` will have a length of at least ``min_size``
960 and at most ``max_size``. If ``max_size`` is None there is no upper limit.
962 Examples from this strategy shrink towards smaller strings and lower byte
963 values.
964 """
965 check_valid_sizes(min_size, max_size)
966 return BytesStrategy(min_size, max_size)
969@cacheable
970@defines_strategy()
971def randoms(
972 *,
973 note_method_calls: bool = False,
974 use_true_random: bool = False,
975) -> SearchStrategy[random.Random]:
976 """Generates instances of ``random.Random``. The generated Random instances
977 are of a special HypothesisRandom subclass.
979 - If ``note_method_calls`` is set to ``True``, Hypothesis will print the
980 randomly drawn values in any falsifying test case. This can be helpful
981 for debugging the behaviour of randomized algorithms.
982 - If ``use_true_random`` is set to ``True`` then values will be drawn from
983 their usual distribution, otherwise they will actually be Hypothesis
984 generated values (and will be shrunk accordingly for any failing test
985 case). Setting ``use_true_random=False`` will tend to expose bugs that
986 would occur with very low probability when it is set to True, and this
987 flag should only be set to True when your code relies on the distribution
988 of values for correctness.
990 For managing global state, see the :func:`~hypothesis.strategies.random_module`
991 strategy and :func:`~hypothesis.register_random` function.
992 """
993 check_type(bool, note_method_calls, "note_method_calls")
994 check_type(bool, use_true_random, "use_true_random")
996 from hypothesis.strategies._internal.random import RandomStrategy
998 return RandomStrategy(
999 use_true_random=use_true_random, note_method_calls=note_method_calls
1000 )
1003class RandomModule(SearchStrategy):
1004 def do_draw(self, data):
1005 # It would be unsafe to do run this method more than once per test case,
1006 # because cleanup() runs tasks in FIFO order (at time of writing!).
1007 # Fortunately, the random_module() strategy wraps us in shared(), so
1008 # it's cached for all but the first of any number of calls.
1009 seed = data.draw(integers(0, 2**32 - 1))
1010 seed_all, restore_all = get_seeder_and_restorer(seed)
1011 seed_all()
1012 cleanup(restore_all)
1013 return RandomSeeder(seed)
1016@cacheable
1017@defines_strategy()
1018def random_module() -> SearchStrategy[RandomSeeder]:
1019 """Hypothesis always seeds global PRNGs before running a test, and restores the
1020 previous state afterwards.
1022 If having a fixed seed would unacceptably weaken your tests, and you
1023 cannot use a ``random.Random`` instance provided by
1024 :func:`~hypothesis.strategies.randoms`, this strategy calls
1025 :func:`python:random.seed` with an arbitrary integer and passes you
1026 an opaque object whose repr displays the seed value for debugging.
1027 If ``numpy.random`` is available, that state is also managed, as is anything
1028 managed by :func:`hypothesis.register_random`.
1030 Examples from these strategy shrink to seeds closer to zero.
1031 """
1032 return shared(RandomModule(), key="hypothesis.strategies.random_module()")
1035class BuildsStrategy(SearchStrategy):
1036 def __init__(self, target, args, kwargs):
1037 self.target = target
1038 self.args = args
1039 self.kwargs = kwargs
1041 def do_draw(self, data):
1042 args = [data.draw(a) for a in self.args]
1043 kwargs = {k: data.draw(v) for k, v in self.kwargs.items()}
1044 try:
1045 obj = self.target(*args, **kwargs)
1046 except TypeError as err:
1047 if (
1048 isinstance(self.target, type)
1049 and issubclass(self.target, enum.Enum)
1050 and not (self.args or self.kwargs)
1051 ):
1052 name = self.target.__module__ + "." + self.target.__qualname__
1053 raise InvalidArgument(
1054 f"Calling {name} with no arguments raised an error - "
1055 f"try using sampled_from({name}) instead of builds({name})"
1056 ) from err
1057 if not (self.args or self.kwargs):
1058 from .types import is_a_new_type, is_generic_type
1060 if is_a_new_type(self.target) or is_generic_type(self.target):
1061 raise InvalidArgument(
1062 f"Calling {self.target!r} with no arguments raised an "
1063 f"error - try using from_type({self.target!r}) instead "
1064 f"of builds({self.target!r})"
1065 ) from err
1066 if getattr(self.target, "__no_type_check__", None) is True:
1067 # Note: could use PEP-678 __notes__ here. Migrate over once we're
1068 # using an `exceptiongroup` backport with support for that.
1069 raise TypeError(
1070 "This might be because the @no_type_check decorator prevented "
1071 "Hypothesis from inferring a strategy for some required arguments."
1072 ) from err
1073 raise
1075 current_build_context().record_call(obj, self.target, args, kwargs)
1076 return obj
1078 def validate(self):
1079 tuples(*self.args).validate()
1080 fixed_dictionaries(self.kwargs).validate()
1082 def __repr__(self):
1083 bits = [get_pretty_function_description(self.target)]
1084 bits.extend(map(repr, self.args))
1085 bits.extend(f"{k}={v!r}" for k, v in self.kwargs.items())
1086 return f"builds({', '.join(bits)})"
1089@cacheable
1090@defines_strategy()
1091def builds(
1092 target: Callable[..., Ex],
1093 /,
1094 *args: SearchStrategy[Any],
1095 **kwargs: Union[SearchStrategy[Any], EllipsisType],
1096) -> SearchStrategy[Ex]:
1097 """Generates values by drawing from ``args`` and ``kwargs`` and passing
1098 them to the callable (provided as the first positional argument) in the
1099 appropriate argument position.
1101 e.g. ``builds(target, integers(), flag=booleans())`` would draw an
1102 integer ``i`` and a boolean ``b`` and call ``target(i, flag=b)``.
1104 If the callable has type annotations, they will be used to infer a strategy
1105 for required arguments that were not passed to builds. You can also tell
1106 builds to infer a strategy for an optional argument by passing ``...``
1107 (:obj:`python:Ellipsis`) as a keyword argument to builds, instead of a strategy for
1108 that argument to the callable.
1110 If the callable is a class defined with :pypi:`attrs`, missing required
1111 arguments will be inferred from the attribute on a best-effort basis,
1112 e.g. by checking :ref:`attrs standard validators <attrs:api-validators>`.
1113 Dataclasses are handled natively by the inference from type hints.
1115 Examples from this strategy shrink by shrinking the argument values to
1116 the callable.
1117 """
1118 if not callable(target):
1119 raise InvalidArgument(
1120 "The first positional argument to builds() must be a callable "
1121 "target to construct."
1122 )
1124 if ... in args: # type: ignore # we only annotated the allowed types
1125 # Avoid an implementation nightmare juggling tuples and worse things
1126 raise InvalidArgument(
1127 "... was passed as a positional argument to "
1128 "builds(), but is only allowed as a keyword arg"
1129 )
1130 required = required_args(target, args, kwargs)
1131 to_infer = {k for k, v in kwargs.items() if v is ...}
1132 if required or to_infer:
1133 if isinstance(target, type) and attr.has(target):
1134 # Use our custom introspection for attrs classes
1135 from hypothesis.strategies._internal.attrs import from_attrs
1137 return from_attrs(target, args, kwargs, required | to_infer)
1138 # Otherwise, try using type hints
1139 hints = get_type_hints(target)
1140 if to_infer - set(hints):
1141 badargs = ", ".join(sorted(to_infer - set(hints)))
1142 raise InvalidArgument(
1143 f"passed ... for {badargs}, but we cannot infer a strategy "
1144 "because these arguments have no type annotation"
1145 )
1146 infer_for = {k: v for k, v in hints.items() if k in (required | to_infer)}
1147 if infer_for:
1148 from hypothesis.strategies._internal.types import _global_type_lookup
1150 for kw, t in infer_for.items():
1151 if t in _global_type_lookup:
1152 kwargs[kw] = from_type(t)
1153 else:
1154 # We defer resolution of these type annotations so that the obvious
1155 # approach to registering recursive types just works. I.e.,
1156 # if we're inside `register_type_strategy(cls, builds(cls, ...))`
1157 # and `...` contains recursion on `cls`. See
1158 # https://github.com/HypothesisWorks/hypothesis/issues/3026
1159 kwargs[kw] = deferred(lambda t=t: from_type(t)) # type: ignore
1160 return BuildsStrategy(target, args, kwargs)
1163@cacheable
1164@defines_strategy(never_lazy=True)
1165def from_type(thing: Type[Ex_Inv]) -> SearchStrategy[Ex_Inv]:
1166 """Looks up the appropriate search strategy for the given type.
1168 ``from_type`` is used internally to fill in missing arguments to
1169 :func:`~hypothesis.strategies.builds` and can be used interactively
1170 to explore what strategies are available or to debug type resolution.
1172 You can use :func:`~hypothesis.strategies.register_type_strategy` to
1173 handle your custom types, or to globally redefine certain strategies -
1174 for example excluding NaN from floats, or use timezone-aware instead of
1175 naive time and datetime strategies.
1177 The resolution logic may be changed in a future version, but currently
1178 tries these five options:
1180 1. If ``thing`` is in the default lookup mapping or user-registered lookup,
1181 return the corresponding strategy. The default lookup covers all types
1182 with Hypothesis strategies, including extras where possible.
1183 2. If ``thing`` is from the :mod:`python:typing` module, return the
1184 corresponding strategy (special logic).
1185 3. If ``thing`` has one or more subtypes in the merged lookup, return
1186 the union of the strategies for those types that are not subtypes of
1187 other elements in the lookup.
1188 4. Finally, if ``thing`` has type annotations for all required arguments,
1189 and is not an abstract class, it is resolved via
1190 :func:`~hypothesis.strategies.builds`.
1191 5. Because :mod:`abstract types <python:abc>` cannot be instantiated,
1192 we treat abstract types as the union of their concrete subclasses.
1193 Note that this lookup works via inheritance but not via
1194 :obj:`~python:abc.ABCMeta.register`, so you may still need to use
1195 :func:`~hypothesis.strategies.register_type_strategy`.
1197 There is a valuable recipe for leveraging ``from_type()`` to generate
1198 "everything except" values from a specified type. I.e.
1200 .. code-block:: python
1202 def everything_except(excluded_types):
1203 return (
1204 from_type(type)
1205 .flatmap(from_type)
1206 .filter(lambda x: not isinstance(x, excluded_types))
1207 )
1209 For example, ``everything_except(int)`` returns a strategy that can
1210 generate anything that ``from_type()`` can ever generate, except for
1211 instances of :class:`python:int`, and excluding instances of types
1212 added via :func:`~hypothesis.strategies.register_type_strategy`.
1214 This is useful when writing tests which check that invalid input is
1215 rejected in a certain way.
1216 """
1217 try:
1218 with warnings.catch_warnings():
1219 warnings.simplefilter("error")
1220 return _from_type(thing)
1221 except Exception:
1222 return _from_type_deferred(thing)
1225def _from_type_deferred(thing: Type[Ex]) -> SearchStrategy[Ex]:
1226 # This tricky little dance is because we want to show the repr of the actual
1227 # underlying strategy wherever possible, as a form of user education, but
1228 # would prefer to fall back to the default "from_type(...)" repr instead of
1229 # "deferred(...)" for recursive types or invalid arguments.
1230 try:
1231 thing_repr = nicerepr(thing)
1232 if hasattr(thing, "__module__"):
1233 module_prefix = f"{thing.__module__}."
1234 if not thing_repr.startswith(module_prefix):
1235 thing_repr = module_prefix + thing_repr
1236 repr_ = f"from_type({thing_repr})"
1237 except Exception: # pragma: no cover
1238 repr_ = None
1239 return LazyStrategy(
1240 lambda thing: deferred(lambda: _from_type(thing)),
1241 (thing,),
1242 {},
1243 force_repr=repr_,
1244 )
1247_recurse_guard: ContextVar = ContextVar("recurse_guard")
1250def _from_type(thing: Type[Ex]) -> SearchStrategy[Ex]:
1251 # TODO: We would like to move this to the top level, but pending some major
1252 # refactoring it's hard to do without creating circular imports.
1253 from hypothesis.strategies._internal import types
1255 def as_strategy(strat_or_callable, thing):
1256 # User-provided strategies need some validation, and callables even more
1257 # of it. We do this in three places, hence the helper function
1258 if not isinstance(strat_or_callable, SearchStrategy):
1259 assert callable(strat_or_callable) # Validated in register_type_strategy
1260 strategy = strat_or_callable(thing)
1261 else:
1262 strategy = strat_or_callable
1263 if strategy is NotImplemented:
1264 return NotImplemented
1265 if not isinstance(strategy, SearchStrategy):
1266 raise ResolutionFailed(
1267 f"Error: {thing} was registered for {nicerepr(strat_or_callable)}, "
1268 f"but returned non-strategy {strategy!r}"
1269 )
1270 if strategy.is_empty:
1271 raise ResolutionFailed(f"Error: {thing!r} resolved to an empty strategy")
1272 return strategy
1274 def from_type_guarded(thing):
1275 """Returns the result of producer, or ... if recursion on thing is encountered"""
1276 try:
1277 recurse_guard = _recurse_guard.get()
1278 except LookupError:
1279 # We can't simply define the contextvar with default=[], as the
1280 # default object would be shared across contexts
1281 _recurse_guard.set(recurse_guard := [])
1282 if thing in recurse_guard:
1283 raise RewindRecursive(thing)
1284 recurse_guard.append(thing)
1285 try:
1286 return _from_type(thing)
1287 except RewindRecursive as rr:
1288 if rr.target != thing:
1289 raise
1290 return ... # defer resolution
1291 finally:
1292 recurse_guard.pop()
1294 # Let registered extra modules handle their own recognized types first, before
1295 # e.g. Unions are resolved
1296 try:
1297 known = thing in types._global_type_lookup
1298 except TypeError:
1299 # thing is not always hashable!
1300 pass
1301 else:
1302 if not known:
1303 for module, resolver in types._global_extra_lookup.items():
1304 if module in sys.modules:
1305 strat = resolver(thing)
1306 if strat is not None:
1307 return strat
1308 if not isinstance(thing, type):
1309 if types.is_a_new_type(thing):
1310 # Check if we have an explicitly registered strategy for this thing,
1311 # resolve it so, and otherwise resolve as for the base type.
1312 if thing in types._global_type_lookup:
1313 strategy = as_strategy(types._global_type_lookup[thing], thing)
1314 if strategy is not NotImplemented:
1315 return strategy
1316 return _from_type(thing.__supertype__)
1317 # Unions are not instances of `type` - but we still want to resolve them!
1318 if types.is_a_union(thing):
1319 args = sorted(thing.__args__, key=types.type_sorting_key)
1320 return one_of([_from_type(t) for t in args])
1321 # We also have a special case for TypeVars.
1322 # They are represented as instances like `~T` when they come here.
1323 # We need to work with their type instead.
1324 if isinstance(thing, TypeVar) and type(thing) in types._global_type_lookup:
1325 strategy = as_strategy(types._global_type_lookup[type(thing)], thing)
1326 if strategy is not NotImplemented:
1327 return strategy
1328 if not types.is_a_type(thing):
1329 if isinstance(thing, str):
1330 # See https://github.com/HypothesisWorks/hypothesis/issues/3016
1331 raise InvalidArgument(
1332 f"Got {thing!r} as a type annotation, but the forward-reference "
1333 "could not be resolved from a string to a type. Consider using "
1334 "`from __future__ import annotations` instead of forward-reference "
1335 "strings."
1336 )
1337 raise InvalidArgument(f"{thing=} must be a type") # pragma: no cover
1338 if thing in types.NON_RUNTIME_TYPES:
1339 # Some code like `st.from_type(TypeAlias)` does not make sense.
1340 # Because there are types in python that do not exist in runtime.
1341 raise InvalidArgument(
1342 f"Could not resolve {thing!r} to a strategy, "
1343 f"because there is no such thing as a runtime instance of {thing!r}"
1344 )
1345 # Now that we know `thing` is a type, the first step is to check for an
1346 # explicitly registered strategy. This is the best (and hopefully most
1347 # common) way to resolve a type to a strategy. Note that the value in the
1348 # lookup may be a strategy or a function from type -> strategy; and we
1349 # convert empty results into an explicit error.
1350 try:
1351 if thing in types._global_type_lookup:
1352 strategy = as_strategy(types._global_type_lookup[thing], thing)
1353 if strategy is not NotImplemented:
1354 return strategy
1355 except TypeError: # pragma: no cover
1356 # This is due to a bizarre divergence in behaviour under Python 3.9.0:
1357 # typing.Callable[[], foo] has __args__ = (foo,) but collections.abc.Callable
1358 # has __args__ = ([], foo); and as a result is non-hashable.
1359 pass
1360 if (
1361 hasattr(typing, "_TypedDictMeta")
1362 and type(thing) is typing._TypedDictMeta
1363 or hasattr(types.typing_extensions, "_TypedDictMeta") # type: ignore
1364 and type(thing) is types.typing_extensions._TypedDictMeta # type: ignore
1365 ): # pragma: no cover
1366 # The __optional_keys__ attribute may or may not be present, but if there's no
1367 # way to tell and we just have to assume that everything is required.
1368 # See https://github.com/python/cpython/pull/17214 for details.
1369 optional = set(getattr(thing, "__optional_keys__", ()))
1370 anns = {}
1371 for k, v in get_type_hints(thing).items():
1372 origin = get_origin(v)
1373 if origin in types.RequiredTypes + types.NotRequiredTypes:
1374 if origin in types.NotRequiredTypes:
1375 optional.add(k)
1376 else:
1377 optional.discard(k)
1378 try:
1379 v = v.__args__[0]
1380 except IndexError:
1381 raise InvalidArgument(
1382 f"`{k}: {v.__name__}` is not a valid type annotation"
1383 ) from None
1384 anns[k] = from_type_guarded(v)
1385 if anns[k] is ...:
1386 anns[k] = _from_type_deferred(v)
1387 if (
1388 (not anns)
1389 and thing.__annotations__
1390 and ".<locals>." in getattr(thing, "__qualname__", "")
1391 ):
1392 raise InvalidArgument("Failed to retrieve type annotations for local type")
1393 return fixed_dictionaries( # type: ignore
1394 mapping={k: v for k, v in anns.items() if k not in optional},
1395 optional={k: v for k, v in anns.items() if k in optional},
1396 )
1398 # If there's no explicitly registered strategy, maybe a subtype of thing
1399 # is registered - if so, we can resolve it to the subclass strategy.
1400 # We'll start by checking if thing is from from the typing module,
1401 # because there are several special cases that don't play well with
1402 # subclass and instance checks.
1403 if isinstance(thing, types.typing_root_type) or (
1404 sys.version_info[:2] >= (3, 9)
1405 and isinstance(get_origin(thing), type)
1406 and get_args(thing)
1407 ):
1408 return types.from_typing_type(thing)
1409 # If it's not from the typing module, we get all registered types that are
1410 # a subclass of `thing` and are not themselves a subtype of any other such
1411 # type. For example, `Number -> integers() | floats()`, but bools() is
1412 # not included because bool is a subclass of int as well as Number.
1413 strategies = [
1414 s
1415 for s in (
1416 as_strategy(v, thing)
1417 for k, v in sorted(types._global_type_lookup.items(), key=repr)
1418 if isinstance(k, type)
1419 and issubclass(k, thing)
1420 and sum(types.try_issubclass(k, typ) for typ in types._global_type_lookup)
1421 == 1
1422 )
1423 if s is not NotImplemented
1424 ]
1425 if any(not s.is_empty for s in strategies):
1426 return one_of(strategies)
1427 # If we don't have a strategy registered for this type or any subtype, we
1428 # may be able to fall back on type annotations.
1429 if issubclass(thing, enum.Enum):
1430 return sampled_from(thing)
1431 # Finally, try to build an instance by calling the type object. Unlike builds(),
1432 # this block *does* try to infer strategies for arguments with default values.
1433 # That's because of the semantic different; builds() -> "call this with ..."
1434 # so we only infer when *not* doing so would be an error; from_type() -> "give
1435 # me arbitrary instances" so the greater variety is acceptable.
1436 # And if it's *too* varied, express your opinions with register_type_strategy()
1437 if not isabstract(thing):
1438 # If we know that builds(thing) will fail, give a better error message
1439 required = required_args(thing)
1440 if required and not (
1441 required.issubset(get_type_hints(thing))
1442 or attr.has(thing)
1443 or is_typed_named_tuple(thing) # weird enough that we have a specific check
1444 ):
1445 raise ResolutionFailed(
1446 f"Could not resolve {thing!r} to a strategy; consider "
1447 "using register_type_strategy"
1448 )
1449 try:
1450 hints = get_type_hints(thing)
1451 params = get_signature(thing).parameters
1452 except Exception:
1453 params = {} # type: ignore
1454 kwargs = {}
1455 for k, p in params.items():
1456 if (
1457 k in hints
1458 and k != "return"
1459 and p.kind in (Parameter.POSITIONAL_OR_KEYWORD, Parameter.KEYWORD_ONLY)
1460 ):
1461 kwargs[k] = from_type_guarded(hints[k])
1462 if p.default is not Parameter.empty and kwargs[k] is not ...:
1463 kwargs[k] = just(p.default) | kwargs[k]
1464 if params and not kwargs and not issubclass(thing, BaseException):
1465 from_type_repr = repr_call(from_type, (thing,), {})
1466 builds_repr = repr_call(builds, (thing,), {})
1467 warnings.warn(
1468 f"{from_type_repr} resolved to {builds_repr}, because we could not "
1469 "find any (non-varargs) arguments. Use st.register_type_strategy() "
1470 "to resolve to a strategy which can generate more than one value, "
1471 "or silence this warning.",
1472 SmallSearchSpaceWarning,
1473 stacklevel=2,
1474 )
1475 return builds(thing, **kwargs)
1476 # And if it's an abstract type, we'll resolve to a union of subclasses instead.
1477 subclasses = thing.__subclasses__()
1478 if not subclasses:
1479 raise ResolutionFailed(
1480 f"Could not resolve {thing!r} to a strategy, because it is an abstract "
1481 "type without any subclasses. Consider using register_type_strategy"
1482 )
1483 subclass_strategies = nothing()
1484 for sc in subclasses:
1485 try:
1486 subclass_strategies |= _from_type(sc)
1487 except Exception:
1488 pass
1489 if subclass_strategies.is_empty:
1490 # We're unable to resolve subclasses now, but we might be able to later -
1491 # so we'll just go back to the mixed distribution.
1492 return sampled_from(subclasses).flatmap(_from_type)
1493 return subclass_strategies
1496@cacheable
1497@defines_strategy(force_reusable_values=True)
1498def fractions(
1499 min_value: Optional[Union[Real, str]] = None,
1500 max_value: Optional[Union[Real, str]] = None,
1501 *,
1502 max_denominator: Optional[int] = None,
1503) -> SearchStrategy[Fraction]:
1504 """Returns a strategy which generates Fractions.
1506 If ``min_value`` is not None then all generated values are no less than
1507 ``min_value``. If ``max_value`` is not None then all generated values are no
1508 greater than ``max_value``. ``min_value`` and ``max_value`` may be anything accepted
1509 by the :class:`~fractions.Fraction` constructor.
1511 If ``max_denominator`` is not None then the denominator of any generated
1512 values is no greater than ``max_denominator``. Note that ``max_denominator`` must
1513 be None or a positive integer.
1515 Examples from this strategy shrink towards smaller denominators, then
1516 closer to zero.
1517 """
1518 min_value = try_convert(Fraction, min_value, "min_value")
1519 max_value = try_convert(Fraction, max_value, "max_value")
1520 # These assertions tell Mypy what happened in try_convert
1521 assert min_value is None or isinstance(min_value, Fraction)
1522 assert max_value is None or isinstance(max_value, Fraction)
1524 check_valid_interval(min_value, max_value, "min_value", "max_value")
1525 check_valid_integer(max_denominator, "max_denominator")
1527 if max_denominator is not None:
1528 if max_denominator < 1:
1529 raise InvalidArgument(f"{max_denominator=} must be >= 1")
1530 if min_value is not None and min_value.denominator > max_denominator:
1531 raise InvalidArgument(
1532 f"The {min_value=} has a denominator greater than the "
1533 f"{max_denominator=}"
1534 )
1535 if max_value is not None and max_value.denominator > max_denominator:
1536 raise InvalidArgument(
1537 f"The {max_value=} has a denominator greater than the "
1538 f"{max_denominator=}"
1539 )
1541 if min_value is not None and min_value == max_value:
1542 return just(min_value)
1544 def dm_func(denom):
1545 """Take denom, construct numerator strategy, and build fraction."""
1546 # Four cases of algebra to get integer bounds and scale factor.
1547 min_num, max_num = None, None
1548 if max_value is None and min_value is None:
1549 pass
1550 elif min_value is None:
1551 max_num = denom * max_value.numerator
1552 denom *= max_value.denominator
1553 elif max_value is None:
1554 min_num = denom * min_value.numerator
1555 denom *= min_value.denominator
1556 else:
1557 low = min_value.numerator * max_value.denominator
1558 high = max_value.numerator * min_value.denominator
1559 scale = min_value.denominator * max_value.denominator
1560 # After calculating our integer bounds and scale factor, we remove
1561 # the gcd to avoid drawing more bytes for the example than needed.
1562 # Note that `div` can be at most equal to `scale`.
1563 div = math.gcd(scale, math.gcd(low, high))
1564 min_num = denom * low // div
1565 max_num = denom * high // div
1566 denom *= scale // div
1568 return builds(
1569 Fraction, integers(min_value=min_num, max_value=max_num), just(denom)
1570 )
1572 if max_denominator is None:
1573 return integers(min_value=1).flatmap(dm_func)
1575 return (
1576 integers(1, max_denominator)
1577 .flatmap(dm_func)
1578 .map(lambda f: f.limit_denominator(max_denominator))
1579 )
1582def _as_finite_decimal(
1583 value: Union[Real, str, None], name: str, allow_infinity: Optional[bool]
1584) -> Optional[Decimal]:
1585 """Convert decimal bounds to decimals, carefully."""
1586 assert name in ("min_value", "max_value")
1587 if value is None:
1588 return None
1589 if not isinstance(value, Decimal):
1590 with localcontext(Context()): # ensure that default traps are enabled
1591 value = try_convert(Decimal, value, name)
1592 assert isinstance(value, Decimal)
1593 if value.is_finite():
1594 return value
1595 if value.is_infinite() and (value < 0 if "min" in name else value > 0):
1596 if allow_infinity or allow_infinity is None:
1597 return None
1598 raise InvalidArgument(f"{allow_infinity=}, but {name}={value!r}")
1599 # This could be infinity, quiet NaN, or signalling NaN
1600 raise InvalidArgument(f"Invalid {name}={value!r}")
1603@cacheable
1604@defines_strategy(force_reusable_values=True)
1605def decimals(
1606 min_value: Optional[Union[Real, str]] = None,
1607 max_value: Optional[Union[Real, str]] = None,
1608 *,
1609 allow_nan: Optional[bool] = None,
1610 allow_infinity: Optional[bool] = None,
1611 places: Optional[int] = None,
1612) -> SearchStrategy[Decimal]:
1613 """Generates instances of :class:`python:decimal.Decimal`, which may be:
1615 - A finite rational number, between ``min_value`` and ``max_value``.
1616 - Not a Number, if ``allow_nan`` is True. None means "allow NaN, unless
1617 ``min_value`` and ``max_value`` are not None".
1618 - Positive or negative infinity, if ``max_value`` and ``min_value``
1619 respectively are None, and ``allow_infinity`` is not False. None means
1620 "allow infinity, unless excluded by the min and max values".
1622 Note that where floats have one ``NaN`` value, Decimals have four: signed,
1623 and either *quiet* or *signalling*. See `the decimal module docs
1624 <https://docs.python.org/3/library/decimal.html#special-values>`_ for
1625 more information on special values.
1627 If ``places`` is not None, all finite values drawn from the strategy will
1628 have that number of digits after the decimal place.
1630 Examples from this strategy do not have a well defined shrink order but
1631 try to maximize human readability when shrinking.
1632 """
1633 # Convert min_value and max_value to Decimal values, and validate args
1634 check_valid_integer(places, "places")
1635 if places is not None and places < 0:
1636 raise InvalidArgument(f"{places=} may not be negative")
1637 min_value = _as_finite_decimal(min_value, "min_value", allow_infinity)
1638 max_value = _as_finite_decimal(max_value, "max_value", allow_infinity)
1639 check_valid_interval(min_value, max_value, "min_value", "max_value")
1640 if allow_infinity and (None not in (min_value, max_value)):
1641 raise InvalidArgument("Cannot allow infinity between finite bounds")
1642 # Set up a strategy for finite decimals. Note that both floating and
1643 # fixed-point decimals require careful handling to remain isolated from
1644 # any external precision context - in short, we always work out the
1645 # required precision for lossless operation and use context methods.
1646 if places is not None:
1647 # Fixed-point decimals are basically integers with a scale factor
1648 def ctx(val):
1649 """Return a context in which this value is lossless."""
1650 precision = ceil(math.log10(abs(val) or 1)) + places + 1
1651 return Context(prec=max([precision, 1]))
1653 def int_to_decimal(val):
1654 context = ctx(val)
1655 return context.quantize(context.multiply(val, factor), factor)
1657 factor = Decimal(10) ** -places
1658 min_num, max_num = None, None
1659 if min_value is not None:
1660 min_num = ceil(ctx(min_value).divide(min_value, factor))
1661 if max_value is not None:
1662 max_num = floor(ctx(max_value).divide(max_value, factor))
1663 if min_num is not None and max_num is not None and min_num > max_num:
1664 raise InvalidArgument(
1665 f"There are no decimals with {places} places between "
1666 f"{min_value=} and {max_value=}"
1667 )
1668 strat = integers(min_num, max_num).map(int_to_decimal)
1669 else:
1670 # Otherwise, they're like fractions featuring a power of ten
1671 def fraction_to_decimal(val):
1672 precision = (
1673 ceil(math.log10(abs(val.numerator) or 1) + math.log10(val.denominator))
1674 + 1
1675 )
1676 return Context(prec=precision or 1).divide(
1677 Decimal(val.numerator), val.denominator
1678 )
1680 strat = fractions(min_value, max_value).map(fraction_to_decimal)
1681 # Compose with sampled_from for infinities and NaNs as appropriate
1682 special: List[Decimal] = []
1683 if allow_nan or (allow_nan is None and (None in (min_value, max_value))):
1684 special.extend(map(Decimal, ("NaN", "-NaN", "sNaN", "-sNaN")))
1685 if allow_infinity or (allow_infinity is None and max_value is None):
1686 special.append(Decimal("Infinity"))
1687 if allow_infinity or (allow_infinity is None and min_value is None):
1688 special.append(Decimal("-Infinity"))
1689 return strat | (sampled_from(special) if special else nothing())
1692@defines_strategy(never_lazy=True)
1693def recursive(
1694 base: SearchStrategy[Ex],
1695 extend: Callable[[SearchStrategy[Any]], SearchStrategy[T]],
1696 *,
1697 max_leaves: int = 100,
1698) -> SearchStrategy[Union[T, Ex]]:
1699 """base: A strategy to start from.
1701 extend: A function which takes a strategy and returns a new strategy.
1703 max_leaves: The maximum number of elements to be drawn from base on a given
1704 run.
1706 This returns a strategy ``S`` such that ``S = extend(base | S)``. That is,
1707 values may be drawn from base, or from any strategy reachable by mixing
1708 applications of | and extend.
1710 An example may clarify: ``recursive(booleans(), lists)`` would return a
1711 strategy that may return arbitrarily nested and mixed lists of booleans.
1712 So e.g. ``False``, ``[True]``, ``[False, []]``, and ``[[[[True]]]]`` are
1713 all valid values to be drawn from that strategy.
1715 Examples from this strategy shrink by trying to reduce the amount of
1716 recursion and by shrinking according to the shrinking behaviour of base
1717 and the result of extend.
1719 """
1721 return RecursiveStrategy(base, extend, max_leaves)
1724class PermutationStrategy(SearchStrategy):
1725 def __init__(self, values):
1726 self.values = values
1728 def do_draw(self, data):
1729 # Reversed Fisher-Yates shuffle: swap each element with itself or with
1730 # a later element. This shrinks i==j for each element, i.e. to no
1731 # change. We don't consider the last element as it's always a no-op.
1732 result = list(self.values)
1733 for i in range(len(result) - 1):
1734 j = data.draw_integer(i, len(result) - 1)
1735 result[i], result[j] = result[j], result[i]
1736 return result
1739@defines_strategy()
1740def permutations(values: Sequence[T]) -> SearchStrategy[List[T]]:
1741 """Return a strategy which returns permutations of the ordered collection
1742 ``values``.
1744 Examples from this strategy shrink by trying to become closer to the
1745 original order of values.
1746 """
1747 values = check_sample(values, "permutations")
1748 if not values:
1749 return builds(list)
1751 return PermutationStrategy(values)
1754class CompositeStrategy(SearchStrategy):
1755 def __init__(self, definition, args, kwargs):
1756 self.definition = definition
1757 self.args = args
1758 self.kwargs = kwargs
1760 def do_draw(self, data):
1761 return self.definition(data.draw, *self.args, **self.kwargs)
1763 def calc_label(self):
1764 return calc_label_from_cls(self.definition)
1767class DrawFn(Protocol):
1768 """This type only exists so that you can write type hints for functions
1769 decorated with :func:`@composite <hypothesis.strategies.composite>`.
1771 .. code-block:: python
1773 @composite
1774 def list_and_index(draw: DrawFn) -> Tuple[int, str]:
1775 i = draw(integers()) # type inferred as 'int'
1776 s = draw(text()) # type inferred as 'str'
1777 return i, s
1779 """
1781 def __init__(self):
1782 raise TypeError("Protocols cannot be instantiated") # pragma: no cover
1784 # Protocol overrides our signature for __init__,
1785 # so we override it right back to make the docs look nice.
1786 __signature__: Signature = Signature(parameters=[])
1788 # We define this as a callback protocol because a simple typing.Callable is
1789 # insufficient to fully represent the interface, due to the optional `label`
1790 # parameter.
1791 def __call__(self, strategy: SearchStrategy[Ex], label: object = None) -> Ex:
1792 raise NotImplementedError
1795def _composite(f):
1796 # Wrapped below, using ParamSpec if available
1797 if isinstance(f, (classmethod, staticmethod)):
1798 special_method = type(f)
1799 f = f.__func__
1800 else:
1801 special_method = None
1803 sig = get_signature(f)
1804 params = tuple(sig.parameters.values())
1806 if not (params and "POSITIONAL" in params[0].kind.name):
1807 raise InvalidArgument(
1808 "Functions wrapped with composite must take at least one "
1809 "positional argument."
1810 )
1811 if params[0].default is not sig.empty:
1812 raise InvalidArgument("A default value for initial argument will never be used")
1813 if not (f is typing._overload_dummy or is_first_param_referenced_in_function(f)):
1814 note_deprecation(
1815 "There is no reason to use @st.composite on a function which "
1816 "does not call the provided draw() function internally.",
1817 since="2022-07-17",
1818 has_codemod=False,
1819 )
1820 if get_origin(sig.return_annotation) is SearchStrategy:
1821 ret_repr = repr(sig.return_annotation).replace("hypothesis.strategies.", "st.")
1822 warnings.warn(
1823 f"Return-type annotation is `{ret_repr}`, but the decorated "
1824 "function should return a value (not a strategy)",
1825 HypothesisWarning,
1826 stacklevel=3 if sys.version_info[:2] > (3, 9) else 5, # ugh
1827 )
1828 if params[0].kind.name != "VAR_POSITIONAL":
1829 params = params[1:]
1830 newsig = sig.replace(
1831 parameters=params,
1832 return_annotation=(
1833 SearchStrategy
1834 if sig.return_annotation is sig.empty
1835 else SearchStrategy[sig.return_annotation]
1836 ),
1837 )
1839 @defines_strategy()
1840 @define_function_signature(f.__name__, f.__doc__, newsig)
1841 def accept(*args, **kwargs):
1842 return CompositeStrategy(f, args, kwargs)
1844 accept.__module__ = f.__module__
1845 accept.__signature__ = newsig
1846 if special_method is not None:
1847 return special_method(accept)
1848 return accept
1851if typing.TYPE_CHECKING or ParamSpec is not None:
1852 P = ParamSpec("P")
1854 def composite(
1855 f: Callable[Concatenate[DrawFn, P], Ex]
1856 ) -> Callable[P, SearchStrategy[Ex]]:
1857 """Defines a strategy that is built out of potentially arbitrarily many
1858 other strategies.
1860 This is intended to be used as a decorator. See
1861 :ref:`the full documentation for more details <composite-strategies>`
1862 about how to use this function.
1864 Examples from this strategy shrink by shrinking the output of each draw
1865 call.
1866 """
1867 return _composite(f)
1869else: # pragma: no cover
1871 @cacheable
1872 def composite(f: Callable[..., Ex]) -> Callable[..., SearchStrategy[Ex]]:
1873 """Defines a strategy that is built out of potentially arbitrarily many
1874 other strategies.
1876 This is intended to be used as a decorator. See
1877 :ref:`the full documentation for more details <composite-strategies>`
1878 about how to use this function.
1880 Examples from this strategy shrink by shrinking the output of each draw
1881 call.
1882 """
1883 return _composite(f)
1886@defines_strategy(force_reusable_values=True)
1887@cacheable
1888def complex_numbers(
1889 *,
1890 min_magnitude: Real = 0,
1891 max_magnitude: Optional[Real] = None,
1892 allow_infinity: Optional[bool] = None,
1893 allow_nan: Optional[bool] = None,
1894 allow_subnormal: bool = True,
1895 width: Literal[32, 64, 128] = 128,
1896) -> SearchStrategy[complex]:
1897 """Returns a strategy that generates :class:`~python:complex`
1898 numbers.
1900 This strategy draws complex numbers with constrained magnitudes.
1901 The ``min_magnitude`` and ``max_magnitude`` parameters should be
1902 non-negative :class:`~python:numbers.Real` numbers; a value
1903 of ``None`` corresponds an infinite upper bound.
1905 If ``min_magnitude`` is nonzero or ``max_magnitude`` is finite, it
1906 is an error to enable ``allow_nan``. If ``max_magnitude`` is finite,
1907 it is an error to enable ``allow_infinity``.
1909 ``allow_infinity``, ``allow_nan``, and ``allow_subnormal`` are
1910 applied to each part of the complex number separately, as for
1911 :func:`~hypothesis.strategies.floats`.
1913 The magnitude constraints are respected up to a relative error
1914 of (around) floating-point epsilon, due to implementation via
1915 the system ``sqrt`` function.
1917 The ``width`` argument specifies the maximum number of bits of precision
1918 required to represent the entire generated complex number.
1919 Valid values are 32, 64 or 128, which correspond to the real and imaginary
1920 components each having width 16, 32 or 64, respectively.
1921 Passing ``width=64`` will still use the builtin 128-bit
1922 :class:`~python:complex` class, but always for values which can be
1923 exactly represented as two 32-bit floats.
1925 Examples from this strategy shrink by shrinking their real and
1926 imaginary parts, as :func:`~hypothesis.strategies.floats`.
1928 If you need to generate complex numbers with particular real and
1929 imaginary parts or relationships between parts, consider using
1930 :func:`builds(complex, ...) <hypothesis.strategies.builds>` or
1931 :func:`@composite <hypothesis.strategies.composite>` respectively.
1932 """
1933 check_valid_magnitude(min_magnitude, "min_magnitude")
1934 check_valid_magnitude(max_magnitude, "max_magnitude")
1935 check_valid_interval(min_magnitude, max_magnitude, "min_magnitude", "max_magnitude")
1936 if max_magnitude == math.inf:
1937 max_magnitude = None
1939 if allow_infinity is None:
1940 allow_infinity = bool(max_magnitude is None)
1941 elif allow_infinity and max_magnitude is not None:
1942 raise InvalidArgument(f"Cannot have {allow_infinity=} with {max_magnitude=}")
1943 if allow_nan is None:
1944 allow_nan = bool(min_magnitude == 0 and max_magnitude is None)
1945 elif allow_nan and not (min_magnitude == 0 and max_magnitude is None):
1946 raise InvalidArgument(
1947 f"Cannot have {allow_nan=}, {min_magnitude=}, {max_magnitude=}"
1948 )
1949 check_type(bool, allow_subnormal, "allow_subnormal")
1950 if width not in (32, 64, 128):
1951 raise InvalidArgument(
1952 f"{width=}, but must be 32, 64 or 128 (other complex dtypes "
1953 "such as complex192 or complex256 are not supported)"
1954 # For numpy, these types would be supported (but not by CPython):
1955 # https://numpy.org/doc/stable/reference/arrays.scalars.html#complex-floating-point-types
1956 )
1957 component_width = width // 2
1958 allow_kw = {
1959 "allow_nan": allow_nan,
1960 "allow_infinity": allow_infinity,
1961 # If we have a nonzero normal min_magnitude and draw a zero imaginary part,
1962 # then allow_subnormal=True would be an error with the min_value to the floats()
1963 # strategy for the real part. We therefore replace True with None.
1964 "allow_subnormal": None if allow_subnormal else allow_subnormal,
1965 "width": component_width,
1966 }
1968 if min_magnitude == 0 and max_magnitude is None:
1969 # In this simple but common case, there are no constraints on the
1970 # magnitude and therefore no relationship between the real and
1971 # imaginary parts.
1972 return builds(complex, floats(**allow_kw), floats(**allow_kw)) # type: ignore
1974 @composite
1975 def constrained_complex(draw):
1976 # We downcast drawn floats to the desired (component) width so we
1977 # guarantee the resulting complex values are representable. Note
1978 # truncating the mantissa bits with float_of() cannot increase the
1979 # magnitude of a float, so we are guaranteed to stay within the allowed
1980 # range. See https://github.com/HypothesisWorks/hypothesis/issues/3573
1982 # Draw the imaginary part, and determine the maximum real part given
1983 # this and the max_magnitude
1984 if max_magnitude is None:
1985 zi = draw(floats(**allow_kw))
1986 rmax = None
1987 else:
1988 zi = draw(
1989 floats(
1990 -float_of(max_magnitude, component_width),
1991 float_of(max_magnitude, component_width),
1992 **allow_kw,
1993 )
1994 )
1995 rmax = float_of(cathetus(max_magnitude, zi), component_width)
1996 # Draw the real part from the allowed range given the imaginary part
1997 if min_magnitude == 0 or math.fabs(zi) >= min_magnitude:
1998 zr = draw(floats(None if rmax is None else -rmax, rmax, **allow_kw))
1999 else:
2000 rmin = float_of(cathetus(min_magnitude, zi), component_width)
2001 zr = draw(floats(rmin, rmax, **allow_kw))
2002 # Order of conditions carefully tuned so that for a given pair of
2003 # magnitude arguments, we always either draw or do not draw the bool
2004 # (crucial for good shrinking behaviour) but only invert when needed.
2005 if min_magnitude > 0 and draw(booleans()) and math.fabs(zi) <= min_magnitude:
2006 zr = -zr
2007 return complex(zr, zi)
2009 return constrained_complex()
2012@defines_strategy(never_lazy=True)
2013def shared(
2014 base: SearchStrategy[Ex],
2015 *,
2016 key: Optional[Hashable] = None,
2017) -> SearchStrategy[Ex]:
2018 """Returns a strategy that draws a single shared value per run, drawn from
2019 base. Any two shared instances with the same key will share the same value,
2020 otherwise the identity of this strategy will be used. That is:
2022 >>> s = integers() # or any other strategy
2023 >>> x = shared(s)
2024 >>> y = shared(s)
2026 In the above x and y may draw different (or potentially the same) values.
2027 In the following they will always draw the same:
2029 >>> x = shared(s, key="hi")
2030 >>> y = shared(s, key="hi")
2032 Examples from this strategy shrink as per their base strategy.
2033 """
2034 return SharedStrategy(base, key)
2037@composite
2038def _maybe_nil_uuids(draw, uuid):
2039 # Equivalent to `random_uuids | just(...)`, with a stronger bias to the former.
2040 if draw(data()).conjecture_data.draw_boolean(1 / 64):
2041 return UUID("00000000-0000-0000-0000-000000000000")
2042 return uuid
2045@cacheable
2046@defines_strategy(force_reusable_values=True)
2047def uuids(
2048 *, version: Optional[Literal[1, 2, 3, 4, 5]] = None, allow_nil: bool = False
2049) -> SearchStrategy[UUID]:
2050 """Returns a strategy that generates :class:`UUIDs <uuid.UUID>`.
2052 If the optional version argument is given, value is passed through
2053 to :class:`~python:uuid.UUID` and only UUIDs of that version will
2054 be generated.
2056 If ``allow_nil`` is True, generate the nil UUID much more often.
2057 Otherwise, all returned values from this will be unique, so e.g. if you do
2058 ``lists(uuids())`` the resulting list will never contain duplicates.
2060 Examples from this strategy don't have any meaningful shrink order.
2061 """
2062 check_type(bool, allow_nil, "allow_nil")
2063 if version not in (None, 1, 2, 3, 4, 5):
2064 raise InvalidArgument(
2065 f"{version=}, but version must be in "
2066 "(None, 1, 2, 3, 4, 5) to pass to the uuid.UUID constructor."
2067 )
2068 random_uuids = shared(
2069 randoms(use_true_random=True), key="hypothesis.strategies.uuids.generator"
2070 ).map(lambda r: UUID(version=version, int=r.getrandbits(128)))
2072 if allow_nil:
2073 if version is not None:
2074 raise InvalidArgument("The nil UUID is not of any version")
2075 return random_uuids.flatmap(_maybe_nil_uuids)
2076 return random_uuids
2079class RunnerStrategy(SearchStrategy):
2080 def __init__(self, default):
2081 self.default = default
2083 def do_draw(self, data):
2084 runner = getattr(data, "hypothesis_runner", not_set)
2085 if runner is not_set:
2086 if self.default is not_set:
2087 raise InvalidArgument(
2088 "Cannot use runner() strategy with no "
2089 "associated runner or explicit default."
2090 )
2091 else:
2092 return self.default
2093 else:
2094 return runner
2097@defines_strategy(force_reusable_values=True)
2098def runner(*, default: Any = not_set) -> SearchStrategy[Any]:
2099 """A strategy for getting "the current test runner", whatever that may be.
2100 The exact meaning depends on the entry point, but it will usually be the
2101 associated 'self' value for it.
2103 If you are using this in a rule for stateful testing, this strategy
2104 will return the instance of the :class:`~hypothesis.stateful.RuleBasedStateMachine`
2105 that the rule is running for.
2107 If there is no current test runner and a default is provided, return
2108 that default. If no default is provided, raises InvalidArgument.
2110 Examples from this strategy do not shrink (because there is only one).
2111 """
2112 return RunnerStrategy(default)
2115class DataObject:
2116 """This type only exists so that you can write type hints for tests using
2117 the :func:`~hypothesis.strategies.data` strategy. Do not use it directly!
2118 """
2120 # Note that "only exists" here really means "is only exported to users",
2121 # but we want to treat it as "semi-stable", not document it as "public API".
2123 def __init__(self, data):
2124 self.count = 0
2125 self.conjecture_data = data
2127 __signature__ = Signature() # hide internals from Sphinx introspection
2129 def __repr__(self):
2130 return "data(...)"
2132 def draw(self, strategy: SearchStrategy[Ex], label: Any = None) -> Ex:
2133 check_strategy(strategy, "strategy")
2134 self.count += 1
2135 printer = RepresentationPrinter(context=current_build_context())
2136 desc = f"Draw {self.count}{'' if label is None else f' ({label})'}: "
2137 with deprecate_random_in_strategy("{}from {!r}", desc, strategy):
2138 result = self.conjecture_data.draw(strategy, observe_as=f"generate:{desc}")
2139 if TESTCASE_CALLBACKS:
2140 self.conjecture_data._observability_args[desc] = to_jsonable(result)
2142 printer.text(desc)
2143 printer.pretty(result)
2144 note(printer.getvalue())
2145 return result
2148class DataStrategy(SearchStrategy):
2149 supports_find = False
2151 def do_draw(self, data):
2152 if not hasattr(data, "hypothesis_shared_data_strategy"):
2153 data.hypothesis_shared_data_strategy = DataObject(data)
2154 return data.hypothesis_shared_data_strategy
2156 def __repr__(self):
2157 return "data()"
2159 def map(self, f):
2160 self.__not_a_first_class_strategy("map")
2162 def filter(self, f):
2163 self.__not_a_first_class_strategy("filter")
2165 def flatmap(self, f):
2166 self.__not_a_first_class_strategy("flatmap")
2168 def example(self):
2169 self.__not_a_first_class_strategy("example")
2171 def __not_a_first_class_strategy(self, name):
2172 raise InvalidArgument(
2173 f"Cannot call {name} on a DataStrategy. You should probably "
2174 "be using @composite for whatever it is you're trying to do."
2175 )
2178@cacheable
2179@defines_strategy(never_lazy=True)
2180def data() -> SearchStrategy[DataObject]:
2181 """This isn't really a normal strategy, but instead gives you an object
2182 which can be used to draw data interactively from other strategies.
2184 See :ref:`the rest of the documentation <interactive-draw>` for more
2185 complete information.
2187 Examples from this strategy do not shrink (because there is only one),
2188 but the result of calls to each ``data.draw()`` call shrink as they normally would.
2189 """
2190 return DataStrategy()
2193def register_type_strategy(
2194 custom_type: Type[Ex],
2195 strategy: Union[SearchStrategy[Ex], Callable[[Type[Ex]], SearchStrategy[Ex]]],
2196) -> None:
2197 """Add an entry to the global type-to-strategy lookup.
2199 This lookup is used in :func:`~hypothesis.strategies.builds` and
2200 :func:`@given <hypothesis.given>`.
2202 :func:`~hypothesis.strategies.builds` will be used automatically for
2203 classes with type annotations on ``__init__`` , so you only need to
2204 register a strategy if one or more arguments need to be more tightly
2205 defined than their type-based default, or if you want to supply a strategy
2206 for an argument with a default value.
2208 ``strategy`` may be a search strategy, or a function that takes a type and
2209 returns a strategy (useful for generic types). The function may return
2210 :data:`NotImplemented` to conditionally not provide a strategy for the type
2211 (the type will still be resolved by other methods, if possible, as if the
2212 function was not registered).
2214 Note that you may not register a parametrised generic type (such as
2215 ``MyCollection[int]``) directly, because the resolution logic does not
2216 handle this case correctly. Instead, you may register a *function* for
2217 ``MyCollection`` and `inspect the type parameters within that function
2218 <https://stackoverflow.com/q/48572831>`__.
2219 """
2220 # TODO: We would like to move this to the top level, but pending some major
2221 # refactoring it's hard to do without creating circular imports.
2222 from hypothesis.strategies._internal import types
2224 if not types.is_a_type(custom_type):
2225 raise InvalidArgument(f"{custom_type=} must be a type")
2226 if custom_type in types.NON_RUNTIME_TYPES:
2227 raise InvalidArgument(
2228 f"{custom_type=} is not allowed to be registered, "
2229 f"because there is no such thing as a runtime instance of {custom_type!r}"
2230 )
2231 if not (isinstance(strategy, SearchStrategy) or callable(strategy)):
2232 raise InvalidArgument(
2233 f"{strategy=} must be a SearchStrategy, or a function that takes "
2234 "a generic type and returns a specific SearchStrategy"
2235 )
2236 if isinstance(strategy, SearchStrategy):
2237 with warnings.catch_warnings():
2238 warnings.simplefilter("error", HypothesisSideeffectWarning)
2240 # Calling is_empty forces materialization of lazy strategies. If this is done at import
2241 # time, lazy strategies will warn about it; here, we force that warning to raise to
2242 # avoid the materialization. Ideally, we'd just check if the strategy is lazy, but the
2243 # lazy strategy may be wrapped underneath another strategy so that's complicated.
2244 try:
2245 if strategy.is_empty:
2246 raise InvalidArgument(f"{strategy=} must not be empty")
2247 except HypothesisSideeffectWarning: # pragma: no cover
2248 pass
2249 if types.has_type_arguments(custom_type):
2250 raise InvalidArgument(
2251 f"Cannot register generic type {custom_type!r}, because it has type "
2252 "arguments which would not be handled. Instead, register a function "
2253 f"for {get_origin(custom_type)!r} which can inspect specific type "
2254 "objects and return a strategy."
2255 )
2256 if (
2257 "pydantic.generics" in sys.modules
2258 and issubclass(custom_type, sys.modules["pydantic.generics"].GenericModel)
2259 and not re.search(r"[A-Za-z_]+\[.+\]", repr(custom_type))
2260 and callable(strategy)
2261 ): # pragma: no cover
2262 # See https://github.com/HypothesisWorks/hypothesis/issues/2940
2263 raise InvalidArgument(
2264 f"Cannot register a function for {custom_type!r}, because parametrized "
2265 "`pydantic.generics.GenericModel` subclasses aren't actually generic "
2266 "types at runtime. In this case, you should register a strategy "
2267 "directly for each parametrized form that you anticipate using."
2268 )
2270 types._global_type_lookup[custom_type] = strategy
2271 from_type.__clear_cache() # type: ignore
2274@cacheable
2275@defines_strategy(never_lazy=True)
2276def deferred(definition: Callable[[], SearchStrategy[Ex]]) -> SearchStrategy[Ex]:
2277 """A deferred strategy allows you to write a strategy that references other
2278 strategies that have not yet been defined. This allows for the easy
2279 definition of recursive and mutually recursive strategies.
2281 The definition argument should be a zero-argument function that returns a
2282 strategy. It will be evaluated the first time the strategy is used to
2283 produce an example.
2285 Example usage:
2287 >>> import hypothesis.strategies as st
2288 >>> x = st.deferred(lambda: st.booleans() | st.tuples(x, x))
2289 >>> x.example()
2290 (((False, (True, True)), (False, True)), (True, True))
2291 >>> x.example()
2292 True
2294 Mutual recursion also works fine:
2296 >>> a = st.deferred(lambda: st.booleans() | b)
2297 >>> b = st.deferred(lambda: st.tuples(a, a))
2298 >>> a.example()
2299 True
2300 >>> b.example()
2301 (False, (False, ((False, True), False)))
2303 Examples from this strategy shrink as they normally would from the strategy
2304 returned by the definition.
2305 """
2306 return DeferredStrategy(definition)
2309def domains():
2310 import hypothesis.provisional
2312 return hypothesis.provisional.domains()
2315@defines_strategy(force_reusable_values=True)
2316def emails(
2317 *, domains: SearchStrategy[str] = LazyStrategy(domains, (), {})
2318) -> SearchStrategy[str]:
2319 """A strategy for generating email addresses as unicode strings. The
2320 address format is specified in :rfc:`5322#section-3.4.1`. Values shrink
2321 towards shorter local-parts and host domains.
2323 If ``domains`` is given then it must be a strategy that generates domain
2324 names for the emails, defaulting to :func:`~hypothesis.provisional.domains`.
2326 This strategy is useful for generating "user data" for tests, as
2327 mishandling of email addresses is a common source of bugs.
2328 """
2329 local_chars = string.ascii_letters + string.digits + "!#$%&'*+-/=^_`{|}~"
2330 local_part = text(local_chars, min_size=1, max_size=64)
2331 # TODO: include dot-atoms, quoted strings, escaped chars, etc in local part
2332 return builds("{}@{}".format, local_part, domains).filter(
2333 lambda addr: len(addr) <= 254
2334 )
2337def _functions(*, like, returns, pure):
2338 # Wrapped up to use ParamSpec below
2339 check_type(bool, pure, "pure")
2340 if not callable(like):
2341 raise InvalidArgument(
2342 "The first argument to functions() must be a callable to imitate, "
2343 f"but got non-callable like={nicerepr(like)!r}"
2344 )
2345 if returns in (None, ...):
2346 # Passing `None` has never been *documented* as working, but it still
2347 # did from May 2020 to Jan 2022 so we'll avoid breaking it without cause.
2348 hints = get_type_hints(like)
2349 returns = from_type(hints.get("return", type(None)))
2350 check_strategy(returns, "returns")
2351 return FunctionStrategy(like, returns, pure)
2354if typing.TYPE_CHECKING or ParamSpec is not None:
2356 @overload
2357 def functions(
2358 *, pure: bool = ...
2359 ) -> SearchStrategy[Callable[[], None]]: # pragma: no cover
2360 ...
2362 @overload
2363 def functions(
2364 *,
2365 like: Callable[P, T],
2366 pure: bool = ...,
2367 ) -> SearchStrategy[Callable[P, T]]: # pragma: no cover
2368 ...
2370 @overload
2371 def functions(
2372 *,
2373 returns: SearchStrategy[T],
2374 pure: bool = ...,
2375 ) -> SearchStrategy[Callable[[], T]]: # pragma: no cover
2376 ...
2378 @overload
2379 def functions(
2380 *,
2381 like: Callable[P, Any],
2382 returns: SearchStrategy[T],
2383 pure: bool = ...,
2384 ) -> SearchStrategy[Callable[P, T]]: # pragma: no cover
2385 ...
2387 @defines_strategy()
2388 def functions(*, like=lambda: None, returns=..., pure=False):
2389 # We shouldn't need overloads here, but mypy disallows default args for
2390 # generics: https://github.com/python/mypy/issues/3737
2391 """functions(*, like=lambda: None, returns=..., pure=False)
2393 A strategy for functions, which can be used in callbacks.
2395 The generated functions will mimic the interface of ``like``, which must
2396 be a callable (including a class, method, or function). The return value
2397 for the function is drawn from the ``returns`` argument, which must be a
2398 strategy. If ``returns`` is not passed, we attempt to infer a strategy
2399 from the return-type annotation if present, falling back to :func:`~none`.
2401 If ``pure=True``, all arguments passed to the generated function must be
2402 hashable, and if passed identical arguments the original return value will
2403 be returned again - *not* regenerated, so beware mutable values.
2405 If ``pure=False``, generated functions do not validate their arguments, and
2406 may return a different value if called again with the same arguments.
2408 Generated functions can only be called within the scope of the ``@given``
2409 which created them. This strategy does not support ``.example()``.
2410 """
2411 return _functions(like=like, returns=returns, pure=pure)
2413else: # pragma: no cover
2415 @defines_strategy()
2416 def functions(
2417 *,
2418 like: Callable[..., Any] = lambda: None,
2419 returns: Union[SearchStrategy[Any], EllipsisType] = ...,
2420 pure: bool = False,
2421 ) -> SearchStrategy[Callable[..., Any]]:
2422 """functions(*, like=lambda: None, returns=..., pure=False)
2424 A strategy for functions, which can be used in callbacks.
2426 The generated functions will mimic the interface of ``like``, which must
2427 be a callable (including a class, method, or function). The return value
2428 for the function is drawn from the ``returns`` argument, which must be a
2429 strategy. If ``returns`` is not passed, we attempt to infer a strategy
2430 from the return-type annotation if present, falling back to :func:`~none`.
2432 If ``pure=True``, all arguments passed to the generated function must be
2433 hashable, and if passed identical arguments the original return value will
2434 be returned again - *not* regenerated, so beware mutable values.
2436 If ``pure=False``, generated functions do not validate their arguments, and
2437 may return a different value if called again with the same arguments.
2439 Generated functions can only be called within the scope of the ``@given``
2440 which created them. This strategy does not support ``.example()``.
2441 """
2442 return _functions(like=like, returns=returns, pure=pure)
2445@composite
2446def slices(draw: Any, size: int) -> slice:
2447 """Generates slices that will select indices up to the supplied size
2449 Generated slices will have start and stop indices that range from -size to size - 1
2450 and will step in the appropriate direction. Slices should only produce an empty selection
2451 if the start and end are the same.
2453 Examples from this strategy shrink toward 0 and smaller values
2454 """
2455 check_valid_size(size, "size")
2456 if size == 0:
2457 step = draw(none() | integers().filter(bool))
2458 return slice(None, None, step)
2459 # For slices start is inclusive and stop is exclusive
2460 start = draw(integers(0, size - 1) | none())
2461 stop = draw(integers(0, size) | none())
2463 # Limit step size to be reasonable
2464 if start is None and stop is None:
2465 max_step = size
2466 elif start is None:
2467 max_step = stop
2468 elif stop is None:
2469 max_step = start
2470 else:
2471 max_step = abs(start - stop)
2473 step = draw(integers(1, max_step or 1))
2475 if (draw(booleans()) and start == stop) or (stop or 0) < (start or 0):
2476 step *= -1
2478 if draw(booleans()) and start is not None:
2479 start -= size
2480 if draw(booleans()) and stop is not None:
2481 stop -= size
2482 if (not draw(booleans())) and step == 1:
2483 step = None
2485 return slice(start, stop, step)