Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# Strategies Reference

Strategies are the way Hypothesis describes the values for `@given` to generate. For instance, passing the strategy `st.lists(st.integers(), min_size=1)` to `@given` tells Hypothesis to generate lists of integers with at least one element.

This reference page lists all of Hypothesis’ first-party functions which return a strategy. There are also many provided by third-party libraries. Note that we often say “strategy” when we mean “function returning a strategy”; it’s usually clear from context which one we mean.

Strategies can be passed to other strategies as arguments, combined using combinator strategies, or modified using `.filter()`, `.map()`, or `.flatmap()`.

## Primitives

hypothesis.strategies.none()

  Return a strategy which only generates None.

  Examples from this strategy do not shrink (because there is only one).

hypothesis.strategies.nothing()

  This strategy never successfully draws a value and will always reject on an attempt to draw.

  Examples from this strategy do not shrink (because there are none).

hypothesis.strategies.just(value)

  Return a strategy which only generates `value`.

  Note: `value` is not copied. Be wary of using mutable values.

  If `value` is the result of a callable, you can use `builds(callable)` instead of `just(callable())` to get a fresh value each time.

  Examples from this strategy do not shrink (because there is only one).

hypothesis.strategies.booleans()

  Returns a strategy which generates instances of `python:bool`.

  Examples from this strategy will shrink towards `False` (i.e. shrinking will replace `True` with `False` where possible).

## Numeric

See also

See also the separate sections for Numpy strategies, Pandas strategies, and Array API strategies.

hypothesis.strategies.integers(min_value=None, max_value=None)

  Returns a strategy which generates integers.

  If min_value is not None then all values will be >= min_value. If max_value is not None then all values will be <= max_value

  Examples from this strategy will shrink towards zero, and negative values will also shrink towards positive (i.e. -n may be replaced by +n).

hypothesis.strategies.floats(

  min_value=None,
  max_value=None,
  *,
  allow_nan=None,
  allow_infinity=None,
  allow_subnormal=None,
  width=64,
  exclude_min=False,
  exclude_max=False,

)

  Returns a strategy which generates floats.

  - If min_value is not None, all values will be `>= min_value` (or `> min_value` if `exclude_min`).

  - If max_value is not None, all values will be `<= max_value` (or `< max_value` if `exclude_max`).

  - If min_value or max_value is not None, it is an error to enable allow_nan.

  - If both min_value and max_value are not None, it is an error to enable allow_infinity.

  - If inferred values range does not include subnormal values, it is an error to enable allow_subnormal.

  Where not explicitly ruled out by the bounds, subnormals, infinities, and NaNs are possible values generated by this strategy.

  The width argument specifies the maximum number of bits of precision required to represent the generated float. Valid values are 16, 32, or 64. Passing `width=32` will still use the builtin 64-bit `python:float` class, but always for values which can be exactly represented as a 32-bit float.

  The exclude_min and exclude_max argument can be used to generate numbers from open or half-open intervals, by excluding the respective endpoints. Excluding either signed zero will also exclude the other. Attempting to exclude an endpoint which is None will raise an error; use `allow_infinity=False` to generate finite floats. You can however use e.g. `min_value=-math.inf, exclude_min=True` to exclude only one infinite endpoint.

  Examples from this strategy have a complicated and hard to explain shrinking behaviour, but it tries to improve “human readability”. Finite numbers will be preferred to infinity and infinity will be preferred to NaN.

hypothesis.strategies.complex_numbers(

  *,
  min_magnitude=0,
  max_magnitude=None,
  allow_infinity=None,
  allow_nan=None,
  allow_subnormal=True,
  width=128,

)

  Returns a strategy that generates `python:complex` numbers.

  This strategy draws complex numbers with constrained magnitudes. The `min_magnitude` and `max_magnitude` parameters should be non-negative `Real` numbers; a value of `None` corresponds an infinite upper bound.

  If `min_magnitude` is nonzero or `max_magnitude` is finite, it is an error to enable `allow_nan`. If `max_magnitude` is finite, it is an error to enable `allow_infinity`.

  `allow_infinity`, `allow_nan`, and `allow_subnormal` are applied to each part of the complex number separately, as for `floats()`.

  The magnitude constraints are respected up to a relative error of (around) floating-point epsilon, due to implementation via the system `sqrt` function.

  The `width` argument specifies the maximum number of bits of precision required to represent the entire generated complex number. Valid values are 32, 64 or 128, which correspond to the real and imaginary components each having width 16, 32 or 64, respectively. Passing `width=64` will still use the builtin 128-bit `python:complex` class, but always for values which can be exactly represented as two 32-bit floats.

  Examples from this strategy shrink by shrinking their real and imaginary parts, as `floats()`.

  If you need to generate complex numbers with particular real and imaginary parts or relationships between parts, consider using `builds(complex, ...)` or `@composite` respectively.

hypothesis.strategies.decimals(

  min_value=None,
  max_value=None,
  *,
  allow_nan=None,
  allow_infinity=None,
  places=None,

)

  Generates instances of `python:decimal.Decimal`, which may be:

  - A finite rational number, between `min_value` and `max_value`.

  - Not a Number, if `allow_nan` is True. None means “allow NaN, unless `min_value` and `max_value` are not None”.

  - Positive or negative infinity, if `max_value` and `min_value` respectively are None, and `allow_infinity` is not False. None means “allow infinity, unless excluded by the min and max values”.

  Note that where floats have one `NaN` value, Decimals have four: signed, and either quiet or signalling. See the decimal module docs for more information on special values.

  If `places` is not None, all finite values drawn from the strategy will have that number of digits after the decimal place.

  Examples from this strategy do not have a well defined shrink order but try to maximize human readability when shrinking.

hypothesis.strategies.fractions(

  min_value=None,
  max_value=None,
  *,
  max_denominator=None,

)

  Returns a strategy which generates Fractions.

  If `min_value` is not None then all generated values are no less than `min_value`. If `max_value` is not None then all generated values are no greater than `max_value`. `min_value` and `max_value` may be anything accepted by the `Fraction` constructor.

  If `max_denominator` is not None then the denominator of any generated values is no greater than `max_denominator`. Note that `max_denominator` must be None or a positive integer.

  Examples from this strategy shrink towards smaller denominators, then closer to zero.

## Strings

See also

The `uuids()` and `ip_addresses()` strategies generate instances of `UUID` and `IPAddress` respectively. You can generate corresponding string values by using `.map()`, such as `st.uuids().map(str)`.

hypothesis.strategies.text(

  alphabet=characters(codec='utf-8'),
  *,
  min_size=0,
  max_size=None,

)

  Generates strings with characters drawn from `alphabet`, which should be a collection of length one strings or a strategy generating such strings.

  The default alphabet strategy can generate the full unicode range but excludes surrogate characters because they are invalid in the UTF-8 encoding. You can use `characters()` without arguments to find surrogate-related bugs such as bpo-34454.

  `min_size` and `max_size` have the usual interpretations. Note that Python measures string length by counting codepoints: U+00C5 `Å` is a single character, while U+0041 U+030A `Å` is two - the `A`, and a combining ring above.

  Examples from this strategy shrink towards shorter strings, and with the characters in the text shrinking as per the alphabet strategy. This strategy does not `normalize()` examples, so generated strings may be in any or none of the ‘normal forms’.

hypothesis.strategies.characters(

  *,
  codec=None,
  min_codepoint=None,
  max_codepoint=None,
  categories=None,
  exclude_categories=None,
  exclude_characters=None,
  include_characters=None,

)

  Generates characters, length-one `python:str`ings, following specified filtering rules.

  - When no filtering rules are specified, any character can be produced.

  - If `min_codepoint` or `max_codepoint` is specified, then only characters having a codepoint in that range will be produced.

  - If `categories` is specified, then only characters from those Unicode categories will be produced. This is a further restriction, characters must also satisfy `min_codepoint` and `max_codepoint`.

  - If `exclude_categories` is specified, then any character from those categories will not be produced. You must not pass both `categories` and `exclude_categories`; these arguments are alternative ways to specify exactly the same thing.

  - If `include_characters` is specified, then any additional characters in that list will also be produced.

  - If `exclude_characters` is specified, then any characters in that list will be not be produced. Any overlap between `include_characters` and `exclude_characters` will raise an exception.

  - If `codec` is specified, only characters in the specified codec encodings will be produced.

  The `_codepoint` arguments must be integers between zero and `python:sys.maxunicode`. The `_characters` arguments must be collections of length-one unicode strings, such as a unicode string.

  The `_categories` arguments must be used to specify either the one-letter Unicode major category or the two-letter Unicode general category. For example, `('Nd', 'Lu')` signifies “Number, decimal digit” and “Letter, uppercase”. A single letter (‘major category’) can be given to match all corresponding categories, for example `'P'` for characters in any punctuation category.

  We allow codecs from the `codecs` module and their aliases, platform specific and user-registered codecs if they are available, and python-specific text encodings (but not text or binary transforms). `include_characters` which cannot be encoded using this codec will raise an exception. If non-encodable codepoints or categories are explicitly allowed, the `codec` argument will exclude them without raising an exception.

  Examples from this strategy shrink towards the codepoint for `'0'`, or the first allowable codepoint after it if `'0'` is excluded.

