def integers(
min_value: Optional[int] = None,
max_value: Optional[int] = None,
) -> SearchStrategy[int]:
"""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).
"""
check_valid_bound(min_value, "min_value")
check_valid_bound(max_value, "max_value")
check_valid_interval(min_value, max_value, "min_value", "max_value")
if min_value is not None:
if min_value != int(min_value):
raise InvalidArgument(
"min_value=%r of type %r cannot be exactly represented as an integer."
% (min_value, type(min_value)))
min_value = int(min_value)
if max_value is not None:
if max_value != int(max_value):
raise InvalidArgument(
"max_value=%r of type %r cannot be exactly represented as an integer."
% (max_value, type(max_value)))
max_value = int(max_value)
return IntegersStrategy(min_value, max_value)
def integers(
min_value: Optional[int] = None,
max_value: Optional[int] = None,
) -> SearchStrategy[int]:
"""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).
"""
check_valid_bound(min_value, "min_value")
check_valid_bound(max_value, "max_value")
check_valid_interval(min_value, max_value, "min_value", "max_value")
if min_value is not None:
if min_value != int(min_value):
raise InvalidArgument(
"min_value=%r of type %r cannot be exactly represented as an integer."
% (min_value, type(min_value))
)
min_value = int(min_value)
if max_value is not None:
if max_value != int(max_value):
raise InvalidArgument(
"max_value=%r of type %r cannot be exactly represented as an integer."
% (max_value, type(max_value))
)
max_value = int(max_value)
if min_value is None:
if max_value is None:
return WideRangeIntStrategy()
else:
if max_value > 0:
return WideRangeIntStrategy().filter(lambda x: x <= max_value)
return WideRangeIntStrategy().map(lambda x: max_value - abs(x))
else:
if max_value is None:
if min_value < 0:
return WideRangeIntStrategy().filter(lambda x: x >= min_value)
return WideRangeIntStrategy().map(lambda x: min_value + abs(x))
else:
assert min_value <= max_value
if min_value == max_value:
return just(min_value)
elif min_value >= 0:
return BoundedIntStrategy(min_value, max_value)
elif max_value <= 0:
return BoundedIntStrategy(-max_value, -min_value).map(lambda t: -t)
else:
return integers(min_value=0, max_value=max_value) | integers(
min_value=min_value, max_value=0
)
def check_valid_minmax(prefix, val, info_obj):
name = f"{prefix}_value"
check_valid_bound(val, name)
check_argument(
val >= info_obj.min,
f"dtype={dtype} requires {name}={val} to be at least {info_obj.min}",
)
check_argument(
val <= info_obj.max,
f"dtype={dtype} requires {name}={val} to be at most {info_obj.max}",
)
def _from_dtype(
xp: Any,
dtype: Union[DataType, str],
*,
min_value: Optional[Union[int, float]] = None,
max_value: Optional[Union[int, float]] = None,
allow_nan: Optional[bool] = None,
allow_infinity: Optional[bool] = None,
allow_subnormal: Optional[bool] = None,
exclude_min: Optional[bool] = None,
exclude_max: Optional[bool] = None,
) -> st.SearchStrategy[Union[bool, int, float]]:
"""Return a strategy for any value of the given dtype.
Values generated are of the Python scalar which is
:xp-ref:`promotable <type_promotion.html>` to ``dtype``, where the values do
not exceed its bounds.
* ``dtype`` may be a dtype object or the string name of a
:xp-ref:`valid dtype <data_types.html>`.
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 :func:`arrays()`, as it seamlessly handles the ``width``
or other representable bounds for you.
"""
check_xp_attributes(xp, ["iinfo", "finfo"])
if isinstance(dtype, str):
dtype = dtype_from_name(xp, dtype)
builtin = find_castable_builtin_for_dtype(xp, dtype)
def check_valid_minmax(prefix, val, info_obj):
name = f"{prefix}_value"
check_valid_bound(val, name)
check_argument(
val >= info_obj.min,
f"dtype={dtype} requires {name}={val} to be at least {info_obj.min}",
)
check_argument(
val <= info_obj.max,
f"dtype={dtype} requires {name}={val} to be at most {info_obj.max}",
)
if builtin is bool:
return st.booleans()
elif builtin is int:
iinfo = xp.iinfo(dtype)
if min_value is None:
min_value = iinfo.min
if max_value is None:
max_value = iinfo.max
check_valid_integer(min_value, "min_value")
check_valid_integer(max_value, "max_value")
assert isinstance(min_value, int)
assert isinstance(max_value, int)
check_valid_minmax("min", min_value, iinfo)
check_valid_minmax("max", max_value, iinfo)
check_valid_interval(min_value, max_value, "min_value", "max_value")
return st.integers(min_value=min_value, max_value=max_value)
else:
finfo = xp.finfo(dtype)
kw = {}
# Whilst we know the boundary values of float dtypes from finfo, we do
# not assign them to the floats() strategy by default - passing min/max
# values will modify test case reduction behaviour so that simple bugs
# may become harder for users to identify. We plan to improve floats()
# behaviour in https://github.com/HypothesisWorks/hypothesis/issues/2907.
# Setting width should manage boundary values for us anyway.
if min_value is not None:
check_valid_bound(min_value, "min_value")
assert isinstance(min_value, Real)
check_valid_minmax("min", min_value, finfo)
kw["min_value"] = min_value
if max_value is not None:
check_valid_bound(max_value, "max_value")
assert isinstance(max_value, Real)
check_valid_minmax("max", max_value, finfo)
if min_value is not None:
check_valid_interval(min_value, max_value, "min_value",
"max_value")
kw["max_value"] = max_value
# We infer whether an array module will flush subnormals to zero, as may
# be the case when libraries are built with compiler options that
# violate IEEE-754 (e.g. -ffast-math and -ftz=true). Note we do this for
# the specific dtype, as compilers may end up flushing subnormals for
# one float but supporting subnormals for the other.
#
# By default, floats() will generate subnormals if they are in the
# inferred values range. If we have detected that xp flushes to zero for
# the passed dtype, we ensure from_dtype() will not generate subnormals
# by default.
if allow_subnormal is not None:
kw["allow_subnormal"] = allow_subnormal
else:
subnormal = next_down(finfo.smallest_normal, width=finfo.bits)
ftz = bool(xp.asarray(subnormal, dtype=dtype) == 0)
if ftz:
kw["allow_subnormal"] = False
if allow_nan is not None:
kw["allow_nan"] = allow_nan
if allow_infinity is not None:
kw["allow_infinity"] = allow_infinity
if exclude_min is not None:
kw["exclude_min"] = exclude_min
if exclude_max is not None:
kw["exclude_max"] = exclude_max
return st.floats(width=finfo.bits, **kw)
def _check_valid_size_interval(min_size, max_size, name, floor=0):
"""Check valid for integers strategy and array shapes."""
# same checks as done in integers
check_valid_bound(min_size, name)
check_valid_bound(max_size, name)
order_check(name, floor, min_size, max_size) # ensure non-none & above 0
def floats(
min_value: Optional[Real] = None,
max_value: Optional[Real] = None,
*,
allow_nan: Optional[bool] = None,
allow_infinity: Optional[bool] = None,
width: int = 64,
exclude_min: bool = False,
exclude_max: bool = False,
) -> SearchStrategy[float]:
"""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.
Where not explicitly ruled out by the bounds, all of infinity, -infinity
and NaN 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 ``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.
"""
check_type(bool, exclude_min, "exclude_min")
check_type(bool, exclude_max, "exclude_max")
if allow_nan is None:
allow_nan = bool(min_value is None and max_value is None)
elif allow_nan and (min_value is not None or max_value is not None):
raise InvalidArgument(
f"Cannot have allow_nan={allow_nan!r}, with min_value or max_value"
)
if width not in (16, 32, 64):
raise InvalidArgument(
f"Got width={width!r}, but the only valid values "
"are the integers 16, 32, and 64.")
check_valid_bound(min_value, "min_value")
check_valid_bound(max_value, "max_value")
min_arg, max_arg = min_value, max_value
if min_value is not None:
min_value = float_of(min_value, width)
assert isinstance(min_value, float)
if max_value is not None:
max_value = float_of(max_value, width)
assert isinstance(max_value, float)
if min_value != min_arg:
raise InvalidArgument(
f"min_value={min_arg!r} cannot be exactly represented as a float "
f"of width {width} - use min_value={min_value!r} instead.")
if max_value != max_arg:
raise InvalidArgument(
f"max_value={max_arg!r} cannot be exactly represented as a float "
f"of width {width} - use max_value={max_value!r} instead.")
if exclude_min and (min_value is None or min_value == math.inf):
raise InvalidArgument(f"Cannot exclude min_value={min_value!r}")
if exclude_max and (max_value is None or max_value == -math.inf):
raise InvalidArgument(f"Cannot exclude max_value={max_value!r}")
if min_value is not None and (exclude_min or (min_arg is not None
and min_value < min_arg)):
min_value = next_up(min_value, width)
if min_value == min_arg:
assert min_value == min_arg == 0
assert is_negative(min_arg) and not is_negative(min_value)
min_value = next_up(min_value, width)
assert min_value > min_arg # type: ignore
if max_value is not None and (exclude_max or (max_arg is not None
and max_value > max_arg)):
max_value = next_down(max_value, width)
if max_value == max_arg:
assert max_value == max_arg == 0
assert is_negative(max_value) and not is_negative(max_arg)
max_value = next_down(max_value, width)
assert max_value < max_arg # type: ignore
if min_value == -math.inf:
min_value = None
if max_value == math.inf:
max_value = None
bad_zero_bounds = (min_value == max_value == 0 and is_negative(max_value)
and not is_negative(min_value))
if (min_value is not None and max_value is not None
and (min_value > max_value or bad_zero_bounds)):
# This is a custom alternative to check_valid_interval, because we want
# to include the bit-width and exclusion information in the message.
msg = (
"There are no %s-bit floating-point values between min_value=%r "
"and max_value=%r" % (width, min_arg, max_arg))
if exclude_min or exclude_max:
msg += f", exclude_min={exclude_min!r} and exclude_max={exclude_max!r}"
raise InvalidArgument(msg)
if allow_infinity is None:
allow_infinity = bool(min_value is None or max_value is None)
elif allow_infinity:
if min_value is not None and max_value is not None:
raise InvalidArgument(
f"Cannot have allow_infinity={allow_infinity!r}, "
"with both min_value and max_value")
elif min_value == math.inf:
raise InvalidArgument("allow_infinity=False excludes min_value=inf")
elif max_value == -math.inf:
raise InvalidArgument("allow_infinity=False excludes max_value=-inf")
unbounded_floats = FloatStrategy(allow_infinity=allow_infinity,
allow_nan=allow_nan,
width=width)
if min_value is None and max_value is None:
return unbounded_floats
elif min_value is not None and max_value is not None:
if min_value == max_value:
assert isinstance(min_value, float)
result = just(min_value)
elif is_negative(min_value):
if is_negative(max_value):
return floats(min_value=-max_value,
max_value=-min_value,
width=width).map(operator.neg)
else:
return floats(
min_value=0.0, max_value=max_value, width=width) | floats(
min_value=0.0, max_value=-min_value, width=width).map(
operator.neg)
elif count_between_floats(min_value, max_value) > 1000:
return FixedBoundedFloatStrategy(lower_bound=min_value,
upper_bound=max_value,
width=width)
else:
ub_int = float_to_int(max_value, width)
lb_int = float_to_int(min_value, width)
assert lb_int <= ub_int
result = integers(
min_value=lb_int,
max_value=ub_int).map(lambda x: int_to_float(x, width))
elif min_value is not None:
assert isinstance(min_value, float)
if is_negative(min_value):
# Ignore known bug https://github.com/python/mypy/issues/6697
return unbounded_floats.map(abs) | floats( # type: ignore
min_value=min_value,
max_value=-0.0,
width=width)
else:
result = unbounded_floats.map(lambda x: min_value + abs(x))
else:
assert isinstance(max_value, float)
if not is_negative(max_value):
return floats(
min_value=0.0, max_value=max_value,
width=width) | unbounded_floats.map(lambda x: -abs(x))
else:
result = unbounded_floats.map(lambda x: max_value - abs(x))
if width < 64:
def downcast(x):
try:
return float_of(x, width)
except OverflowError: # pragma: no cover
reject()
result = result.map(downcast)
if not allow_infinity:
result = result.filter(lambda x: not math.isinf(x))
return result
def floats(
min_value: Optional[Real] = None,
max_value: Optional[Real] = None,
*,
allow_nan: Optional[bool] = None,
allow_infinity: Optional[bool] = None,
allow_subnormal: Optional[bool] = None,
width: int = 64,
exclude_min: bool = False,
exclude_max: bool = False,
) -> SearchStrategy[float]:
"""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,
:wikipedia:`subnormals <Subnormal_number>`, 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 ``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.
"""
check_type(bool, exclude_min, "exclude_min")
check_type(bool, exclude_max, "exclude_max")
if allow_nan is None:
allow_nan = bool(min_value is None and max_value is None)
elif allow_nan and (min_value is not None or max_value is not None):
raise InvalidArgument(
f"Cannot have allow_nan={allow_nan!r}, with min_value or max_value"
)
if width not in (16, 32, 64):
raise InvalidArgument(
f"Got width={width!r}, but the only valid values "
"are the integers 16, 32, and 64.")
check_valid_bound(min_value, "min_value")
check_valid_bound(max_value, "max_value")
if math.copysign(1.0, -0.0) == 1.0: # pragma: no cover
raise FloatingPointError(
"You Python install can't represent -0.0, which is required by the "
"IEEE-754 floating-point specification. This is probably because it was "
"compiled with an unsafe option like -ffast-math; for a more detailed "
"explanation see https://simonbyrne.github.io/notes/fastmath/")
if allow_subnormal and next_up(0.0, width=width) == 0: # pragma: no cover
# Not worth having separate CI envs and dependencies just to cover this branch;
# discussion in https://github.com/HypothesisWorks/hypothesis/issues/3092
#
# Erroring out here ensures that the database contents are interpreted
# consistently - which matters for such a foundational strategy, even if it's
# not always true for all user-composed strategies further up the stack.
raise FloatingPointError(
f"Got allow_subnormal={allow_subnormal!r}, but we can't represent "
f"subnormal floats right now, in violation of the IEEE-754 floating-point "
f"specification. This is usually because something was compiled with "
f"-ffast-math or a similar option, which sets global processor state. "
f"See https://simonbyrne.github.io/notes/fastmath/ for a more detailed "
f"writeup - and good luck!")
min_arg, max_arg = min_value, max_value
if min_value is not None:
min_value = float_of(min_value, width)
assert isinstance(min_value, float)
if max_value is not None:
max_value = float_of(max_value, width)
assert isinstance(max_value, float)
if min_value != min_arg:
raise InvalidArgument(
f"min_value={min_arg!r} cannot be exactly represented as a float "
f"of width {width} - use min_value={min_value!r} instead.")
if max_value != max_arg:
raise InvalidArgument(
f"max_value={max_arg!r} cannot be exactly represented as a float "
f"of width {width} - use max_value={max_value!r} instead.")
if exclude_min and (min_value is None or min_value == math.inf):
raise InvalidArgument(f"Cannot exclude min_value={min_value!r}")
if exclude_max and (max_value is None or max_value == -math.inf):
raise InvalidArgument(f"Cannot exclude max_value={max_value!r}")
assumed_allow_subnormal = allow_subnormal is None or allow_subnormal
if min_value is not None and (exclude_min or (min_arg is not None
and min_value < min_arg)):
min_value = next_up_normal(min_value, width, assumed_allow_subnormal)
if min_value == min_arg:
assert min_value == min_arg == 0
assert is_negative(min_arg) and not is_negative(min_value)
min_value = next_up_normal(min_value, width,
assumed_allow_subnormal)
assert min_value > min_arg # type: ignore
if max_value is not None and (exclude_max or (max_arg is not None
and max_value > max_arg)):
max_value = next_down_normal(max_value, width, assumed_allow_subnormal)
if max_value == max_arg:
assert max_value == max_arg == 0
assert is_negative(max_value) and not is_negative(max_arg)
max_value = next_down_normal(max_value, width,
assumed_allow_subnormal)
assert max_value < max_arg # type: ignore
if min_value == -math.inf:
min_value = None
if max_value == math.inf:
max_value = None
bad_zero_bounds = (min_value == max_value == 0 and is_negative(max_value)
and not is_negative(min_value))
if (min_value is not None and max_value is not None
and (min_value > max_value or bad_zero_bounds)):
# This is a custom alternative to check_valid_interval, because we want
# to include the bit-width and exclusion information in the message.
msg = (
"There are no %s-bit floating-point values between min_value=%r "
"and max_value=%r" % (width, min_arg, max_arg))
if exclude_min or exclude_max:
msg += f", exclude_min={exclude_min!r} and exclude_max={exclude_max!r}"
raise InvalidArgument(msg)
if allow_infinity is None:
allow_infinity = bool(min_value is None or max_value is None)
elif allow_infinity:
if min_value is not None and max_value is not None:
raise InvalidArgument(
f"Cannot have allow_infinity={allow_infinity!r}, "
"with both min_value and max_value")
elif min_value == math.inf:
if min_arg == math.inf:
raise InvalidArgument(
"allow_infinity=False excludes min_value=inf")
raise InvalidArgument(
f"exclude_min=True turns min_value={min_arg!r} into inf, "
"but allow_infinity=False")
elif max_value == -math.inf:
if max_arg == -math.inf:
raise InvalidArgument(
"allow_infinity=False excludes max_value=-inf")
raise InvalidArgument(
f"exclude_max=True turns max_value={max_arg!r} into -inf, "
"but allow_infinity=False")
smallest_normal = width_smallest_normals[width]
if allow_subnormal is None:
if min_value is not None and max_value is not None:
if min_value == max_value:
allow_subnormal = -smallest_normal < min_value < smallest_normal
else:
allow_subnormal = (min_value < smallest_normal
and max_value > -smallest_normal)
elif min_value is not None:
allow_subnormal = min_value < smallest_normal
elif max_value is not None:
allow_subnormal = max_value > -smallest_normal
else:
allow_subnormal = True
if allow_subnormal:
if min_value is not None and min_value >= smallest_normal:
raise InvalidArgument(
f"allow_subnormal=True, but minimum value {min_value} "
f"excludes values below float{width}'s "
f"smallest positive normal {smallest_normal}")
if max_value is not None and max_value <= -smallest_normal:
raise InvalidArgument(
f"allow_subnormal=True, but maximum value {max_value} "
f"excludes values above float{width}'s "
f"smallest negative normal {-smallest_normal}")
# Any type hint silences mypy when we unpack these parameters
kw: Any = {"allow_subnormal": allow_subnormal, "width": width}
unbounded_floats = FloatStrategy(allow_infinity=allow_infinity,
allow_nan=allow_nan,
**kw)
if min_value is None and max_value is None:
return unbounded_floats
elif min_value is not None and max_value is not None:
if min_value == max_value:
assert isinstance(min_value, float)
result = just(min_value)
elif is_negative(min_value):
if is_negative(max_value):
return floats(min_value=-max_value, max_value=-min_value,
**kw).map(operator.neg)
else:
return floats(
min_value=0.0, max_value=max_value, **kw) | floats(
min_value=0.0, max_value=-min_value, **kw).map(
operator.neg # type: ignore
)
elif (count_between_floats(min_value, max_value, width) > 1000
or not allow_subnormal):
return FixedBoundedFloatStrategy(lower_bound=min_value,
upper_bound=max_value,
**kw)
else:
ub_int = float_to_int(max_value, width)
lb_int = float_to_int(min_value, width)
assert lb_int <= ub_int
result = integers(
min_value=lb_int,
max_value=ub_int).map(lambda x: int_to_float(x, width))
elif min_value is not None:
assert isinstance(min_value, float)
if is_negative(min_value):
# Ignore known bug https://github.com/python/mypy/issues/6697
return unbounded_floats.map(abs) | floats( # type: ignore
min_value=min_value, max_value=-0.0, **kw)
else:
result = unbounded_floats.map(lambda x: min_value + abs(x))
else:
assert isinstance(max_value, float)
if not is_negative(max_value):
return floats(min_value=0.0, max_value=max_value, **
kw) | unbounded_floats.map(lambda x: -abs(x))
else:
result = unbounded_floats.map(lambda x: max_value - abs(x))
if width < 64:
def downcast(x):
try:
return float_of(x, width)
except OverflowError: # pragma: no cover
reject()
result = result.map(downcast)
if not allow_infinity:
result = result.filter(lambda x: not math.isinf(x))
return result