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