hypothesis.strategies.from_regex(regex, *, fullmatch=False, alphabet=None)

  Generates strings that contain a match for the given regex (i.e. ones for which `python:re.search()` will return a non-None result).

  `regex` may be a pattern or `compiled regex`. Both byte-strings and unicode strings are supported, and will generate examples of the same type.

  You can use regex flags such as `python:re.IGNORECASE` or `python:re.DOTALL` to control generation. Flags can be passed either in compiled regex or inside the pattern with a `(?iLmsux)` group.

  Some regular expressions are only partly supported - the underlying strategy checks local matching and relies on filtering to resolve context-dependent expressions. Using too many of these constructs may cause health-check errors as too many examples are filtered out. This mainly includes (positive or negative) lookahead and lookbehind groups.

  If you want the generated string to match the whole regex you should use boundary markers. So e.g. `r"\A.\Z"` will return a single character string, while `"."` will return any string, and `r"\A.$"` will return a single character optionally followed by a `"\n"`. Alternatively, passing `fullmatch=True` will ensure that the whole string is a match, as if you had used the `\A` and `\Z` markers.

  The `alphabet=` argument constrains the characters in the generated string, as for `text()`, and is only supported for unicode strings.

  Examples from this strategy shrink towards shorter strings and lower character values, with exact behaviour that may depend on the pattern.

hypothesis.strategies.binary(*, min_size=0, max_size=None)

  Generates `python:bytes`.

  The generated `python:bytes` will have a length of at least `min_size` and at most `max_size`. If `max_size` is None there is no upper limit.

  Examples from this strategy shrink towards smaller strings and lower byte values.

hypothesis.strategies.emails(*, domains=domains())

  A strategy for generating email addresses as unicode strings. The address format is specified in RFC 5322 Section 3.4.1. Values shrink towards shorter local-parts and host domains.

  If `domains` is given then it must be a strategy that generates domain names for the emails, defaulting to `domains()`.

  This strategy is useful for generating “user data” for tests, as mishandling of email addresses is a common source of bugs.

hypothesis.provisional.domains(*, max_length=255, max_element_length=63)

  Generate RFC 1035 compliant fully qualified domain names.

Warning

The `domains()` strategy is provisional. Its interface may be changed in a minor release, without being subject to our deprecation policy. That said, we expect it to be relatively stable.

hypothesis.provisional.urls()

  A strategy for RFC 3986, generating http/https URLs.

  The generated URLs could, at least in theory, be passed to an HTTP client and fetched.

Warning

The `urls()` strategy is provisional. Its interface may be changed in a minor release, without being subject to our deprecation policy. That said, we expect it to be relatively stable.

## Collections

hypothesis.strategies.lists(

  elements,
  *,
  min_size=0,
  max_size=None,
  unique_by=None,
  unique=False,

)

  Returns a list containing values drawn from elements with length in the interval [min_size, max_size] (no bounds in that direction if these are None). If max_size is 0, only the empty list will be drawn.

  If `unique` is True (or something that evaluates to True), we compare direct object equality, as if unique_by was `lambda x: x`. This comparison only works for hashable types.

  If `unique_by` is not None it must be a callable or tuple of callables returning a hashable type when given a value drawn from elements. The resulting list will satisfy the condition that for `i` != `j`, `unique_by(result[i])` != `unique_by(result[j])`.

  If `unique_by` is a tuple of callables the uniqueness will be respective to each callable.

  For example, the following will produce two columns of integers with both columns being unique respectively.

      >>> twoints = st.tuples(st.integers(), st.integers())
      >>> st.lists(twoints, unique_by=(lambda x: x[0], lambda x: x[1]))

  Examples from this strategy shrink by trying to remove elements from the list, and by shrinking each individual element of the list.

hypothesis.strategies.tuples(*args)

  Return a strategy which generates a tuple of the same length as args by generating the value at index i from args[i].

  e.g. tuples(integers(), integers()) would generate a tuple of length two with both values an integer.

  Examples from this strategy shrink by shrinking their component parts.

hypothesis.strategies.sets(elements, *, min_size=0, max_size=None)

  This has the same behaviour as lists, but returns sets instead.

  Note that Hypothesis cannot tell if values are drawn from elements are hashable until running the test, so you can define a strategy for sets of an unhashable type but it will fail at test time.

  Examples from this strategy shrink by trying to remove elements from the set, and by shrinking each individual element of the set.

hypothesis.strategies.frozensets(elements, *, min_size=0, max_size=None)

  This is identical to the sets function but instead returns frozensets.

hypothesis.strategies.dictionaries(

  keys,
  values,
  *,
  dict_class=<class 'dict'>,
  min_size=0,
  max_size=None,

)

  Generates dictionaries of type `dict_class` with keys drawn from the `keys` argument and values drawn from the `values` argument.

  The size parameters have the same interpretation as for `lists()`.

  Examples from this strategy shrink by trying to remove keys from the generated dictionary, and by shrinking each generated key and value.

hypothesis.strategies.fixed_dictionaries(mapping, *, optional=None)

  Generates a dictionary of the same type as mapping with a fixed set of keys mapping to strategies. `mapping` must be a dict subclass.

  Generated values have all keys present in mapping, in iteration order, with the corresponding values drawn from mapping[key].

  If `optional` is passed, the generated value may or may not contain each key from `optional` and a value drawn from the corresponding strategy. Generated values may contain optional keys in an arbitrary order.

  Examples from this strategy shrink by shrinking each individual value in the generated dictionary, and omitting optional key-value pairs.

hypothesis.strategies.iterables(

  elements,
  *,
  min_size=0,
  max_size=None,
  unique_by=None,
  unique=False,

)

  This has the same behaviour as lists, but returns iterables instead.

  Some iterables cannot be indexed (e.g. sets) and some do not have a fixed length (e.g. generators). This strategy produces iterators, which cannot be indexed and do not have a fixed length. This ensures that you do not accidentally depend on sequence behaviour.

## Datetime

hypothesis.strategies.dates(

  min_value=datetime.date.min,
  max_value=datetime.date.max,

)

  A strategy for dates between `min_value` and `max_value`.

  Examples from this strategy shrink towards January 1st 2000.

hypothesis.strategies.times(

  min_value=datetime.time.min,
  max_value=datetime.time.max,
  *,
  timezones=none(),

)

  A strategy for times between `min_value` and `max_value`.

  The `timezones` argument is handled as for `datetimes()`.

  Examples from this strategy shrink towards midnight, with the timezone component shrinking as for the strategy that provided it.

hypothesis.strategies.datetimes(

  min_value=datetime.datetime.min,
  max_value=datetime.datetime.max,
  *,
  timezones=none(),
  allow_imaginary=True,

)

  A strategy for generating datetimes, which may be timezone-aware.

  This strategy works by drawing a naive datetime between `min_value` and `max_value`, which must both be naive (have no timezone).

  `timezones` must be a strategy that generates either `None`, for naive datetimes, or `tzinfo` objects for ‘aware’ datetimes. You can construct your own, though we recommend using one of these built-in strategies:

  - with the standard library: `hypothesis.strategies.timezones()`;

  - with dateutil: `hypothesis.extra.dateutil.timezones()`; or

  - with pytz: `hypothesis.extra.pytz.timezones()`.

  You may pass `allow_imaginary=False` to filter out “imaginary” datetimes which did not (or will not) occur due to daylight savings, leap seconds, timezone and calendar adjustments, etc. Imaginary datetimes are allowed by default, because malformed timestamps are a common source of bugs.

  Examples from this strategy shrink towards midnight on January 1st 2000, local time.

hypothesis.strategies.timezones(*, no_cache=False)

  A strategy for `python:zoneinfo.ZoneInfo` objects.

  If `no_cache=True`, the generated instances are constructed using `ZoneInfo.no_cache` instead of the usual constructor. This may change the semantics of your datetimes in surprising ways, so only use it if you know that you need to!

  Note

  The tzdata package is required on Windows. `pip install hypothesis[zoneinfo]` installs it, if and only if needed.

hypothesis.strategies.timezone_keys(*, allow_prefix=True)

  A strategy for IANA timezone names.

  As well as timezone names like `"UTC"`, `"Australia/Sydney"`, or `"America/New_York"`, this strategy can generate:

  - Aliases such as `"Antarctica/McMurdo"`, which links to `"Pacific/Auckland"`.

  - Deprecated names such as `"Antarctica/South_Pole"`, which also links to `"Pacific/Auckland"`. Note that most but not all deprecated timezone names are also aliases.

  - Timezone names with the `"posix/"` or `"right/"` prefixes, unless `allow_prefix=False`.

  These strings are provided separately from Tzinfo objects - such as ZoneInfo instances from the timezones() strategy - to facilitate testing of timezone logic without needing workarounds to access non-canonical names.

  Note

  The tzdata package is required on Windows. `pip install hypothesis[zoneinfo]` installs it, if and only if needed.

  On Windows, you may need to access IANA timezone data via the tzdata package. For non-IANA timezones, such as Windows-native names or GNU TZ strings, we recommend using `sampled_from()` with the dateutil package, e.g. `dateutil:dateutil.tz.tzwin.list()`.

hypothesis.strategies.timedeltas(

  min_value=datetime.timedelta.min,
  max_value=datetime.timedelta.max,

)

  A strategy for timedeltas between `min_value` and `max_value`.

  Examples from this strategy shrink towards zero.

## Recursive

