feat(asc): add timestamps_format parameter to ASCWriter

Allow callers to choose between 'absolute' (default, existing behaviour)
and 'relative' when creating an ASC log file. The value is written into
the 'base hex  timestamps ...' header line so that other tools
(CANalyzer, CANoe, etc.) can interpret the file correctly.

Closes #2022

Author: Ju-Daeng-E

can/io/asc.py

@@ -10,7 +10,7 @@
 import re
 from collections.abc import Generator
 from datetime import datetime, timezone, tzinfo
-from typing import Any, Final, TextIO
+from typing import Any, Final, Literal, TextIO
 
 from ..message import Message
 from ..typechecking import StringPathLike
@@ -372,6 +372,7 @@ def __init__(
         file: StringPathLike | TextIO,
         channel: int = 1,
         tz: tzinfo | None = _LOCAL_TZ,
+        timestamps_format: Literal["absolute", "relative"] = "absolute",
         **kwargs: Any,
     ) -> None:
         """
@@ -384,7 +385,22 @@ def __init__(
             have a channel set. Default is 1.
         :param tz:
             Timezone for timestamps in the log file. Defaults to local timezone.
+        :param timestamps_format:
+            the format of timestamps in the header.
+            Use ``"absolute"`` (default) so that readers can recover
+            the original wall-clock timestamps by combining the
+            per-message offset with the trigger-block start time.
+            Use ``"relative"`` when only the elapsed time from the
+            start of the recording matters and no absolute time
+            recovery is needed.
+        :raises ValueError: if *timestamps_format* is not ``"absolute"`` or
+                            ``"relative"``
         """
+        if timestamps_format not in ("absolute", "relative"):
+            raise ValueError(
+                f"timestamps_format must be 'absolute' or 'relative', "
+                f"got {timestamps_format!r}"
+            )
         if kwargs.get("append", False):
             raise ValueError(
                 f"{self.__class__.__name__} is currently not equipped to "
@@ -394,11 +410,12 @@ def __init__(
 
         self._timezone = tz
         self.channel = channel
+        self.timestamps_format = timestamps_format
 
         # write start of file header
         start_time = self._format_header_datetime(datetime.now(tz=self._timezone))
         self.file.write(f"date {start_time}\n")
-        self.file.write("base hex  timestamps absolute\n")
+        self.file.write(f"base hex  timestamps {self.timestamps_format}\n")
         self.file.write("internal events logged\n")
 
         # the last part is written with the timestamp of the first message

test/logformats_test.py

@@ -687,6 +687,49 @@ def test_write(self):
 
         self.assertEqual(expected_file.read_text(), actual_file.read_text())
 
+    def test_write_timestamps_format_default_is_absolute(self):
+        """ASCWriter should write 'timestamps absolute' in the header by default."""
+        with can.ASCWriter(self.test_file_name) as writer:
+            pass
+
+        content = Path(self.test_file_name).read_text()
+        self.assertIn("timestamps absolute", content)
+
+    def test_write_timestamps_format_relative(self):
+        """ASCWriter should write 'timestamps relative' when requested."""
+        with can.ASCWriter(self.test_file_name, timestamps_format="relative") as writer:
+            pass
+
+        content = Path(self.test_file_name).read_text()
+        self.assertIn("timestamps relative", content)
+        self.assertNotIn("timestamps absolute", content)
+
+    def test_write_timestamps_format_invalid(self):
+        """ASCWriter should raise ValueError for an unsupported timestamps_format."""
+        with self.assertRaises(ValueError):
+            can.ASCWriter(self.test_file_name, timestamps_format="unix")
+
+    def test_write_relative_timestamp_roundtrip(self):
+        """Messages written with relative format round-trip with relative timestamps."""
+        msgs = [
+            can.Message(timestamp=100.0, arbitration_id=0x1, data=b"\x01"),
+            can.Message(timestamp=100.5, arbitration_id=0x2, data=b"\x02"),
+        ]
+
+        with can.ASCWriter(
+            self.test_file_name, timestamps_format="relative"
+        ) as writer:
+            for m in msgs:
+                writer.on_message_received(m)
+
+        with can.ASCReader(self.test_file_name, relative_timestamp=True) as reader:
+            result = list(reader)
+
+        self.assertEqual(len(result), len(msgs))
+        # With relative_timestamp=True timestamps are offsets from the first message
+        self.assertAlmostEqual(result[0].timestamp, 0.0, places=5)
+        self.assertAlmostEqual(result[1].timestamp, 0.5, places=5)
+
     @parameterized.expand(
         [
             (