Message.mesage_datetime property

dramatiq/message.py

@@ -20,6 +20,7 @@
 import dataclasses
 import time
 import uuid
+from datetime import datetime, timezone
 from typing import Any, Generic, Optional, TypeVar
 
 from .broker import get_broker
@@ -189,3 +190,13 @@ def _fields(self) -> tuple[str, ...]:
 
     def _replace(self, **changes) -> Message[R]:
         return dataclasses.replace(self, **changes)
+
+    @property
+    def message_datetime(self) -> datetime:
+        """Read ``message_timestamp`` as a UTC-aware datetime.
+
+        Datetime precision is limited by the representation of ``Message.message_timestamp``, which is an
+        integer storing milliseconds.
+        """
+        unix_seconds, ms = divmod(self.message_timestamp, 1000)
+        return datetime.fromtimestamp(unix_seconds, tz=timezone.utc).replace(microsecond=ms * 1000)

tests/test_messages.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from datetime import datetime, timedelta, timezone
+
 import dramatiq
 
 
@@ -47,3 +49,21 @@ def actor(arg):
 
     assert repr(message) in repr(message_proxy), "Expecting MessageProxy repr to contain Message repr"
     assert str(message) == str(message_proxy), "Expecting identical __str__ of MessageProxy and Message"
+
+
+def test_message_datetime(stub_broker):
+    """Test reading message time as datetime."""
+
+    @dramatiq.actor
+    def actor(arg):
+        return arg
+
+    message = actor.send("input")
+    after = datetime.now(timezone.utc)
+
+    assert message.message_datetime.tzinfo is timezone.utc
+    assert message.message_datetime < after
+    assert message.message_datetime > after - timedelta(seconds=1)
+
+    # no rounding problems here because message_timestamp is an int
+    assert message.message_datetime.timestamp() == message.message_timestamp / 1000