hypothesis.strategies.recursive(base, extend, *, max_leaves=100)

  base: A strategy to start from.

  extend: A function which takes a strategy and returns a new strategy.

  max_leaves: The maximum number of elements to be drawn from base on a given run.

  This returns a strategy `S` such that `S = extend(base | S)`. That is, values may be drawn from base, or from any strategy reachable by mixing applications of | and extend.

  An example may clarify: `recursive(booleans(), lists)` would return a strategy that may return arbitrarily nested and mixed lists of booleans. So e.g. `False`, `[True]`, `[False, []]`, and `[[[[True]]]]` are all valid values to be drawn from that strategy.

  Examples from this strategy shrink by trying to reduce the amount of recursion and by shrinking according to the shrinking behaviour of base and the result of extend.

hypothesis.strategies.deferred(definition)

  A deferred strategy allows you to write a strategy that references other strategies that have not yet been defined. This allows for the easy definition of recursive and mutually recursive strategies.

  The definition argument should be a zero-argument function that returns a strategy. It will be evaluated the first time the strategy is used to produce an example.

  Example usage:

      >>> import hypothesis.strategies as st
      >>> x = st.deferred(lambda: st.booleans() | st.tuples(x, x))
      >>> x.example()
      (((False, (True, True)), (False, True)), (True, True))
      >>> x.example()
      True

  Mutual recursion also works fine:

      >>> a = st.deferred(lambda: st.booleans() | b)
      >>> b = st.deferred(lambda: st.tuples(a, a))
      >>> a.example()
      True
      >>> b.example()
      (False, (False, ((False, True), False)))

  Examples from this strategy shrink as they normally would from the strategy returned by the definition.

## Random

hypothesis.strategies.randoms(*, note_method_calls=False, use_true_random=False)

  Generates instances of `random.Random`. The generated Random instances are of a special HypothesisRandom subclass.

  - If `note_method_calls` is set to `True`, Hypothesis will print the randomly drawn values in any falsifying test case. This can be helpful for debugging the behaviour of randomized algorithms.

  - If `use_true_random` is set to `True` then values will be drawn from their usual distribution, otherwise they will actually be Hypothesis generated values (and will be shrunk accordingly for any failing test case). Setting `use_true_random=False` will tend to expose bugs that would occur with very low probability when it is set to True, and this flag should only be set to True when your code relies on the distribution of values for correctness.

  For managing global state, see the `random_module()` strategy and `register_random()` function.

hypothesis.strategies.random_module()

  Hypothesis always seeds global PRNGs before running a test, and restores the previous state afterwards.

  If having a fixed seed would unacceptably weaken your tests, and you cannot use a `random.Random` instance provided by `randoms()`, this strategy calls `python:random.seed()` with an arbitrary integer and passes you an opaque object whose repr displays the seed value for debugging. If `numpy.random` is available, that state is also managed, as is anything managed by `hypothesis.register_random()`.

  Examples from these strategy shrink to seeds closer to zero.

hypothesis.register_random(r)

  Register (a weakref to) the given Random-like instance for management by Hypothesis.

  You can pass instances of structural subtypes of `random.Random` (i.e., objects with seed, getstate, and setstate methods) to `register_random(r)` to have their states seeded and restored in the same way as the global PRNGs from the `random` and `numpy.random` modules.

  All global PRNGs, from e.g. simulation or scheduling frameworks, should be registered to prevent flaky tests. Hypothesis will ensure that the PRNG state is consistent for all test runs, always seeding them to zero and restoring the previous state after the test, or, reproducibly varied if you choose to use the `random_module()` strategy.

  `register_random` only makes weakrefs to `r`, thus `r` will only be managed by Hypothesis as long as it has active references elsewhere at runtime. The pattern `register_random(MyRandom())` will raise a `ReferenceError` to help protect users from this issue. This check does not occur for the PyPy interpreter. See the following example for an illustration of this issue

      def my_BROKEN_hook():
          r = MyRandomLike()

          # `r` will be garbage collected after the hook resolved
          # and Hypothesis will 'forget' that it was registered
          register_random(r)  # Hypothesis will emit a warning

      rng = MyRandomLike()

      def my_WORKING_hook():
          register_random(rng)

## Combinators

hypothesis.strategies.one_of(*args)

  Return a strategy which generates values from any of the argument strategies.

  This may be called with one iterable argument instead of multiple strategy arguments, in which case `one_of(x)` and `one_of(*x)` are equivalent.

  Examples from this strategy will generally shrink to ones that come from strategies earlier in the list, then shrink according to behaviour of the strategy that produced them. In order to get good shrinking behaviour, try to put simpler strategies first. e.g. `one_of(none(), text())` is better than `one_of(text(), none())`.

  This is especially important when using recursive strategies. e.g. `x = st.deferred(lambda: st.none() | st.tuples(x, x))` will shrink well, but `x = st.deferred(lambda: st.tuples(x, x) | st.none())` will shrink very badly indeed.

hypothesis.strategies.builds(target, /, *args, **kwargs)

  Generates values by drawing from `args` and `kwargs` and passing them to the callable (provided as the first positional argument) in the appropriate argument position.

  e.g. `builds(target, integers(), flag=booleans())` would draw an integer `i` and a boolean `b` and call `target(i, flag=b)`.

  If the callable has type annotations, they will be used to infer a strategy for required arguments that were not passed to builds. You can also tell builds to infer a strategy for an optional argument by passing `...` (`python:Ellipsis`) as a keyword argument to builds, instead of a strategy for that argument to the callable.

  If the callable is a class defined with attrs, missing required arguments will be inferred from the attribute on a best-effort basis, e.g. by checking attrs standard validators. Dataclasses are handled natively by the inference from type hints.

  Examples from this strategy shrink by shrinking the argument values to the callable.

hypothesis.strategies.composite(f)

  Defines a strategy that is built out of potentially arbitrarily many other strategies.

  @composite provides a callable `draw` as the first parameter to the decorated function, which can be used to dynamically draw a value from any strategy. For example:

      from hypothesis import strategies as st, given

      @st.composite
      def values(draw):
          n1 = draw(st.integers())
          n2 = draw(st.integers(min_value=n1))
          return (n1, n2)

      @given(values())
      def f(value):
          (n1, n2) = value
          assert n1 <= n2

  @composite cannot mix test code and generation code. If you need that, use `data()`.

  If `@composite` is used to decorate a method or classmethod, the `draw` argument must come before `self` or `cls`. While we therefore recommend writing strategies as standalone functions and using `register_type_strategy()` to associate them with a class, methods are supported and the `@composite` decorator may be applied either before or after `@classmethod` or `@staticmethod`. See issue #2578 and pull request #2634 for more details.

  Examples from this strategy shrink by shrinking the output of each draw call.

hypothesis.strategies.data()

  Provides an object `data` with a `data.draw` function which acts like the `draw` callable provided by `@composite`, in that it can be used to dynamically draw values from strategies. `data()` is more powerful than `@composite`, because it allows you to mix generation and test code.

  Here’s an example of dynamically generating values using `data()`:

      from hypothesis import strategies as st, given

      @given(st.data())
      def test_values(data):
          n1 = data.draw(st.integers())
          n2 = data.draw(st.integers(min_value=n1))
          assert n1 + 1 <= n2

  If the test fails, each draw will be printed with the falsifying example. e.g. the above is wrong (it has a boundary condition error), so will print:

      Falsifying example: test_values(data=data(...))
      Draw 1: 0
      Draw 2: 0

  Optionally, you can provide a label to identify values generated by each call to `data.draw()`. These labels can be used to identify values in the output of a falsifying example.

  For instance:

      @given(st.data())
      def test_draw_sequentially(data):
          x = data.draw(st.integers(), label="First number")
          y = data.draw(st.integers(min_value=x), label="Second number")
          assert x < y

  will produce:

      Falsifying example: test_draw_sequentially(data=data(...))
      Draw 1 (First number): 0
      Draw 2 (Second number): 0

  Examples from this strategy shrink by shrinking the output of each draw call.

## Typing

hypothesis.strategies.from_type(thing)

  Looks up the appropriate search strategy for the given type.

  `from_type` is used internally to fill in missing arguments to `builds()` and can be used interactively to explore what strategies are available or to debug type resolution.

  You can use `register_type_strategy()` to handle your custom types, or to globally redefine certain strategies - for example excluding NaN from floats, or use timezone-aware instead of naive time and datetime strategies.

  The resolution logic may be changed in a future version, but currently tries these five options:

  1. If `thing` is in the default lookup mapping or user-registered lookup, return the corresponding strategy. The default lookup covers all types with Hypothesis strategies, including extras where possible.

  2. If `thing` is from the `python:typing` module, return the corresponding strategy (special logic).

  3. If `thing` has one or more subtypes in the merged lookup, return the union of the strategies for those types that are not subtypes of other elements in the lookup.

  4. Finally, if `thing` has type annotations for all required arguments, and is not an abstract class, it is resolved via `builds()`.

  5. Because `abstract types` cannot be instantiated, we treat abstract types as the union of their concrete subclasses. Note that this lookup works via inheritance but not via `register`, so you may still need to use `register_type_strategy()`.

  There is a valuable recipe for leveraging `from_type()` to generate “everything except” values from a specified type. I.e.

      def everything_except(excluded_types):
          return (
              from_type(type)
              .flatmap(from_type)
              .filter(lambda x: not isinstance(x, excluded_types))
          )

  For example, `everything_except(int)` returns a strategy that can generate anything that `from_type()` can ever generate, except for instances of `python:int`, and excluding instances of types added via `register_type_strategy()`.

  This is useful when writing tests which check that invalid input is rejected in a certain way.

