From 2ec4ba8186e3bf98fd5b8e7f2f8568e275aacf90 Mon Sep 17 00:00:00 2001 From: sakarpaisen Date: Thu, 22 Oct 2026 16:07:04 +0300 Subject: [PATCH] Report the UTC weekday in the timestamp converter convert_timestamp returns weekday_utc, an English weekday name indexed from a fixed Monday-to-Sunday tuple using the converted UTC date, so neither the input's offset nor the machine's locale changes it. Existing values and error handling are unchanged; millisecond support (#6) has not landed, so there is no extra mode to cover. Tests use the issue's epoch and midnight-crossing examples plus a negative timestamp. --- docs/tool-guide.md | 8 ++++++-- src/mcp_tools_lab/tools/timestamps.py | 11 ++++++++++- tests/test_timestamps.py | 20 ++++++++++++++++++++ 3 files changed, 36 insertions(+), 3 deletions(-) diff --git a/docs/tool-guide.md b/docs/tool-guide.md index ed54a58..59684f4 100644 --- a/docs/tool-guide.md +++ b/docs/tool-guide.md @@ -58,8 +58,12 @@ other whitespace is significant. Empty input is supported. `value` is a string. `to_iso` accepts Unix **seconds**, including fractions and negative values. `to_unix` accepts an ISO 8601 date/time with `Z` or a UTC offset. -Both return `unix_seconds` and `iso_utc`. For example, -`convert_timestamp("1970-01-01T05:30:00+05:30", "to_unix")` returns zero seconds. +Both return `unix_seconds`, `iso_utc`, and `weekday_utc`, the English weekday name +of the converted UTC date. For example, +`convert_timestamp("1970-01-01T05:30:00+05:30", "to_unix")` returns zero seconds, +and `convert_timestamp("1970-01-02T00:30:00+01:00", "to_unix")` is Thursday in UTC +even though the input's local date is Friday. A fixed Monday-to-Sunday list is used, +so the name does not depend on the machine's locale. Timezone-less dates are rejected so results do not depend on the machine's timezone. Python datetime's year range (1–9999) and microsecond precision apply; finer fractional seconds may be rounded. Invalid, infinite, or out-of-range values raise `ValueError`. diff --git a/src/mcp_tools_lab/tools/timestamps.py b/src/mcp_tools_lab/tools/timestamps.py index 334d6de..54f5b6f 100644 --- a/src/mcp_tools_lab/tools/timestamps.py +++ b/src/mcp_tools_lab/tools/timestamps.py @@ -4,11 +4,16 @@ from datetime import datetime, timedelta, timezone from typing import Literal +# A fixed list keeps the name in English whatever the machine's locale is. +WEEKDAYS = ("Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday") + def convert_timestamp(value: str, direction: Literal["to_iso", "to_unix"] = "to_iso") -> dict: """Convert Unix seconds to UTC ISO 8601, or an offset-aware ISO date to seconds. ISO input must include a time and timezone, such as 2026-01-01T12:00:00+05:30. + + weekday_utc is the English weekday name of the converted UTC date. """ epoch = datetime(1970, 1, 1, tzinfo=timezone.utc) try: @@ -27,4 +32,8 @@ def convert_timestamp(value: str, direction: Literal["to_iso", "to_unix"] = "to_ raise ValueError("direction must be to_iso or to_unix.") except (ValueError, OverflowError) as error: raise ValueError(f"Cannot convert timestamp: {error}") from error - return {"unix_seconds": seconds, "iso_utc": date.isoformat().replace("+00:00", "Z")} + return { + "unix_seconds": seconds, + "iso_utc": date.isoformat().replace("+00:00", "Z"), + "weekday_utc": WEEKDAYS[date.weekday()], + } diff --git a/tests/test_timestamps.py b/tests/test_timestamps.py index 49f75ed..f3a389e 100644 --- a/tests/test_timestamps.py +++ b/tests/test_timestamps.py @@ -18,3 +18,23 @@ def test_fractional_and_negative_seconds(): def test_invalid_input(value, direction): with pytest.raises(ValueError, match="Cannot convert"): convert_timestamp(value, direction) + + +def test_weekday_utc_for_known_days(): + assert convert_timestamp("0")["weekday_utc"] == "Thursday" + assert convert_timestamp("345600")["weekday_utc"] == "Monday" + assert convert_timestamp("1970-01-04T00:00:00Z", "to_unix")["weekday_utc"] == "Sunday" + + +def test_weekday_utc_uses_utc_not_the_inputs_local_date(): + result = convert_timestamp("1970-01-02T00:30:00+01:00", "to_unix") + assert result["iso_utc"] == "1970-01-01T23:30:00Z" + assert result["weekday_utc"] == "Thursday" + + +def test_weekday_utc_for_negative_timestamp(): + assert convert_timestamp("-0.5")["weekday_utc"] == "Wednesday" + + +def test_weekday_utc_in_both_directions(): + assert convert_timestamp("0")["weekday_utc"] == convert_timestamp("1970-01-01T00:00:00Z", "to_unix")["weekday_utc"]