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
)

Bases: IsNumeric[datetime]

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 `approx`, if omitted 2 seconds is used, ints and floats are assumed to represent seconds and converted to `timedelta`s.	`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, `format_string` is used with `datetime.strptime` to parse strings	`None`
`enforce_tz`	`bool`	whether timezone should be enforced in comparison, see below for more details	`True`

Examples of basic usage:

IsDatetime

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

Example

IsDatetime & timezones

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 `timedelta`s.	`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, `format_string` is used with `datetime.strptime` to parse strings	`None`
`enforce_tz`	`bool`	whether timezone should be enforced in comparison, see below for more details	`True`
`tz`	`str \| tzinfo \| None`	either a `ZoneInfo`, a `datetime.timezone` or a string which will be passed to `ZoneInfo`, to get a timezone, if provided now will be converted to this timezone.	`None`

IsNow

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
)

Bases: IsNumeric[date]

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 `timedelta`s.	`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, `format_string` is used with `datetime.strptime` to parse strings	`None`

Examples of basic usage:

IsDate

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 ¶

IsToday(
    *,
    iso_string: bool = False,
    format_string: str | None = None
)

Bases: IsDate

Check if a date is today, this is similar to IsDate(approx=date.today()), but slightly more powerful.

Parameters:

Name	Type	Description	Default
`iso_string`	`bool`	whether to allow iso formatted strings in comparison	`False`
`format_string`	`str \| None`	if provided, `format_string` is used with `datetime.strptime` to parse strings	`None`

IsToday

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