hypothesis.strategies.register_type_strategy(custom_type, strategy)

  Add an entry to the global type-to-strategy lookup.

  This lookup is used in `builds()` and `@given`.

  `builds()` will be used automatically for classes with type annotations on `__init__` , so you only need to register a strategy if one or more arguments need to be more tightly defined than their type-based default, or if you want to supply a strategy for an argument with a default value.

  `strategy` may be a search strategy, or a function that takes a type and returns a strategy (useful for generic types). The function may return `NotImplemented` to conditionally not provide a strategy for the type (the type will still be resolved by other methods, if possible, as if the function was not registered).

  Note that you may not register a parametrised generic type (such as `MyCollection[int]`) directly, because the resolution logic does not handle this case correctly. Instead, you may register a function for `MyCollection` and inspect the type parameters within that function.

## Hypothesis

hypothesis.strategies.runner(*, default=not_set)

  A strategy for getting “the current test runner”, whatever that may be. The exact meaning depends on the entry point, but it will usually be the associated ‘self’ value for it.

  If you are using this in a rule for stateful testing, this strategy will return the instance of the `RuleBasedStateMachine` that the rule is running for.

  If there is no current test runner and a default is provided, return that default. If no default is provided, raises InvalidArgument.

  Examples from this strategy do not shrink (because there is only one).

hypothesis.strategies.shared(base, *, key=None)

  Returns a strategy that draws a single shared value per run, drawn from base. Any two shared instances with the same key will share the same value, otherwise the identity of this strategy will be used. That is:

      >>> s = integers()  # or any other strategy
      >>> x = shared(s)
      >>> y = shared(s)

  In the above x and y may draw different (or potentially the same) values. In the following they will always draw the same:

      >>> x = shared(s, key="hi")
      >>> y = shared(s, key="hi")

  Examples from this strategy shrink as per their base strategy.

## Misc

hypothesis.strategies.functions(*, like=lambda : ..., returns=..., pure=False)

  A strategy for functions, which can be used in callbacks.

  The generated functions will mimic the interface of `like`, which must be a callable (including a class, method, or function). The return value for the function is drawn from the `returns` argument, which must be a strategy. If `returns` is not passed, we attempt to infer a strategy from the return-type annotation if present, falling back to `none()`.

  If `pure=True`, all arguments passed to the generated function must be hashable, and if passed identical arguments the original return value will be returned again - not regenerated, so beware mutable values.

  If `pure=False`, generated functions do not validate their arguments, and may return a different value if called again with the same arguments.

  Generated functions can only be called within the scope of the `@given` which created them. This strategy does not support `.example()`.

hypothesis.strategies.slices(size)

  Generates slices that will select indices up to the supplied size

  Generated slices will have start and stop indices that range from -size to size - 1 and will step in the appropriate direction. Slices should only produce an empty selection if the start and end are the same.

  Examples from this strategy shrink toward 0 and smaller values

hypothesis.strategies.uuids(*, version=None, allow_nil=False)

  Returns a strategy that generates `UUIDs`.

  If the optional version argument is given, value is passed through to `UUID` and only UUIDs of that version will be generated.

  If `allow_nil` is True, generate the nil UUID much more often. Otherwise, all returned values from this will be unique, so e.g. if you do `lists(uuids())` the resulting list will never contain duplicates.

  Examples from this strategy don’t have any meaningful shrink order.

hypothesis.strategies.ip_addresses(*, v=None, network=None)

  Generate IP addresses - `v=4` for `IPv4Address`es, `v=6` for `IPv6Address`es, or leave unspecified to allow both versions.

  `network` may be an `IPv4Network` or `IPv6Network`, or a string representing a network such as `"127.0.0.0/24"` or `"2001:db8::/32"`. As well as generating addresses within a particular routable network, this can be used to generate addresses from a reserved range listed in the IANA registries.

  If you pass both `v` and `network`, they must be for the same version.

hypothesis.strategies.sampled_from(elements)

  Returns a strategy which generates any value present in `elements`.

  Note that as with `just()`, values will not be copied and thus you should be careful of using mutable data.

  `sampled_from` supports ordered collections, as well as `Enum` objects. `Flag` objects may also generate any combination of their members.

  Examples from this strategy shrink by replacing them with values earlier in the list. So e.g. `sampled_from([10, 1])` will shrink by trying to replace 1 values with 10, and `sampled_from([1, 10])` will shrink by trying to replace 10 values with 1.

  It is an error to sample from an empty sequence, because returning `nothing()` makes it too easy to silently drop parts of compound strategies. If you need that behaviour, use `sampled_from(seq) if seq else nothing()`.

hypothesis.strategies.permutations(values)

  Return a strategy which returns permutations of the ordered collection `values`.

  Examples from this strategy shrink by trying to become closer to the original order of values.

## Related

class hypothesis.strategies.DataObject

  This type only exists so that you can write type hints for tests using the `data()` strategy. Do not use it directly!

class hypothesis.strategies.DrawFn

  This type only exists so that you can write type hints for functions decorated with `@composite`.

      @composite
      def list_and_index(draw: DrawFn) -> tuple[int, str]:
          i = draw(integers())  # type inferred as 'int'
          s = draw(text())  # type inferred as 'str'
          return i, s

class hypothesis.strategies.SearchStrategy

  A SearchStrategy is an object that knows how to explore data of a given type.

  Except where noted otherwise, methods on this class are not part of the public API and their behaviour may change significantly between minor version releases. They will generally be stable between patch releases.

  filter(condition)

    Returns a new strategy that generates values from this strategy which satisfy the provided condition. Note that if the condition is too hard to satisfy this might result in your tests failing with Unsatisfiable.

    This method is part of the public API.

  map(pack)

    Returns a new strategy that generates values by generating a value from this strategy and then calling pack() on the result, giving that.

    This method is part of the public API.

  flatmap(expand)

    Returns a new strategy that generates values by generating a value from this strategy, say x, then generating a value from strategy(expand(x))

    This method is part of the public API.

## NumPy

Hypothesis offers a number of strategies for NumPy testing, available in the `hypothesis[numpy]` extra. It lives in the `hypothesis.extra.numpy` package.

The centerpiece is the `arrays()` strategy, which generates arrays with any dtype, shape, and contents you can specify or give a strategy for. To make this as useful as possible, strategies are provided to generate array shapes and generate all kinds of fixed-size or compound dtypes.

hypothesis.extra.numpy.array_dtypes(

  subtype_strategy=scalar_dtypes(),
  *,
  min_size=1,
  max_size=5,
  allow_subarrays=False,

)

  Return a strategy for generating array (compound) dtypes, with members drawn from the given subtype strategy.

hypothesis.extra.numpy.array_shapes(

  *,
  min_dims=1,
  max_dims=None,
  min_side=1,
  max_side=None,

)

  Return a strategy for array shapes (tuples of int >= 1).

  - `min_dims` is the smallest length that the generated shape can possess.

  - `max_dims` is the largest length that the generated shape can possess, defaulting to `min_dims + 2`.

  - `min_side` is the smallest size that a dimension can possess.

  - `max_side` is the largest size that a dimension can possess, defaulting to `min_side + 5`.

hypothesis.extra.numpy.arrays(

  dtype,
  shape,
  *,
  elements=None,
  fill=None,
  unique=False,

)

  Returns a strategy for generating `numpy:numpy.ndarray`s.

  - `dtype` may be any valid input to `dtype` (this includes `dtype` objects), or a strategy that generates such values.

  - `shape` may be an integer >= 0, a tuple of such integers, or a strategy that generates such values.

  - `elements` is a strategy for generating values to put in the array. If it is None a suitable value will be inferred based on the dtype, which may give any legal value (including eg NaN for floats). If a mapping, it will be passed as `**kwargs` to `from_dtype()`

  - `fill` is a strategy that may be used to generate a single background value for the array. If None, a suitable default will be inferred based on the other arguments. If set to `nothing()` then filling behaviour will be disabled entirely and every element will be generated independently.

  - `unique` specifies if the elements of the array should all be distinct from one another. Note that in this case multiple NaN values may still be allowed. If fill is also set, the only valid values for it to return are NaN values (anything for which `numpy:numpy.isnan` returns True. So e.g. for complex numbers `nan+1j` is also a valid fill). Note that if `unique` is set to `True` the generated values must be hashable.

  Arrays of specified `dtype` and `shape` are generated for example like this:

      >>> import numpy as np
      >>> arrays(np.int8, (2, 3)).example()
      array([[-8,  6,  3],
             [-6,  4,  6]], dtype=int8)
      >>> arrays(np.float, 3, elements=st.floats(0, 1)).example()
      array([ 0.88974794,  0.77387938,  0.1977879 ])

  Array values are generated in two parts:

  1. Some subset of the coordinates of the array are populated with a value drawn from the elements strategy (or its inferred form).

  2. If any coordinates were not assigned in the previous step, a single value is drawn from the `fill` strategy and is assigned to all remaining places.

  You can set `fill=nothing()` to disable this behaviour and draw a value for every element.

  If `fill=None`, then it will attempt to infer the correct behaviour automatically. If `unique` is `True`, no filling will occur by default. Otherwise, if it looks safe to reuse the values of elements across multiple coordinates (this will be the case for any inferred strategy, and for most of the builtins, but is not the case for mutable values or strategies built with flatmap, map, composite, etc) then it will use the elements strategy as the fill, else it will default to having no fill.

  Having a fill helps Hypothesis craft high quality examples, but its main importance is when the array generated is large: Hypothesis is primarily designed around testing small examples. If you have arrays with hundreds or more elements, having a fill value is essential if you want your tests to run in reasonable time.

