Add assert_datetime_now

Author: srittau

CHANGELOG.md

@@ -7,6 +7,7 @@ python-asserts adheres to [semantic versioning](https://semver.org/).
 ### Added
 
 - Add support for Python 3.13 and 3.14.
+- Add `assert_datetime_now()`.
 
 ### Changed
 

asserts/__init__.py

@@ -819,6 +819,55 @@ def assert_has_attr(obj, attribute, msg_fmt="{msg}"):
 _EPSILON_SECONDS = 5
 
 
+def assert_datetime_now(
+    actual: datetime | None,
+    msg_fmt: str = "{msg}",
+    *,
+    check_utc: bool = False,
+) -> None:
+    """Fail if a timezone-aware datetime object is not close to the current time.
+
+    >>> assert_datetime_now(datetime.now(timezone.utc))
+    >>> assert_datetime_now(datetime(1900, 1, 1, 12, 0, 0, tzinfo=timezone.utc))
+    Traceback (most recent call last):
+        ...
+    AssertionError: datetime.datetime(1900, 1, 1, 12, 0, tzinfo=datetime.timezone.utc) is not close to current date/time
+
+    The datetime's 'tzinfo' is asserted to be UTC if the optional parameter
+    'check_utc' is set to True:
+
+    >>> import zoneinfo
+    >>> assert_datetime_now(datetime.now(timezone.utc), check_utc=True)
+    >>> assert_datetime_now(datetime(1900, 1, 1, 12, 0, 0, tzinfo=zoneinfo.ZoneInfo('Europe/Berlin')), check_utc=True)
+    Traceback (most recent call last):
+        ...
+    AssertionError: expected tzinfo of datetime.datetime(1900, 1, 1, 12, 0, tzinfo=zoneinfo.ZoneInfo(key='Europe/Berlin')) to be UTC
+
+    The following msg_fmt arguments are supported:
+    * msg - the default error message
+    * actual - datetime object to check
+    * now - current datetime that was tested against
+    """
+
+    now = datetime.now(timezone.utc)
+
+    if actual is None:
+        msg = "None is not a valid date/time"
+        fail(msg_fmt.format(msg=msg, actual=actual, now=now))
+    if actual.tzinfo is None:
+        msg = f"expected timezone-aware datetime object, got {actual!r}"
+        fail(msg_fmt.format(msg=msg, actual=actual, now=now))
+    if check_utc and actual.tzinfo != timezone.utc:
+        msg = f"expected tzinfo of {actual!r} to be UTC"
+        fail(msg_fmt.format(msg=msg, actual=actual, now=now))
+
+    lower_bound = now - timedelta(seconds=_EPSILON_SECONDS)
+    upper_bound = now + timedelta(seconds=_EPSILON_SECONDS)
+    if not lower_bound <= actual <= upper_bound:
+        msg = f"{actual!r} is not close to current date/time"
+        fail(msg_fmt.format(msg=msg, actual=actual, now=now))
+
+
 def assert_datetime_about_now(
     actual: datetime | None, msg_fmt: str = "{msg}"
 ) -> None:

asserts/__init__.pyi

@@ -133,6 +133,12 @@ def assert_count_equal(
 def assert_has_attr(
     obj: object, attribute: str, msg_fmt: str = ...
 ) -> None: ...
+def assert_datetime_now(
+    actual: datetime.datetime | None,
+    msg_fmt: str = "{msg}",
+    *,
+    check_utc: bool = False,
+) -> None: ...
 def assert_datetime_about_now(
     actual: datetime.datetime | None, msg_fmt: str = ...
 ) -> None: ...

test_asserts.py

@@ -2,6 +2,7 @@
 
 import re
 import sys
+import zoneinfo
 from collections import OrderedDict
 from datetime import datetime, timedelta, timezone
 from json import JSONDecodeError
@@ -19,6 +20,7 @@
     assert_count_equal,
     assert_datetime_about_now,
     assert_datetime_about_now_utc,
+    assert_datetime_now,
     assert_dict_equal,
     assert_dict_superset,
     assert_equal,
@@ -879,6 +881,72 @@ def test_assert_has_attr__does_not_have_attribute__custom_message(self):
         with _assert_raises_assertion(expected):
             assert_has_attr(d, "foo", msg_fmt="{msg};{obj!r};{attribute}")
 
+    # assert_datetime_now()
+
+    def test_assert_datetime_now__naive_dt(self):
+        expected_message = "^expected timezone-aware datetime object, got "
+        with assert_raises_regex(AssertionError, expected_message):
+            assert_datetime_now(datetime.now())
+
+    def test_assert_datetime_now__close(self):
+        assert_datetime_now(datetime.now(timezone.utc))
+        assert_datetime_now(datetime.now(zoneinfo.ZoneInfo("Europe/Berlin")))
+
+    def test_assert_datetime_now__none__default_message(self):
+        expected_message = r"^None is not a valid date/time$"
+        with assert_raises_regex(AssertionError, expected_message):
+            assert_datetime_now(None)
+
+    def test_assert_datetime_now__none__custom_message(self):
+        dt = datetime.now().date().isoformat()
+        expected = "None is not a valid date/time;None;{}".format(dt)
+        with _assert_raises_assertion(expected):
+            assert_datetime_now(
+                None, msg_fmt="{msg};{actual!r};{now:%Y-%m-%d}"
+            )
+
+    def test_assert_datetime_now__too_low(self):
+        then = datetime.now(timezone.utc) - timedelta(minutes=1)
+        with assert_raises(AssertionError):
+            assert_datetime_now(then)
+
+    def test_assert_datetime_now__too_high(self):
+        then = datetime.now(timezone.utc) + timedelta(minutes=1)
+        with assert_raises(AssertionError):
+            assert_datetime_now(then)
+
+    def test_assert_datetime_now__default_message(self):
+        then = datetime(1990, 4, 13, 12, 30, 15, tzinfo=timezone.utc)
+        expected_message = (
+            r"^datetime.datetime\(1990, 4, 13, 12, 30, 15, tzinfo=datetime.timezone.utc\) "
+            "is not close to current date/time$"
+        )
+        with assert_raises_regex(AssertionError, expected_message):
+            assert_datetime_now(then)
+
+    def test_assert_datetime_now__custom_message(self):
+        then = datetime(1990, 4, 13, 12, 30, 15, tzinfo=timezone.utc)
+        now = datetime.now().date().isoformat()
+        expected = (
+            "datetime.datetime(1990, 4, 13, 12, 30, 15, tzinfo=datetime.timezone.utc) "
+            f"is not close to current date/time;12:30;{now}"
+        )
+        with _assert_raises_assertion(expected):
+            assert_datetime_now(
+                then, msg_fmt="{msg};{actual:%H:%M};{now:%Y-%m-%d}"
+            )
+
+    def test_assert_datetime_now__check_utc(self):
+        assert_datetime_now(datetime.now(timezone.utc), check_utc=True)
+
+    def test_assert_datetime_now__check_utc_fail(self):
+        expected = r"^expected tzinfo of datetime.datetime\(.*\) to be UTC"
+        with assert_raises_regex(AssertionError, expected):
+            assert_datetime_now(
+                datetime.now(zoneinfo.ZoneInfo("Europe/Berlin")),
+                check_utc=True,
+            )
+
     # assert_datetime_about_now()
 
     def test_assert_datetime_about_now__aware_dt(self):