comments: add Comment.timestamp

Author: scanny

features/cmt-props.feature

@@ -19,7 +19,6 @@ Feature: Get comment properties
      Then comment.initials is the initials of the comment author
 
 
-  @wip
   Scenario: Comment.timestamp
     Given a Comment object
      Then comment.timestamp is the date and time the comment was authored

src/docx/comments.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import datetime as dt
 from typing import TYPE_CHECKING, Iterator
 
 from docx.blkcntnr import BlockItemContainer
@@ -71,3 +72,11 @@ def initials(self) -> str | None:
         any existing initials from the XML.
         """
         return self._comment_elm.initials
+
+    @property
+    def timestamp(self) -> dt.datetime | None:
+        """The date and time this comment was authored.
+
+        This attribute is optional in the XML, returns |None| if not set.
+        """
+        return self._comment_elm.date

src/docx/oxml/comments.py

@@ -2,7 +2,9 @@
 
 from __future__ import annotations
 
-from docx.oxml.simpletypes import ST_DecimalNumber, ST_String
+import datetime as dt
+
+from docx.oxml.simpletypes import ST_DateTime, ST_DecimalNumber, ST_String
 from docx.oxml.xmlchemy import BaseOxmlElement, OptionalAttribute, RequiredAttribute, ZeroOrMore
 
 
@@ -39,3 +41,6 @@ class CT_Comment(BaseOxmlElement):
     initials: str | None = OptionalAttribute(  # pyright: ignore[reportAssignmentType]
         "w:initials", ST_String
     )
+    date: dt.datetime | None = OptionalAttribute(  # pyright: ignore[reportAssignmentType]
+        "w:date", ST_DateTime
+    )

src/docx/oxml/simpletypes.py

@@ -9,6 +9,7 @@
 
 from __future__ import annotations
 
+import datetime as dt
 from typing import TYPE_CHECKING, Any, Tuple
 
 from docx.exceptions import InvalidXmlError
@@ -213,6 +214,58 @@ def validate(cls, value: Any) -> None:
         cls.validate_int_in_range(value, -27273042329600, 27273042316900)
 
 
+class ST_DateTime(BaseSimpleType):
+    @classmethod
+    def convert_from_xml(cls, str_value: str) -> dt.datetime:
+        """Convert an xsd:dateTime string to a datetime object."""
+
+        def parse_xsd_datetime(dt_str: str) -> dt.datetime:
+            # -- handle trailing 'Z' (Zulu/UTC), common in Word files --
+            if dt_str.endswith("Z"):
+                try:
+                    # -- optional fractional seconds case --
+                    return dt.datetime.strptime(dt_str, "%Y-%m-%dT%H:%M:%S.%fZ").replace(
+                        tzinfo=dt.timezone.utc
+                    )
+                except ValueError:
+                    return dt.datetime.strptime(dt_str, "%Y-%m-%dT%H:%M:%SZ").replace(
+                        tzinfo=dt.timezone.utc
+                    )
+
+            # -- handles explicit offsets like +00:00, -05:00, or naive datetimes --
+            try:
+                return dt.datetime.fromisoformat(dt_str)
+            except ValueError:
+                # -- fall-back to parsing as naive datetime (with or without fractional seconds) --
+                try:
+                    return dt.datetime.strptime(dt_str, "%Y-%m-%dT%H:%M:%S.%f")
+                except ValueError:
+                    return dt.datetime.strptime(dt_str, "%Y-%m-%dT%H:%M:%S")
+
+        try:
+            # -- parse anything reasonable, but never raise, just use default epoch time --
+            return parse_xsd_datetime(str_value)
+        except Exception:
+            return dt.datetime(1970, 1, 1, tzinfo=dt.timezone.utc)
+
+    @classmethod
+    def convert_to_xml(cls, value: dt.datetime) -> str:
+        # -- convert naive datetime to timezon-aware assuming local timezone --
+        if value.tzinfo is None:
+            value = value.astimezone()
+
+        # -- convert to UTC if not already --
+        value = value.astimezone(dt.timezone.utc)
+
+        # -- format with 'Z' suffix for UTC --
+        return value.strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    @classmethod
+    def validate(cls, value: Any) -> None:
+        if not isinstance(value, dt.datetime):
+            raise TypeError("only a datetime.datetime object may be assigned, got '%s'" % value)
+
+
 class ST_DecimalNumber(XsdInt):
     pass
 

tests/test_comments.py

@@ -4,6 +4,7 @@
 
 from __future__ import annotations
 
+import datetime as dt
 from typing import cast
 
 import pytest
@@ -113,6 +114,15 @@ def it_knows_the_initials_of_its_author(self, comments_part_: Mock):
 
         assert comment.initials == "SJC"
 
+    def it_knows_the_date_and_time_it_was_authored(self, comments_part_: Mock):
+        comment_elm = cast(
+            CT_Comment,
+            element("w:comment{w:id=42,w:date=2023-10-01T12:34:56Z}"),
+        )
+        comment = Comment(comment_elm, comments_part_)
+
+        assert comment.timestamp == dt.datetime(2023, 10, 1, 12, 34, 56, tzinfo=dt.timezone.utc)
+
     # -- fixtures --------------------------------------------------------------------------------
 
     @pytest.fixture