hypothesis.extra.numpy.basic_indices(

  shape,
  *,
  min_dims=0,
  max_dims=None,
  allow_newaxis=False,
  allow_ellipsis=True,

)

  Return a strategy for basic indexes of arrays with the specified shape, which may include dimensions of size zero.

  It generates tuples containing some mix of integers, `python:slice` objects, `...` (an `Ellipsis`), and `None`. When a length-one tuple would be generated, this strategy may instead return the element which will index the first axis, e.g. `5` instead of `(5,)`.

  - `shape` is the shape of the array that will be indexed, as a tuple of positive integers. This must be at least two-dimensional for a tuple to be a valid index; for one-dimensional arrays use `slices()` instead.

  - `min_dims` is the minimum dimensionality of the resulting array from use of the generated index. When `min_dims == 0`, scalars and zero-dimensional arrays are both allowed.

  - `max_dims` is the the maximum dimensionality of the resulting array, defaulting to `len(shape) if not allow_newaxis else max(len(shape), min_dims) + 2`.

  - `allow_newaxis` specifies whether `None` is allowed in the index.

  - `allow_ellipsis` specifies whether `...` is allowed in the index.

hypothesis.extra.numpy.boolean_dtypes()

  Return a strategy for boolean dtypes.

hypothesis.extra.numpy.broadcastable_shapes(

  shape,
  *,
  min_dims=0,
  max_dims=None,
  min_side=1,
  max_side=None,

)

  Return a strategy for shapes that are broadcast-compatible with the provided shape.

  Examples from this strategy shrink towards a shape with length `min_dims`. The size of an aligned dimension shrinks towards size `1`. The size of an unaligned dimension shrink towards `min_side`.

  - `shape` is a tuple of integers.

  - `min_dims` is the smallest length that the generated shape can possess.

  - `max_dims` is the largest length that the generated shape can possess, defaulting to `max(len(shape), min_dims) + 2`.

  - `min_side` is the smallest size that an unaligned dimension can possess.

  - `max_side` is the largest size that an unaligned dimension can possess, defaulting to 2 plus the size of the largest aligned dimension.

  The following are some examples drawn from this strategy.

      >>> [broadcastable_shapes(shape=(2, 3)).example() for i in range(5)]
      [(1, 3), (), (2, 3), (2, 1), (4, 1, 3), (3, )]

hypothesis.extra.numpy.byte_string_dtypes(*, endianness='?', min_len=1, max_len=16)

  Return a strategy for generating bytestring dtypes, of various lengths and byteorder.

  While Hypothesis’ string strategies can generate empty strings, string dtypes with length 0 indicate that size is still to be determined, so the minimum length for string dtypes is 1.

hypothesis.extra.numpy.complex_number_dtypes(*, endianness='?', sizes=(64, 128))

  Return a strategy for complex-number dtypes.

  sizes is the total size in bits of a complex number, which consists of two floats. Complex halves (a 16-bit real part) are not supported by numpy and will not be generated by this strategy.

hypothesis.extra.numpy.datetime64_dtypes(

  *,
  max_period='Y',
  min_period='ns',
  endianness='?',

)

  Return a strategy for datetime64 dtypes, with various precisions from year to attosecond.

hypothesis.extra.numpy.floating_dtypes(*, endianness='?', sizes=(16, 32, 64))

  Return a strategy for floating-point dtypes.

  sizes is the size in bits of floating-point number. Some machines support 96- or 128-bit floats, but these are not generated by default.

  Larger floats (96 and 128 bit real parts) are not supported on all platforms and therefore disabled by default. To generate these dtypes, include these values in the sizes argument.

hypothesis.extra.numpy.from_dtype(

  dtype,
  *,
  alphabet=None,
  min_size=0,
  max_size=None,
  min_value=None,
  max_value=None,
  allow_nan=None,
  allow_infinity=None,
  allow_subnormal=None,
  exclude_min=None,
  exclude_max=None,
  min_magnitude=0,
  max_magnitude=None,

)

  Creates a strategy which can generate any value of the given dtype.

  Compatible parameters are passed to the inferred strategy function while inapplicable ones are ignored. This allows you, for example, to customise the min and max values, control the length or contents of strings, or exclude non-finite numbers. This is particularly useful when kwargs are passed through from `arrays()` which allow a variety of numeric dtypes, as it seamlessly handles the `width` or representable bounds for you.

hypothesis.extra.numpy.integer_array_indices(

  shape,
  *,
  result_shape=array_shapes(),
  dtype=dtype('int64'),

)

  Return a search strategy for tuples of integer-arrays that, when used to index into an array of shape `shape`, given an array whose shape was drawn from `result_shape`.

  Examples from this strategy shrink towards the tuple of index-arrays:

      len(shape) * (np.zeros(drawn_result_shape, dtype), )

  - `shape` a tuple of integers that indicates the shape of the array, whose indices are being generated.

  - `result_shape` a strategy for generating tuples of integers, which describe the shape of the resulting index arrays. The default is `array_shapes()`. The shape drawn from this strategy determines the shape of the array that will be produced when the corresponding example from `integer_array_indices` is used as an index.

  - `dtype` the integer data type of the generated index-arrays. Negative integer indices can be generated if a signed integer type is specified.

  Recall that an array can be indexed using a tuple of integer-arrays to access its members in an arbitrary order, producing an array with an arbitrary shape. For example:

      >>> from numpy import array
      >>> x = array([-0, -1, -2, -3, -4])
      >>> ind = (array([[4, 0], [0, 1]]),)  # a tuple containing a 2D integer-array
      >>> x[ind]  # the resulting array is commensurate with the indexing array(s)
      array([[-4,  0],
             [0, -1]])

  Note that this strategy does not accommodate all variations of so-called ‘advanced indexing’, as prescribed by NumPy’s nomenclature. Combinations of basic and advanced indexes are too complex to usefully define in a standard strategy; we leave application-specific strategies to the user. Advanced-boolean indexing can be defined as `arrays(shape=..., dtype=bool)`, and is similarly left to the user.

hypothesis.extra.numpy.integer_dtypes(*, endianness='?', sizes=(8, 16, 32, 64))

  Return a strategy for signed integer dtypes.

  endianness and sizes are treated as for `unsigned_integer_dtypes()`.

hypothesis.extra.numpy.mutually_broadcastable_shapes(

  *,
  num_shapes=not_set,
  signature=not_set,
  base_shape=(),
  min_dims=0,
  max_dims=None,
  min_side=1,
  max_side=None,

)

  > Return a strategy for a specified number of shapes N that are

  mutually-broadcastable with one another and with the provided base shape.

  - `num_shapes` is the number of mutually broadcast-compatible shapes to generate.

  - `base_shape` is the shape against which all generated shapes can broadcast. The default shape is empty, which corresponds to a scalar and thus does not constrain broadcasting at all.

  - `min_dims` is the smallest length that the generated shape can possess.

  - `max_dims` is the largest length that the generated shape can possess, defaulting to `max(len(shape), min_dims) + 2`.

  - `min_side` is the smallest size that an unaligned dimension can possess.

  - `max_side` is the largest size that an unaligned dimension can possess, defaulting to 2 plus the size of the largest aligned dimension.

  The strategy will generate a `python:typing.NamedTuple` containing:

  - `input_shapes` as a tuple of the N generated shapes.

  - `result_shape` as the resulting shape produced by broadcasting the N shapes with the base shape.

  The following are some examples drawn from this strategy.

      >>> # Draw three shapes where each shape is broadcast-compatible with (2, 3)
      ... strat = mutually_broadcastable_shapes(num_shapes=3, base_shape=(2, 3))
      >>> for _ in range(5):
      ...     print(strat.example())
      BroadcastableShapes(input_shapes=((4, 1, 3), (4, 2, 3), ()), result_shape=(4, 2, 3))
      BroadcastableShapes(input_shapes=((3,), (1, 3), (2, 3)), result_shape=(2, 3))
      BroadcastableShapes(input_shapes=((), (), ()), result_shape=())
      BroadcastableShapes(input_shapes=((3,), (), (3,)), result_shape=(3,))
      BroadcastableShapes(input_shapes=((1, 2, 3), (3,), ()), result_shape=(1, 2, 3))

      **Use with Generalised Universal Function signatures**

      A :doc:`universal function <numpy:reference/ufuncs>` (or ufunc for short) is a function
      that operates on ndarrays in an element-by-element fashion, supporting array
      broadcasting, type casting, and several other standard features.
      A :doc:`generalised ufunc <numpy:reference/c-api/generalized-ufuncs>` operates on
      sub-arrays rather than elements, based on the "signature" of the function.
      Compare e.g. :obj:`numpy.add() <numpy:numpy.add>` (ufunc) to
      :obj:`numpy.matmul() <numpy:numpy.matmul>` (gufunc).

      To generate shapes for a gufunc, you can pass the ``signature`` argument instead of
      ``num_shapes``.  This must be a gufunc signature string; which you can write by
      hand or access as e.g. ``np.matmul.signature`` on generalised ufuncs.

      In this case, the ``side`` arguments are applied to the 'core dimensions' as well,
      ignoring any frozen dimensions.  ``base_shape``  and the ``dims`` arguments are
      applied to the 'loop dimensions', and if necessary, the dimensionality of each
      shape is silently capped to respect the 32-dimension limit.

      The generated ``result_shape`` is the real result shape of applying the gufunc
      to arrays of the generated ``input_shapes``, even where this is different to
      broadcasting the loop dimensions.

      gufunc-compatible shapes shrink their loop dimensions as above, towards omitting
      optional core dimensions, and smaller-size core dimensions.

      .. code-block:: pycon

          >>> # np.matmul.signature == "(m?,n),(n,p?)->(m?,p?)"
          >>> for _ in range(3):
          ...     mutually_broadcastable_shapes(signature=np.matmul.signature).example()
          BroadcastableShapes(input_shapes=((2,), (2,)), result_shape=())
          BroadcastableShapes(input_shapes=((3, 4, 2), (1, 2)), result_shape=(3, 4))
          BroadcastableShapes(input_shapes=((4, 2), (1, 2, 3)), result_shape=(4, 3))

