Update time handling in knob and MQT extractors for improved clarity and consistency

Author: jgray-19

omc3/knob_extractor.py

@@ -44,8 +44,8 @@
 - **time** *(str)*:
 
     At what time to extract the knobs. Accepts ISO-format (YYYY-MM-
-    DDThh:mm:ss), timestamp or 'now'. The default timezone for the ISO-
-    format is local time, but you can force e.g. UTC by adding +00:00.
+    DDThh:mm:ss) with timezone, timestamp or 'now'. Timezone must be
+    specified for ISO-format (e.g. +00:00 for UTC).
 
     default: ``now``
 
@@ -212,7 +212,7 @@ class Head:
 
 USAGE_EXAMPLES = """Usage Examples:
 
-python -m omc3.knob_extractor --knobs disp chroma --time 2022-05-04T14:00
+python -m omc3.knob_extractor --knobs disp chroma --time 2022-05-04T14:00+00:00
     extracts the chromaticity and dispersion knobs at 14h on May 4th 2022
 
 python -m omc3.knob_extractor --knobs disp chroma --time now _2h
@@ -241,9 +241,8 @@ def get_params():
             "type": str,
             "help": (
                 "At what time to extract the knobs. "
-                "Accepts ISO-format (YYYY-MM-DDThh:mm:ss), timestamp or 'now'. "
-                "The default timezone for the ISO-format is local time, "
-                "but you can force e.g. UTC by adding +00:00."
+                "Accepts ISO-format (YYYY-MM-DDThh:mm:ss) with timezone, timestamp or 'now'. "
+                "Timezone must be specified for ISO-format (e.g. +00:00 for UTC)."
             ),
             "default": "now",
         },

omc3/mqt_extractor.py

@@ -25,8 +25,8 @@
 - **time** *(str)*:
 
     At what time to extract the MQT knobs. Accepts ISO-format (YYYY-MM-
-    DDThh:mm:ss), timestamp or 'now'. The default timezone for the ISO-
-    format is local time, but you can force e.g. UTC by adding +00:00.
+    DDThh:mm:ss) with timezone, timestamp or 'now'. Timezone must be
+    specified for ISO-format (e.g. +00:00 for UTC).
 
     default: ``now``
 
@@ -81,7 +81,7 @@
 
 USAGE_EXAMPLES = """Usage Examples:
 
-python -m omc3.mqt_extractor --beam 1 --time 2022-05-04T14:00
+python -m omc3.mqt_extractor --beam 1 --time 2022-05-04T14:00+00:00
     extracts the MQT knobs for beam 1 at 14h on May 4th 2022
 
 python -m omc3.mqt_extractor --beam 2 --time now --timedelta _2h
@@ -102,9 +102,8 @@ def get_params():
             "type": str,
             "help": (
                 "At what time to extract the MQT knobs. "
-                "Accepts ISO-format (YYYY-MM-DDThh:mm:ss), timestamp or 'now'. "
-                "The default timezone for the ISO-format is local time, "
-                "but you can force e.g. UTC by adding +00:00."
+                "Accepts ISO-format (YYYY-MM-DDThh:mm:ss) with timezone, timestamp or 'now'. "
+                "Timezone must be specified for ISO-format (e.g. +00:00 for UTC)."
             ),
             "default": "now",
         },

tests/unit/test_nxcals_mqt_extraction.py

@@ -182,27 +182,31 @@ def test_parse_time_now():
     """Test that _parse_time correctly handles 'now'."""
     from datetime import datetime
 
-    result = mqt_extractor._parse_time("now")
+    from omc3.utils.time_tools import parse_time
+
+    result = parse_time("now")
     now = datetime.now(timezone.utc)
 
     # Should be very close to now (within 1 second)
     diff = abs((now - result).total_seconds())
-    assert diff < 1, f"_parse_time('now') should return current time, diff was {diff}s"
+    assert diff < 1, f"parse_time('now') should return current time, diff was {diff}s"
 
 
 def test_parse_time_with_timedelta():
     """Test that _parse_time correctly applies timedelta."""
     from datetime import datetime
 
+    from omc3.utils.time_tools import parse_time
+
     now_str = datetime.now(timezone.utc).isoformat()
 
     # Test positive timedelta
-    result_plus = mqt_extractor._parse_time(now_str, "1h")
-    result_base = mqt_extractor._parse_time(now_str)
+    result_plus = parse_time(now_str, "1h")
+    result_base = parse_time(now_str)
     diff_plus = (result_plus - result_base).total_seconds()
     assert abs(diff_plus - 3600) < 1, f"1h timedelta should add 3600s, got {diff_plus}s"
 
     # Test negative timedelta
-    result_minus = mqt_extractor._parse_time(now_str, "_2h")
+    result_minus = parse_time(now_str, "_2h")
     diff_minus = (result_minus - result_base).total_seconds()
     assert abs(diff_minus + 7200) < 1, f"_2h timedelta should subtract 7200s, got {diff_minus}s"