fix(asc): address PR review feedback on timestamps_format

Reviewer feedback received (zariiii9003):

1. Use Literal type hint for timestamps_format parameter
   - Changed: timestamps_format: str = "absolute"
   - To:      timestamps_format: Literal["absolute", "relative"] = "absolute"
   - Added Literal to typing imports

2. Simplify log_event timestamp computation
   - Moved monotonic clamp out of if/else blocks:
     timestamp = max(timestamp, self.last_timestamp)
   - Each branch now contains only simple arithmetic:
     absolute: written_timestamp = timestamp - self.started
     relative: written_timestamp = timestamp - self.last_timestamp

3. Use relative_timestamp=False in roundtrip tests
   - Updated test_write_relative_timestamp_roundtrip and
     test_write_absolute_timestamps_are_offsets_from_start to use
     relative_timestamp=False so assertions verify original message
     timestamps are recovered (100.0, 100.3, 101.0) rather than
     file-stored offsets (0.0, 0.3, 1.0)

Additional issues found and fixed during review:

4. Removed outdated TODO comment in ASCReader
   - Removed: "TODO - what is this used for? The ASC Writer only prints
     absolute" — no longer accurate since ASCWriter now supports both
     "absolute" and "relative" formats

5. Lowered assertAlmostEqual precision from places=5 to places=3
   - The datetime triggerblock roundtrip (fromtimestamp -> strftime ->
     strptime -> timestamp) only preserves millisecond precision due to
     the ".NNN" format. places=5 (5 microseconds) is stricter than what
     the format can guarantee; places=3 (0.5 ms) correctly reflects the
     actual precision limit. Verified empirically: sub-millisecond
     timestamps incur ~0.456 ms error which passes places=3 but fails
     places=5.

6. Updated docstrings for both modified roundtrip tests to accurately
   describe the new assertion semantics (original timestamp recovery)

Author: Ju-Daeng-E

can/io/asc.py

@@ -10,7 +10,7 @@
 import re
 from collections.abc import Generator
 from datetime import datetime
-from typing import Any, Final, TextIO
+from typing import Any, Final, Literal, TextIO
 
 from ..message import Message
 from ..typechecking import StringPathLike
@@ -66,7 +66,6 @@ def __init__(
         self.relative_timestamp = relative_timestamp
         self.date: str | None = None
         self.start_time = 0.0
-        # TODO - what is this used for? The ASC Writer only prints `absolute`
         self.timestamps_format: str | None = None
         self.internal_events_logged = False
 
@@ -358,7 +357,7 @@ def __init__(
         self,
         file: StringPathLike | TextIO,
         channel: int = 1,
-        timestamps_format: str = "absolute",
+        timestamps_format: Literal["absolute", "relative"] = "absolute",
         **kwargs: Any,
     ) -> None:
         """
@@ -442,19 +441,14 @@ def log_event(self, message: str, timestamp: float | None = None) -> None:
         # Use last known timestamp if unknown
         if timestamp is None:
             timestamp = self.last_timestamp
+        timestamp = max(timestamp, self.last_timestamp)
         # Compute written timestamp based on configured format
         if self.timestamps_format == "absolute":
             # offsets from the start of measurement
-            written_timestamp = (
-                timestamp - self.started if timestamp >= self.started else timestamp
-            )
+            written_timestamp = timestamp - self.started
         else:
             # deltas from the preceding event
-            written_timestamp = (
-                timestamp - self.last_timestamp
-                if timestamp >= self.last_timestamp
-                else 0.0
-            )
+            written_timestamp = timestamp - self.last_timestamp
         # Track last timestamp so the next event can compute its delta
         self.last_timestamp = timestamp
         line = self.FORMAT_EVENT.format(timestamp=written_timestamp, message=message)

test/logformats_test.py

@@ -704,7 +704,7 @@ def test_write_timestamps_format_invalid(self):
             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."""
+        """Messages written with relative format round-trip to their original timestamps."""
         msgs = [
             can.Message(timestamp=100.0, arbitration_id=0x1, data=b"\x01"),
             can.Message(timestamp=100.5, arbitration_id=0x2, data=b"\x02"),
@@ -714,13 +714,12 @@ def test_write_relative_timestamp_roundtrip(self):
             for m in msgs:
                 writer.on_message_received(m)
 
-        with can.ASCReader(self.test_file_name, relative_timestamp=True) as reader:
+        with can.ASCReader(self.test_file_name, relative_timestamp=False) as reader:
             result = list(reader)
 
         self.assertEqual(len(result), len(msgs))
-        # Timestamps in file are per-event deltas; reader reads them as-is
-        self.assertAlmostEqual(result[0].timestamp, 0.0, places=5)
-        self.assertAlmostEqual(result[1].timestamp, 0.5, places=5)
+        self.assertAlmostEqual(result[0].timestamp, 100.0, places=3)
+        self.assertAlmostEqual(result[1].timestamp, 100.5, places=3)
 
     def test_write_relative_timestamps_are_per_event_deltas(self):
         """With timestamps_format='relative', each written timestamp is a delta from the
@@ -747,8 +746,8 @@ def test_write_relative_timestamps_are_per_event_deltas(self):
         self.assertAlmostEqual(result[2].timestamp, 0.7, places=5)
 
     def test_write_absolute_timestamps_are_offsets_from_start(self):
-        """With timestamps_format='absolute' (default), each written timestamp is an
-        offset from the measurement start, not a per-event delta."""
+        """With timestamps_format='absolute' (default), messages round-trip to their
+        original timestamps when read back with relative_timestamp=False."""
         msgs = [
             can.Message(timestamp=100.0, arbitration_id=0x1, data=b"\x01"),
             can.Message(timestamp=100.3, arbitration_id=0x2, data=b"\x02"),
@@ -759,14 +758,14 @@ def test_write_absolute_timestamps_are_offsets_from_start(self):
             for m in msgs:
                 writer.on_message_received(m)
 
-        with can.ASCReader(self.test_file_name, relative_timestamp=True) as reader:
+        with can.ASCReader(self.test_file_name, relative_timestamp=False) as reader:
             result = list(reader)
 
         self.assertEqual(len(result), len(msgs))
-        # All timestamps are offsets from the measurement start (100.0):
-        self.assertAlmostEqual(result[0].timestamp, 0.0, places=5)
-        self.assertAlmostEqual(result[1].timestamp, 0.3, places=5)
-        self.assertAlmostEqual(result[2].timestamp, 1.0, places=5)
+        # Timestamps are recovered from the triggerblock start time + file offset:
+        self.assertAlmostEqual(result[0].timestamp, 100.0, places=3)
+        self.assertAlmostEqual(result[1].timestamp, 100.3, places=3)
+        self.assertAlmostEqual(result[2].timestamp, 101.0, places=3)
 
     @parameterized.expand(
         [