hypothesis.extra.numpy.nested_dtypes(

  subtype_strategy=scalar_dtypes(),
  *,
  max_leaves=10,
  max_itemsize=None,

)

  Return the most-general dtype strategy.

  Elements drawn from this strategy may be simple (from the subtype_strategy), or several such values drawn from `array_dtypes()` with `allow_subarrays=True`. Subdtypes in an array dtype may be nested to any depth, subject to the max_leaves argument.

hypothesis.extra.numpy.scalar_dtypes()

  Return a strategy that can return any non-flexible scalar dtype.

hypothesis.extra.numpy.timedelta64_dtypes(

  *,
  max_period='Y',
  min_period='ns',
  endianness='?',

)

  Return a strategy for timedelta64 dtypes, with various precisions from year to attosecond.

hypothesis.extra.numpy.unicode_string_dtypes(

  *,
  endianness='?',
  min_len=1,
  max_len=16,

)

  Return a strategy for generating unicode string dtypes, of various lengths and byteorder.

  While Hypothesis’ string strategies can generate empty strings, string dtypes with length 0 indicate that size is still to be determined, so the minimum length for string dtypes is 1.

hypothesis.extra.numpy.unsigned_integer_dtypes(

  *,
  endianness='?',
  sizes=(8, 16, 32, 64),

)

  Return a strategy for unsigned integer dtypes.

  endianness may be `<` for little-endian, `>` for big-endian, `=` for native byte order, or `?` to allow either byte order. This argument only applies to dtypes of more than one byte.

  sizes must be a collection of integer sizes in bits. The default (8, 16, 32, 64) covers the full range of sizes.

hypothesis.extra.numpy.valid_tuple_axes(ndim, *, min_size=0, max_size=None)

  > Return a strategy for generating permissible tuple-values for the `axis` argument for a numpy sequential function (e.g. `numpy:numpy.sum()`), given an array of the specified dimensionality.

  > All tuples will have a length >= `min_size` and <= `max_size`. The default

  value for `max_size` is `ndim`.

  Examples from this strategy shrink towards an empty tuple, which render most sequential functions as no-ops.

  The following are some examples drawn from this strategy.

      >>> [valid_tuple_axes(3).example() for i in range(4)]
      [(-3, 1), (0, 1, -1), (0, 2), (0, -2, 2)]

  `valid_tuple_axes` can be joined with other strategies to generate any type of valid axis object, i.e. integers, tuples, and `None`:

      any_axis_strategy = none() | integers(-ndim, ndim - 1) | valid_tuple_axes(ndim)

## pandas

Hypothesis provides strategies for several of the core pandas data types: `pandas.Index`, `pandas.Series` and `pandas.DataFrame`.

The general approach taken by the pandas module is that there are multiple strategies for generating indexes, and all of the other strategies take the number of entries they contain from their index strategy (with sensible defaults). So e.g. a Series is specified by specifying its `numpy.dtype` (and/or a strategy for generating elements for it).

class hypothesis.extra.pandas.column(

  name=None,
  elements=None,
  dtype=None,
  fill=None,
  unique=False,

)

  Data object for describing a column in a DataFrame.

  Arguments:

  - name: the column name, or None to default to the column position. Must be hashable, but can otherwise be any value supported as a pandas column name.

  - elements: the strategy for generating values in this column, or None to infer it from the dtype.

  - dtype: the dtype of the column, or None to infer it from the element strategy. At least one of dtype or elements must be provided.

  - fill: A default value for elements of the column. See `arrays()` for a full explanation.

  - unique: If all values in this column should be distinct.

hypothesis.extra.pandas.columns(

  names_or_number,
  *,
  dtype=None,
  elements=None,
  fill=None,
  unique=False,

)

  A convenience function for producing a list of `column` objects of the same general shape.

  The names_or_number argument is either a sequence of values, the elements of which will be used as the name for individual column objects, or a number, in which case that many unnamed columns will be created. All other arguments are passed through verbatim to create the columns.

hypothesis.extra.pandas.data_frames(columns=None, *, rows=None, index=None)

  Provides a strategy for producing a `pandas.DataFrame`.

  Arguments:

  - columns: An iterable of `column` objects describing the shape of the generated DataFrame.

  - rows: A strategy for generating a row object. Should generate either dicts mapping column names to values or a sequence mapping column position to the value in that position (note that unlike the `pandas.DataFrame` constructor, single values are not allowed here. Passing e.g. an integer is an error, even if there is only one column).

    At least one of rows and columns must be provided. If both are provided then the generated rows will be validated against the columns and an error will be raised if they don’t match.

    Caveats on using rows:

    - In general you should prefer using columns to rows, and only use rows if the columns interface is insufficiently flexible to describe what you need - you will get better performance and example quality that way.

    - If you provide rows and not columns, then the shape and dtype of the resulting DataFrame may vary. e.g. if you have a mix of int and float in the values for one column in your row entries, the column will sometimes have an integral dtype and sometimes a float.

  - index: If not None, a strategy for generating indexes for the resulting DataFrame. This can generate either `pandas.Index` objects or any sequence of values (which will be passed to the Index constructor).

    You will probably find it most convenient to use the `indexes()` or `range_indexes()` function to produce values for this argument.

  Usage:

  The expected usage pattern is that you use `column` and `columns()` to specify a fixed shape of the DataFrame you want as follows. For example the following gives a two column data frame:

      >>> from hypothesis.extra.pandas import column, data_frames
      >>> data_frames([
      ... column('A', dtype=int), column('B', dtype=float)]).example()
                  A              B
      0  2021915903  1.793898e+232
      1  1146643993            inf
      2 -2096165693   1.000000e+07

  If you want the values in different columns to interact in some way you can use the rows argument. For example the following gives a two column DataFrame where the value in the first column is always at most the value in the second:

      >>> from hypothesis.extra.pandas import column, data_frames
      >>> import hypothesis.strategies as st
      >>> data_frames(
      ...     rows=st.tuples(st.floats(allow_nan=False),
      ...                    st.floats(allow_nan=False)).map(sorted)
      ... ).example()
                     0             1
      0  -3.402823e+38  9.007199e+15
      1 -1.562796e-298  5.000000e-01

  You can also combine the two:

      >>> from hypothesis.extra.pandas import columns, data_frames
      >>> import hypothesis.strategies as st
      >>> data_frames(
      ...     columns=columns(["lo", "hi"], dtype=float),
      ...     rows=st.tuples(st.floats(allow_nan=False),
      ...                    st.floats(allow_nan=False)).map(sorted)
      ... ).example()
               lo            hi
      0   9.314723e-49  4.353037e+45
      1  -9.999900e-01  1.000000e+07
      2 -2.152861e+134 -1.069317e-73

  (Note that the column dtype must still be specified and will not be inferred from the rows. This restriction may be lifted in future).

  Combining rows and columns has the following behaviour:

  - The column names and dtypes will be used.

  - If the column is required to be unique, this will be enforced.

  - Any values missing from the generated rows will be provided using the column’s fill.

  - Any values in the row not present in the column specification (if dicts are passed, if there are keys with no corresponding column name, if sequences are passed if there are too many items) will result in InvalidArgument being raised.

hypothesis.extra.pandas.indexes(

  *,
  elements=None,
  dtype=None,
  min_size=0,
  max_size=None,
  unique=True,
  name=none(),

)

  Provides a strategy for producing a `pandas.Index`.

  Arguments:

  - elements is a strategy which will be used to generate the individual values of the index. If None, it will be inferred from the dtype. Note: even if the elements strategy produces tuples, the generated value will not be a MultiIndex, but instead be a normal index whose elements are tuples.

  - dtype is the dtype of the resulting index. If None, it will be inferred from the elements strategy. At least one of dtype or elements must be provided.

  - min_size is the minimum number of elements in the index.

  - max_size is the maximum number of elements in the index. If None then it will default to a suitable small size. If you want larger indexes you should pass a max_size explicitly.

  - unique specifies whether all of the elements in the resulting index should be distinct.

  - name is a strategy for strings or `None`, which will be passed to the `pandas.Index` constructor.

hypothesis.extra.pandas.range_indexes(min_size=0, max_size=None, name=none())

  Provides a strategy which generates an `Index` whose values are 0, 1, …, n for some n.

  Arguments:

  - min_size is the smallest number of elements the index can have.

  - max_size is the largest number of elements the index can have. If None it will default to some suitable value based on min_size.

  - name is the name of the index. If st.none(), the index will have no name.

