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 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 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)