Date and Time Types¶
IsDatetime ¶
IsDatetime(*, approx: datetime | None = None, delta: timedelta | int | float | None = None, gt: datetime | None = None, lt: datetime | None = None, ge: datetime | None = None, le: datetime | None = None, unix_number: bool = False, iso_string: bool = False, format_string: str | None = None, enforce_tz: bool = True)
Check if the value is a datetime, and matches the given conditions.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
approx |
datetime | None
|
A value to approximately compare to. |
None
|
delta |
timedelta | int | float | None
|
The allowable different when comparing to the value to |
None
|
gt |
datetime | None
|
Value which the compared value should be greater than (after). |
None
|
lt |
datetime | None
|
Value which the compared value should be less than (before). |
None
|
ge |
datetime | None
|
Value which the compared value should be greater than (after) or equal to. |
None
|
le |
datetime | None
|
Value which the compared value should be less than (before) or equal to. |
None
|
unix_number |
bool
|
whether to allow unix timestamp numbers in comparison |
False
|
iso_string |
bool
|
whether to allow iso formatted strings in comparison |
False
|
format_string |
str | None
|
if provided, |
None
|
enforce_tz |
bool
|
whether timezone should be enforced in comparison, see below for more details |
True
|
Examples of basic usage:
from datetime import datetime
from dirty_equals import IsDatetime
y2k = datetime(2000, 1, 1)
assert datetime(2000, 1, 1) == IsDatetime(approx=y2k)
# Note: this requires the system timezone to be UTC
assert 946684800.123 == IsDatetime(approx=y2k, unix_number=True)
assert datetime(2000, 1, 1, 0, 0, 9) == IsDatetime(approx=y2k, delta=10)
assert '2000-01-01T00:00' == IsDatetime(approx=y2k, iso_string=True)
assert datetime(2000, 1, 2) == IsDatetime(gt=y2k)
assert datetime(1999, 1, 2) != IsDatetime(gt=y2k)
Timezones¶
Timezones are hard, anyone who claims otherwise is either a genius, a liar, or an idiot.
IsDatetime
and its subtypes (e.g. IsNow
) can be used in two modes,
based on the enforce_tz
parameter:
enforce_tz=True
(the default):- if the datetime wrapped by
IsDatetime
is timezone naive, the compared value must also be timezone naive. - if the datetime wrapped by
IsDatetime
has a timezone, the compared value must have a timezone with the same offset.
- if the datetime wrapped by
enforce_tz=False
:- if the datetime wrapped by
IsDatetime
is timezone naive, the compared value can either be naive or have a timezone all that matters is the datetime values match. - if the datetime wrapped by
IsDatetime
has a timezone, the compared value needs to represent the same point in time - either way it must have a timezone.
- if the datetime wrapped by
Example
from datetime import datetime
from zoneinfo import ZoneInfo
from dirty_equals import IsDatetime
tz_london = ZoneInfo('Europe/London')
new_year_london = datetime(2000, 1, 1, tzinfo=tz_london)
tz_nyc = ZoneInfo('America/New_York')
new_year_eve_nyc = datetime(1999, 12, 31, 19, 0, 0, tzinfo=tz_nyc)
assert new_year_eve_nyc == IsDatetime(approx=new_year_london, enforce_tz=False)
assert new_year_eve_nyc != IsDatetime(approx=new_year_london, enforce_tz=True)
new_year_naive = datetime(2000, 1, 1)
assert new_year_naive != IsDatetime(approx=new_year_london, enforce_tz=False)
assert new_year_naive != IsDatetime(approx=new_year_eve_nyc, enforce_tz=False)
assert new_year_london == IsDatetime(approx=new_year_naive, enforce_tz=False)
assert new_year_eve_nyc != IsDatetime(approx=new_year_naive, enforce_tz=False)
IsNow ¶
IsNow(*, delta: timedelta | int | float = 2, unix_number: bool = False, iso_string: bool = False, format_string: str | None = None, enforce_tz: bool = True, tz: str | tzinfo | None = None)
Bases: IsDatetime
Check if a datetime is close to now, this is similar to IsDatetime(approx=datetime.now())
,
but slightly more powerful.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
delta |
timedelta | int | float
|
The allowable different when comparing to the value to now, if omitted 2 seconds is used,
ints and floats are assumed to represent seconds and converted to |
2
|
unix_number |
bool
|
whether to allow unix timestamp numbers in comparison |
False
|
iso_string |
bool
|
whether to allow iso formatted strings in comparison |
False
|
format_string |
str | None
|
if provided, |
None
|
enforce_tz |
bool
|
whether timezone should be enforced in comparison, see below for more details |
True
|
tz |
str | tzinfo | None
|
either a |
None
|
from datetime import datetime, timezone
from dirty_equals import IsNow
now = datetime.now()
assert now == IsNow
assert now.timestamp() == IsNow(unix_number=True)
assert now.timestamp() != IsNow
assert now.isoformat() == IsNow(iso_string=True)
assert now.isoformat() != IsNow
utc_now = datetime.utcnow().replace(tzinfo=timezone.utc)
assert utc_now == IsNow(tz=timezone.utc)
IsDate ¶
IsDate(*, approx: date | None = None, delta: timedelta | int | float | None = None, gt: date | None = None, lt: date | None = None, ge: date | None = None, le: date | None = None, iso_string: bool = False, format_string: str | None = None)
Check if the value is a date, and matches the given conditions.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
approx |
date | None
|
A value to approximately compare to. |
None
|
delta |
timedelta | int | float | None
|
The allowable different when comparing to the value to now, if omitted 2 seconds is used,
ints and floats are assumed to represent seconds and converted to |
None
|
gt |
date | None
|
Value which the compared value should be greater than (after). |
None
|
lt |
date | None
|
Value which the compared value should be less than (before). |
None
|
ge |
date | None
|
Value which the compared value should be greater than (after) or equal to. |
None
|
le |
date | None
|
Value which the compared value should be less than (before) or equal to. |
None
|
iso_string |
bool
|
whether to allow iso formatted strings in comparison |
False
|
format_string |
str | None
|
if provided, |
None
|
Examples of basic usage:
from datetime import date
from dirty_equals import IsDate
y2k = date(2000, 1, 1)
assert date(2000, 1, 1) == IsDate(approx=y2k)
assert '2000-01-01' == IsDate(approx=y2k, iso_string=True)
assert date(2000, 1, 2) == IsDate(gt=y2k)
assert date(1999, 1, 2) != IsDate(gt=y2k)
IsToday ¶
Bases: IsDate
Check if a date is today, this is similar to IsDate(approx=date.today())
, but slightly more powerful.
Parameters:
from datetime import date, timedelta
from dirty_equals import IsToday
today = date.today()
assert today == IsToday
assert today.isoformat() == IsToday(iso_string=True)
assert today.isoformat() != IsToday
assert today + timedelta(days=1) != IsToday
assert today.strftime('%Y/%m/%d') == IsToday(format_string='%Y/%m/%d')
assert today.strftime('%Y/%m/%d') != IsToday()