hypothesis.extra.pandas.series(

  *,
  elements=None,
  dtype=None,
  index=None,
  fill=None,
  unique=False,
  name=none(),

)

  Provides a strategy for producing a `pandas.Series`.

  Arguments:

  - elements: a strategy that will be used to generate the individual values in the series. If None, we will attempt to infer a suitable default from the dtype.

  - dtype: the dtype of the resulting series and may be any value that can be passed to `numpy.dtype`. If None, will use pandas’s standard behaviour to infer it from the type of the elements values. Note that if the type of values that comes out of your elements strategy varies, then so will the resulting dtype of the series.

  - index: If not None, a strategy for generating indexes for the resulting Series. This can generate either `pandas.Index` objects or any sequence of values (which will be passed to the Index constructor).

    You will probably find it most convenient to use the `indexes()` or `range_indexes()` function to produce values for this argument.

  - name: is a strategy for strings or `None`, which will be passed to the `pandas.Series` constructor.

  Usage:

      >>> series(dtype=int).example()
      0   -2001747478
      1    1153062837

### Supported versions

There is quite a lot of variation between pandas versions. We only commit to supporting the latest version of pandas, but older minor versions are supported on a “best effort” basis. Hypothesis is currently tested against and confirmed working with every Pandas minor version from 1.1 through to 2.2.

Releases that are not the latest patch release of their minor version are not tested or officially supported, but will probably also work unless you hit a pandas bug.

## Array API

Note

Several array libraries have more library-specific strategies, including Xarray (via their upstream strategies) and NumPy (via its Hypothesis extra). Of course, strategies in the Array API namespace can still be used to test Xarray or NumPy, just like any other array library.

Hypothesis offers strategies for Array API adopting libraries in the `hypothesis.extra.array_api` package. See issue #3037 for more details. If you want to test with CuPy, Dask, JAX, MXNet, PyTorch, TensorFlow, or Xarray - or just NumPy - this is the extension for you!

hypothesis.extra.array_api.make_strategies_namespace(xp, *, api_version=None)

  Creates a strategies namespace for the given array module.

  - `xp` is the Array API library to automatically pass to the namespaced methods.

  - `api_version` is the version of the Array API which the returned strategies namespace should conform to. If `None`, the latest API version which `xp` supports will be inferred from `xp.__array_api_version__`. If a version string in the `YYYY.MM` format, the strategies namespace will conform to that version if supported.

  A `python:types.SimpleNamespace` is returned which contains all the strategy methods in this module but without requiring the `xp` argument. Creating and using a strategies namespace for NumPy’s Array API implementation would go like this:

      >>> xp.__array_api_version__  # xp is your desired array library
      '2021.12'
      >>> xps = make_strategies_namespace(xp)
      >>> xps.api_version
      '2021.12'
      >>> x = xps.arrays(xp.int8, (2, 3)).example()
      >>> x
      Array([[-8,  6,  3],
             [-6,  4,  6]], dtype=int8)
      >>> x.__array_namespace__() is xp
      True

The resulting namespace contains all our familiar strategies like `arrays()` and `from_dtype()`, but based on the Array API standard semantics and returning objects from the `xp` module:

xps.from_dtype(

  dtype,
  *,
  min_value=None,
  max_value=None,
  allow_nan=None,
  allow_infinity=None,
  allow_subnormal=None,
  exclude_min=None,
  exclude_max=None,

)

  Return a strategy for any value of the given dtype.

  Values generated are of the Python scalar which is promotable to `dtype`, where the values do not exceed its bounds.

  - `dtype` may be a dtype object or the string name of a valid dtype.

  Compatible `**kwargs` are passed to the inferred strategy function for integers and floats. This allows you to customise the min and max values, and exclude non-finite numbers. This is particularly useful when kwargs are passed through from `arrays()`, as it seamlessly handles the `width` or other representable bounds for you.

xps.arrays(

  dtype,
  shape,
  *,
  elements=None,
  fill=None,
  unique=False,

)

  Returns a strategy for arrays.

  - `dtype` may be a valid dtype object or name, or a strategy that generates such values.

  - `shape` may be an integer >= 0, a tuple of such integers, or a strategy that generates such values.

  - `elements` is a strategy for values to put in the array. If `None` then a suitable value will be inferred based on the dtype, which may give any legal value (including e.g. NaN for floats). If a mapping, it will be passed as `**kwargs` to `from_dtype()` when inferring based on the dtype.

  - `fill` is a strategy that may be used to generate a single background value for the array. If `None`, a suitable default will be inferred based on the other arguments. If set to `nothing()` then filling behaviour will be disabled entirely and every element will be generated independently.

  - `unique` specifies if the elements of the array should all be distinct from one another; if fill is also set, the only valid values for fill to return are NaN values.

  Arrays of specified `dtype` and `shape` are generated for example like this:

      >>> from numpy import array_api as xp
      >>> xps.arrays(xp, xp.int8, (2, 3)).example()
      Array([[-8,  6,  3],
             [-6,  4,  6]], dtype=int8)

  Specifying element boundaries by a `python:dict` of the kwargs to pass to `from_dtype()` will ensure `dtype` bounds will be respected.

      >>> xps.arrays(xp, xp.int8, 3, elements={"min_value": 10}).example()
      Array([125, 13, 79], dtype=int8)

      >>> xps.arrays(xp, xp.float32, 3, elements=floats(0, 1, width=32)).example()
      Array([ 0.88974794,  0.77387938,  0.1977879 ], dtype=float32)

  Array values are generated in two parts:

  1. A single value is drawn from the fill strategy and is used to create a filled array.

  2. Some subset of the coordinates of the array are populated with a value drawn from the elements strategy (or its inferred form).

  You can set `fill` to `nothing()` if you want to disable this behaviour and draw a value for every element.

  By default `arrays` will attempt to infer the correct fill behaviour: if `unique` is also `True`, no filling will occur. Otherwise, if it looks safe to reuse the values of elements across multiple coordinates (this will be the case for any inferred strategy, and for most of the builtins, but is not the case for mutable values or strategies built with flatmap, map, composite, etc.) then it will use the elements strategy as the fill, else it will default to having no fill.

  Having a fill helps Hypothesis craft high quality examples, but its main importance is when the array generated is large: Hypothesis is primarily designed around testing small examples. If you have arrays with hundreds or more elements, having a fill value is essential if you want your tests to run in reasonable time.

xps.array_shapes(

  *,
  min_dims=1,
  max_dims=None,
  min_side=1,
  max_side=None,

)

  Return a strategy for array shapes (tuples of int >= 1).

  - `min_dims` is the smallest length that the generated shape can possess.

  - `max_dims` is the largest length that the generated shape can possess, defaulting to `min_dims + 2`.

  - `min_side` is the smallest size that a dimension can possess.

  - `max_side` is the largest size that a dimension can possess, defaulting to `min_side + 5`.

xps.scalar_dtypes()

  Return a strategy for all valid dtype objects.

xps.boolean_dtypes()

  Return a strategy for just the boolean dtype object.

xps.numeric_dtypes()

  Return a strategy for all numeric dtype objects.

xps.real_dtypes()

  Return a strategy for all real-valued dtype objects.

xps.integer_dtypes(*, sizes=(8, 16, 32, 64))

  Return a strategy for signed integer dtype objects.

  `sizes` contains the signed integer sizes in bits, defaulting to `(8, 16, 32, 64)` which covers all valid sizes.

xps.unsigned_integer_dtypes(*, sizes=(8, 16, 32, 64))

  Return a strategy for unsigned integer dtype objects.

  `sizes` contains the unsigned integer sizes in bits, defaulting to `(8, 16, 32, 64)` which covers all valid sizes.

xps.floating_dtypes(*, sizes=(32, 64))

  Return a strategy for real-valued floating-point dtype objects.

  `sizes` contains the floating-point sizes in bits, defaulting to `(32, 64)` which covers all valid sizes.

xps.complex_dtypes(*, sizes=(64, 128))

  Return a strategy for complex dtype objects.

  `sizes` contains the complex sizes in bits, defaulting to `(64, 128)` which covers all valid sizes.

xps.valid_tuple_axes(ndim, *, min_size=0, max_size=None)

  > Return a strategy for permissible tuple-values for the `axis` argument in Array API sequential methods e.g. `sum`, given the specified dimensionality.

  > All tuples will have a length >= `min_size` and <= `max_size`. The default

  value for `max_size` is `ndim`.

  Examples from this strategy shrink towards an empty tuple, which render most sequential functions as no-ops.

  The following are some examples drawn from this strategy.

      >>> [valid_tuple_axes(3).example() for i in range(4)]
      [(-3, 1), (0, 1, -1), (0, 2), (0, -2, 2)]

  `valid_tuple_axes` can be joined with other strategies to generate any type of valid axis object, i.e. integers, tuples, and `None`:

      any_axis_strategy = none() | integers(-ndim, ndim - 1) | valid_tuple_axes(ndim)

