def indexes(*,
elements: st.SearchStrategy[Ex] = None,
dtype: Any = None,
min_size: int = 0,
max_size: int = None,
unique: bool = True) -> st.SearchStrategy[pandas.Index]:
"""Provides a strategy for producing a :class:`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.
"""
check_valid_size(min_size, "min_size")
check_valid_size(max_size, "max_size")
check_valid_interval(min_size, max_size, "min_size", "max_size")
check_type(bool, unique, "unique")
elements, dtype = elements_and_dtype(elements, dtype)
if max_size is None:
max_size = min_size + DEFAULT_MAX_SIZE
return ValueIndexStrategy(elements, dtype, min_size, max_size, unique)
def times(
min_value: dt.time = dt.time.min,
max_value: dt.time = dt.time.max,
*,
timezones: SearchStrategy[Optional[dt.tzinfo]] = none()
) -> SearchStrategy[dt.time]:
"""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 :py:func:`datetimes`.
Examples from this strategy shrink towards midnight, with the timezone
component shrinking as for the strategy that provided it.
"""
check_type(dt.time, min_value, "min_value")
check_type(dt.time, max_value, "max_value")
if min_value.tzinfo is not None:
raise InvalidArgument("min_value=%r must not have tzinfo" % min_value)
if max_value.tzinfo is not None:
raise InvalidArgument("max_value=%r must not have tzinfo" % max_value)
check_valid_interval(min_value, max_value, "min_value", "max_value")
day = dt.date(2000, 1, 1)
return datetimes(
min_value=dt.datetime.combine(day, min_value),
max_value=dt.datetime.combine(day, max_value),
timezones=timezones,
).map(lambda t: t.timetz())
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 datetimes(
min_value: dt.datetime = dt.datetime.min,
max_value: dt.datetime = dt.datetime.max,
*,
timezones: SearchStrategy[Optional[dt.tzinfo]] = none(),
allow_imaginary: bool = True,
) -> SearchStrategy[dt.datetime]:
"""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 :class:`~python:datetime.tzinfo` objects for 'aware' datetimes.
You can construct your own, though we recommend using the :pypi:`dateutil
<python-dateutil>` package and :func:`hypothesis.extra.dateutil.timezones`
strategy, and also provide :func:`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.
Note that because :pypi:`pytz` predates :pep:`495`, this does not work
correctly with timezones that use a negative DST offset (such as
``"Europe/Dublin"``).
Examples from this strategy shrink towards midnight on January 1st 2000,
local time.
"""
# Why must bounds be naive? In principle, we could also write a strategy
# that took aware bounds, but the API and validation is much harder.
# If you want to generate datetimes between two particular moments in
# time I suggest (a) just filtering out-of-bounds values; (b) if bounds
# are very close, draw a value and subtract its UTC offset, handling
# overflows and nonexistent times; or (c) do something customised to
# handle datetimes in e.g. a four-microsecond span which is not
# representable in UTC. Handling (d), all of the above, leads to a much
# more complex API for all users and a useful feature for very few.
check_type(bool, allow_imaginary, "allow_imaginary")
check_type(dt.datetime, min_value, "min_value")
check_type(dt.datetime, max_value, "max_value")
if min_value.tzinfo is not None:
raise InvalidArgument("min_value=%r must not have tzinfo" %
(min_value, ))
if max_value.tzinfo is not None:
raise InvalidArgument("max_value=%r must not have tzinfo" %
(max_value, ))
check_valid_interval(min_value, max_value, "min_value", "max_value")
if not isinstance(timezones, SearchStrategy):
raise InvalidArgument(
"timezones=%r must be a SearchStrategy that can provide tzinfo "
"for datetimes (either None or dt.tzinfo objects)" % (timezones, ))
return DatetimeStrategy(min_value, max_value, timezones, allow_imaginary)
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 dates(min_value: dt.date = dt.date.min,
max_value: dt.date = dt.date.max) -> SearchStrategy[dt.date]:
"""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.
"""
check_type(dt.date, min_value, "min_value")
check_type(dt.date, max_value, "max_value")
check_valid_interval(min_value, max_value, "min_value", "max_value")
if min_value == max_value:
return just(min_value)
return DateStrategy(min_value, max_value)
def timedeltas(
min_value: dt.timedelta = dt.timedelta.min,
max_value: dt.timedelta = dt.timedelta.max,
) -> SearchStrategy[dt.timedelta]:
"""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.
"""
check_type(dt.timedelta, min_value, "min_value")
check_type(dt.timedelta, max_value, "max_value")
check_valid_interval(min_value, max_value, "min_value", "max_value")
if min_value == max_value:
return just(min_value)
return TimedeltaStrategy(min_value=min_value, max_value=max_value)
def range_indexes(min_size=0, max_size=None):
"""Provides a strategy which generates an :class:`~pandas.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.
"""
check_valid_size(min_size, 'min_size')
check_valid_size(max_size, 'max_size')
if max_size is None:
max_size = min([min_size + DEFAULT_MAX_SIZE, 2**63 - 1])
check_valid_interval(min_size, max_size, 'min_size', 'max_size')
return st.integers(min_size, max_size).map(pandas.RangeIndex)
def range_indexes(min_size=0, max_size=None):
# type: (int, int) -> st.SearchStrategy[pandas.RangeIndex]
"""Provides a strategy which generates an :class:`~pandas.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.
"""
check_valid_size(min_size, "min_size")
check_valid_size(max_size, "max_size")
if max_size is None:
max_size = min([min_size + DEFAULT_MAX_SIZE, 2 ** 63 - 1])
check_valid_interval(min_size, max_size, "min_size", "max_size")
return st.integers(min_size, max_size).map(pandas.RangeIndex)
def valid_tuple_axes(ndim, min_size=0, max_size=None):
# type: (int, int, int) -> st.SearchStrategy[Shape]
"""Return a strategy for generating permissible tuple-values for the
``axis`` argument for a numpy sequential function (e.g.
:func:`numpy:numpy.sum`), given an array of the specified
dimensionality.
All tuples will have an 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.
.. code-block:: pycon
>>> [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``:
.. code-block:: pycon
any_axis_strategy = none() | integers(-ndim, ndim - 1) | valid_tuple_axes(ndim)
"""
if max_size is None:
max_size = ndim
check_type(integer_types, ndim, "ndim")
check_type(integer_types, min_size, "min_size")
check_type(integer_types, max_size, "max_size")
order_check("size", 0, min_size, max_size)
check_valid_interval(max_size, ndim, "max_size", "ndim")
# shrink axis values from negative to positive
axes = st.integers(0, max(0, 2 * ndim - 1)).map(
lambda x: x if x < ndim else x - 2 * ndim
)
return st.lists(axes, min_size, max_size, unique_by=lambda x: x % ndim).map(tuple)
def valid_tuple_axes(
ndim: int,
*,
min_size: int = 0,
max_size: Optional[int] = None,
) -> st.SearchStrategy[Tuple[int, ...]]:
"""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.
.. code-block:: pycon
>>> [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``:
.. code-block:: python
any_axis_strategy = none() | integers(-ndim, ndim - 1) | valid_tuple_axes(ndim)
"""
check_type(int, ndim, "ndim")
check_type(int, min_size, "min_size")
if max_size is None:
max_size = ndim
check_type(int, max_size, "max_size")
order_check("size", 0, min_size, max_size)
check_valid_interval(max_size, ndim, "max_size", "ndim")
axes = st.integers(0, max(0, 2 * ndim - 1)).map(
lambda x: x if x < ndim else x - 2 * ndim
)
return st.lists(
axes, min_size=min_size, max_size=max_size, unique_by=lambda x: x % ndim
).map(tuple)
def times(
min_value: dt.time = dt.time.min,
max_value: dt.time = dt.time.max,
*,
timezones: SearchStrategy[Optional[dt.tzinfo]] = none(),
) -> SearchStrategy[dt.time]:
"""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 :py:func:`datetimes`.
Examples from this strategy shrink towards midnight, with the timezone
component shrinking as for the strategy that provided it.
"""
check_type(dt.time, min_value, "min_value")
check_type(dt.time, max_value, "max_value")
if min_value.tzinfo is not None:
raise InvalidArgument(f"min_value={min_value!r} must not have tzinfo")
if max_value.tzinfo is not None:
raise InvalidArgument(f"max_value={max_value!r} must not have tzinfo")
check_valid_interval(min_value, max_value, "min_value", "max_value")
return TimeStrategy(min_value, max_value, timezones)
def indexes(
elements=None, # type: st.SearchStrategy[Ex]
dtype=None, # type: Any
min_size=0, # type: int
max_size=None, # type: int
unique=True, # type: bool
):
"""Provides a strategy for producing a :class:`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.
"""
check_valid_size(min_size, "min_size")
check_valid_size(max_size, "max_size")
check_valid_interval(min_size, max_size, "min_size", "max_size")
check_type(bool, unique, "unique")
elements, dtype = elements_and_dtype(elements, dtype)
if max_size is None:
max_size = min_size + DEFAULT_MAX_SIZE
return ValueIndexStrategy(elements, dtype, min_size, max_size, unique)
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 functions(draw,
name=None
min_argc=None, # int
max_argc=None, # int
manual_argument_bindings=None, # {} dict
manual_keyword_bindings=None, # {} dict
body=_phony_callable,
decorators=None, # [] list
kwarginit=hs.nothing(),
):
"""DOCUMENT ME!!!"""
# Replicates check_valid_sizes logic but with correct variable names
check_valid_size(min_argc, "min_argc")
check_valid_size(max_argc, "max_argc")
check_valid_interval(min_argc, max_argc, "min_argc", "max_argc")
min_argc = None if min_argc is None else ceil(min_argc)
max_argc = None if max_argc is None else floor(max_argc)
check_strategy(kwarginit, name="kwarginit")
if decorators is not None:
check_type(list, decorators, "decorators")
for index, d in enumerate(decorators):
_check_callable(d, name="iteration %r in 'decorators'" % (index))
_check_callable(body, name="body")
#if not hasattr(binding_regex, 'pattern'):
# # this has to be done later anyway inside the binding generator,
def datetimes(
min_value: dt.datetime = dt.datetime.min,
max_value: dt.datetime = dt.datetime.max,
*,
timezones: SearchStrategy[Optional[dt.tzinfo]] = none()
) -> SearchStrategy[dt.datetime]:
"""datetimes(min_value=datetime.datetime.min, max_value=datetime.datetime.max, *, timezones=none())
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
:class:`~python:datetime.tzinfo` objects (or None,
which is valid for naive datetimes). A value drawn from this strategy
will be added to a naive datetime, and the resulting tz-aware datetime
returned.
.. note::
tz-aware datetimes from this strategy may be ambiguous or non-existent
due to daylight savings, leap seconds, timezone and calendar
adjustments, etc. This is intentional, as malformed timestamps are a
common source of bugs.
:py:func:`hypothesis.extra.pytz.timezones` requires the :pypi:`pytz`
package, but provides all timezones in the Olsen database.
:py:func:`hypothesis.extra.dateutil.timezones` requires the
:pypi:`python-dateutil` package, and similarly provides all timezones
there. If you want to allow naive datetimes, combine strategies
like ``none() | timezones()``.
Alternatively, you can create a list of the timezones you wish to allow
(e.g. from the standard library, :pypi:`dateutil <python-dateutil>`,
or :pypi:`pytz`) and use :py:func:`sampled_from`.
Examples from this strategy shrink towards midnight on January 1st 2000,
local time.
"""
# Why must bounds be naive? In principle, we could also write a strategy
# that took aware bounds, but the API and validation is much harder.
# If you want to generate datetimes between two particular moments in
# time I suggest (a) just filtering out-of-bounds values; (b) if bounds
# are very close, draw a value and subtract its UTC offset, handling
# overflows and nonexistent times; or (c) do something customised to
# handle datetimes in e.g. a four-microsecond span which is not
# representable in UTC. Handling (d), all of the above, leads to a much
# more complex API for all users and a useful feature for very few.
check_type(dt.datetime, min_value, "min_value")
check_type(dt.datetime, max_value, "max_value")
if min_value.tzinfo is not None:
raise InvalidArgument("min_value=%r must not have tzinfo" % (min_value,))
if max_value.tzinfo is not None:
raise InvalidArgument("max_value=%r must not have tzinfo" % (max_value,))
check_valid_interval(min_value, max_value, "min_value", "max_value")
if not isinstance(timezones, SearchStrategy):
raise InvalidArgument(
"timezones=%r must be a SearchStrategy that can provide tzinfo "
"for datetimes (either None or dt.tzinfo objects)" % (timezones,)
)
return DatetimeStrategy(min_value, max_value, timezones)