xps.broadcastable_shapes(

  shape,
  *,
  min_dims=0,
  max_dims=None,
  min_side=1,
  max_side=None,

)

  Return a strategy for shapes that are broadcast-compatible with the provided shape.

  Examples from this strategy shrink towards a shape with length `min_dims`. The size of an aligned dimension shrinks towards size `1`. The size of an unaligned dimension shrink towards `min_side`.

  - `shape` is a tuple of integers.

  - `min_dims` is the smallest length that the generated shape can possess.

  - `max_dims` is the largest length that the generated shape can possess, defaulting to `max(len(shape), min_dims) + 2`.

  - `min_side` is the smallest size that an unaligned dimension can possess.

  - `max_side` is the largest size that an unaligned dimension can possess, defaulting to 2 plus the size of the largest aligned dimension.

  The following are some examples drawn from this strategy.

      >>> [broadcastable_shapes(shape=(2, 3)).example() for i in range(5)]
      [(1, 3), (), (2, 3), (2, 1), (4, 1, 3), (3, )]

xps.mutually_broadcastable_shapes(

  num_shapes,
  *,
  base_shape=(),
  min_dims=0,
  max_dims=None,
  min_side=1,
  max_side=None,

)

  Return a strategy for a specified number of shapes N that are mutually-broadcastable with one another and with the provided base shape.

  - `num_shapes` is the number of mutually broadcast-compatible shapes to generate.

  - `base_shape` is the shape against which all generated shapes can broadcast. The default shape is empty, which corresponds to a scalar and thus does not constrain broadcasting at all.

  - `min_dims` is the smallest length that the generated shape can possess.

  - `max_dims` is the largest length that the generated shape can possess, defaulting to `max(len(shape), min_dims) + 2`.

  - `min_side` is the smallest size that an unaligned dimension can possess.

  - `max_side` is the largest size that an unaligned dimension can possess, defaulting to 2 plus the size of the largest aligned dimension.

  The strategy will generate a `python:typing.NamedTuple` containing:

  - `input_shapes` as a tuple of the N generated shapes.

  - `result_shape` as the resulting shape produced by broadcasting the N shapes with the base shape.

  The following are some examples drawn from this strategy.

      >>> # Draw three shapes where each shape is broadcast-compatible with (2, 3)
      ... strat = mutually_broadcastable_shapes(num_shapes=3, base_shape=(2, 3))
      >>> for _ in range(5):
      ...     print(strat.example())
      BroadcastableShapes(input_shapes=((4, 1, 3), (4, 2, 3), ()), result_shape=(4, 2, 3))
      BroadcastableShapes(input_shapes=((3,), (1, 3), (2, 3)), result_shape=(2, 3))
      BroadcastableShapes(input_shapes=((), (), ()), result_shape=())
      BroadcastableShapes(input_shapes=((3,), (), (3,)), result_shape=(3,))
      BroadcastableShapes(input_shapes=((1, 2, 3), (3,), ()), result_shape=(1, 2, 3))

xps.indices(

  shape,
  *,
  min_dims=0,
  max_dims=None,
  allow_newaxis=False,
  allow_ellipsis=True,

)

  Return a strategy for valid indices of arrays with the specified shape, which may include dimensions of size zero.

  It generates tuples containing some mix of integers, `python:slice` objects, `...` (an `Ellipsis`), and `None`. When a length-one tuple would be generated, this strategy may instead return the element which will index the first axis, e.g. `5` instead of `(5,)`.

  - `shape` is the shape of the array that will be indexed, as a tuple of integers >= 0. This must be at least two-dimensional for a tuple to be a valid index; for one-dimensional arrays use `slices()` instead.

  - `min_dims` is the minimum dimensionality of the resulting array from use of the generated index.

  - `max_dims` is the the maximum dimensionality of the resulting array, defaulting to `len(shape) if not allow_newaxis else max(len(shape), min_dims) + 2`.

  - `allow_ellipsis` specifies whether `None` is allowed in the index.

  - `allow_ellipsis` specifies whether `...` is allowed in the index.

## Django

See also

See the Django API reference for documentation on testing Django with Hypothesis.

hypothesis.extra.django.from_model(model, /, **field_strategies)

  Return a strategy for examples of `model`.

  Warning

  Hypothesis creates saved models. This will run inside your testing transaction when using the test runner, but if you use the dev console this will leave debris in your database.

  `model` must be an subclass of `Model`. Strategies for fields may be passed as keyword arguments, for example `is_staff=st.just(False)`. In order to support models with fields named “model”, this is a positional-only parameter.

  Hypothesis can often infer a strategy based the field type and validators, and will attempt to do so for any required fields. No strategy will be inferred for an `AutoField`, nullable field, foreign key, or field for which a keyword argument is passed to `from_model()`. For example, a Shop type with a foreign key to Company could be generated with:

      shop_strategy = from_model(Shop, company=from_model(Company))

  Like for `builds()`, you can pass `...` (`python:Ellipsis`) as a keyword argument to infer a strategy for a field which has a default value instead of using the default.

hypothesis.extra.django.from_form(form, form_kwargs=None, **field_strategies)

  Return a strategy for examples of `form`.

  `form` must be an subclass of `Form`. Strategies for fields may be passed as keyword arguments, for example `is_staff=st.just(False)`.

  Hypothesis can often infer a strategy based the field type and validators, and will attempt to do so for any required fields. No strategy will be inferred for a disabled field or field for which a keyword argument is passed to `from_form()`.

  This function uses the fields of an unbound `form` instance to determine field strategies, any keyword arguments needed to instantiate the unbound `form` instance can be passed into `from_form()` as a dict with the keyword `form_kwargs`. E.g.:

      shop_strategy = from_form(Shop, form_kwargs={"company_id": 5})

  Like for `builds()`, you can pass `...` (`python:Ellipsis`) as a keyword argument to infer a strategy for a field which has a default value instead of using the default.

hypothesis.extra.django.from_field(field)

  Return a strategy for values that fit the given field.

  This function is used by `from_form()` and `from_model()` for any fields that require a value, or for which you passed `...` (`python:Ellipsis`) to infer a strategy from an annotation.

  It’s pretty similar to the core `from_type()` function, with a subtle but important difference: `from_field` takes a Field instance, rather than a Field subtype, so that it has access to instance attributes such as string length and validators.

hypothesis.extra.django.register_field_strategy(field_type, strategy)

  Add an entry to the global field-to-strategy lookup used by `from_field()`.

  `field_type` must be a subtype of `django.db.models.Field` or `django.forms.Field`, which must not already be registered. `strategy` must be a `SearchStrategy`.

## hypothesis[lark]

Note

Strategies in this module require the `hypothesis[lark]` extra, via `pip install hypothesis[lark]`.

This extra can be used to generate strings matching any context-free grammar, using the Lark parser library.

It currently only supports Lark’s native EBNF syntax, but we plan to extend this to support other common syntaxes such as ANTLR and RFC 5234 ABNF. Lark already supports loading grammars from nearley.js, so you may not have to write your own at all.

hypothesis.extra.lark.from_lark(

  grammar,
  *,
  start=None,
  explicit=None,
  alphabet=characters(codec='utf-8'),

)

  A strategy for strings accepted by the given context-free grammar.

  `grammar` must be a `Lark` object, which wraps an EBNF specification. The Lark EBNF grammar reference can be found here.

  `from_lark` will automatically generate strings matching the nonterminal `start` symbol in the grammar, which was supplied as an argument to the Lark class. To generate strings matching a different symbol, including terminals, you can override this by passing the `start` argument to `from_lark`. Note that Lark may remove unreachable productions when the grammar is compiled, so you should probably pass the same value for `start` to both.

  Currently `from_lark` does not support grammars that need custom lexing. Any lexers will be ignored, and any undefined terminals from the use of `%declare` will result in generation errors. To define strategies for such terminals, pass a dictionary mapping their name to a corresponding strategy as the `explicit` argument.

  The hypothesmith project includes a strategy for Python source, based on a grammar and careful post-processing.

Example grammars, which may provide a useful starting point for your tests, can be found in the Lark repository and in this third-party collection.

## hypothesis[pytz]

Note

Strategies in this module require the `hypothesis[pytz]` extra, via `pip install hypothesis[pytz]`.

This module provides pytz timezones.

If you are unable to use the stdlib `zoneinfo` module, e.g. via the `hypothesis.strategies.timezones()` strategy, you can use this strategy with `hypothesis.strategies.datetimes()` and `hypothesis.strategies.times()` to produce timezone-aware values.

Deprecated since version :mod:`zoneinfo`: was added we intend to remove `hypothesis.extra.pytz`, after libraries such as Pandas and Django complete their own migrations.

hypothesis.extra.pytz.timezones()

  Any timezone in the Olsen database, as a pytz tzinfo object.

  This strategy minimises to UTC, or the smallest possible fixed offset, and is designed for use with `hypothesis.strategies.datetimes()`.

  Tip

  Prefer the `hypothesis.strategies.timezones()` strategy, which uses the stdlib `zoneinfo` module and avoids the many footguns in pytz.

## hypothesis[dateutil]

Note

Strategies in this module require the `hypothesis[dateutil]` extra, via `pip install hypothesis[dateutil]`.

### hypothesis[dateutil]

This module provides dateutil timezones.

You can use this strategy to make `datetimes()` and `times()` produce timezone-aware values.

Tip

Consider using the stdlib `zoneinfo` module, via `st.timezones()`.

hypothesis.extra.dateutil.timezones()

  Any timezone from dateutil.

  This strategy minimises to UTC, or the timezone with the smallest offset from UTC as of 2000-01-01, and is designed for use with `datetimes()`.

  Note that the timezones generated by the strategy may vary depending on the configuration of your machine. See the dateutil documentation for more information.