fix (timezone/windows): Implemented support for the tzlocal

[jafin]

Windows Timezone Detection Fix - Implementation Summary

Problem

The Windows timezone detection in SystemTimeDetector.get_timezone() is using tzutil which returns Windows-specific timezone IDs (e.g., "Eastern Standard Time", "Pacific Standard Time") instead of IANA timezone names (e.g., "America/New_York", "America/Los_Angeles"). This caused failures for some locales and inconsistent behavior across platforms.

Solution

Implemented support for the tzlocal library (version 5.0+) which properly converts Windows timezone IDs to IANA timezone names, with silent fallback to the original tzutil approach if tzlocal is not available.

Changes Made

1. Added tzlocal Import (src/claude_monitor/utils/time_utils.py)

try:
    from tzlocal import get_localzone_name

    HAS_TZLOCAL = True
except ImportError:
    HAS_TZLOCAL = False

    def get_localzone_name():
        """Stub function when tzlocal is not available."""
        return None

2. Updated Windows Timezone Detection (src/claude_monitor/utils/time_utils.py)

elif system == "Windows":
    # Try tzlocal first for proper IANA timezone name
    if HAS_TZLOCAL:
        with contextlib.suppress(Exception):
            tz_name = get_localzone_name()
            if tz_name:
                return tz_name

    # Fallback to tzutil if tzlocal is not available
    with contextlib.suppress(Exception):
        tzutil_result: subprocess.CompletedProcess[str] = subprocess.run(
            ["tzutil", "/g"], capture_output=True, text=True, check=True
        )
        return tzutil_result.stdout.strip()

3. Added tzlocal Dependency (pyproject.toml)

dependencies = [
  # ... other dependencies ...
  "tzlocal>=5.0"
]

4. Updated Tests (src/tests/test_time_utils.py)

Added two tests to cover both the tzlocal and fallback scenarios:

• test_get_timezone_windows: Tests tzlocal-based IANA timezone detection
• test_get_timezone_windows_fallback: Tests fallback to tzutil when tzlocal is unavailable

Resolves #188

Summary by CodeRabbit

• Bug Fixes

  • Improved Windows timezone detection to prefer IANA names when available and fall back more reliably for unknown cases.

• Tests

  • Added tests covering Windows primary and fallback timezone detection, unknown-system fallback, and time format retrieval.

• Chores

  • Added optional tzlocal dependency to support improved Windows timezone handling.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

---

📝 Walkthrough

Walkthrough

Adds optional tzlocal support and runtime detection for Windows timezones: module-level HAS_TZLOCAL and get_localzone_name stub; Windows detection tries tzlocal IANA name first, then falls back to tzutil. pyproject.toml lists tzlocal as a Windows-only dependency and tests for Windows behaviors were added.

Changes

Cohort / File(s)	Summary
Dependency Management pyproject.toml	Added tzlocal>=5.0 as a Windows-specific dependency (kept tzdata under sys_platform == "win32"); formatting adjusted to include a separate line for tzlocal.
Core Timezone Detection src/claude_monitor/utils/time_utils.py	Added HAS_TZLOCAL flag and a safe get_localzone_name() stub when tzlocal is absent. On Windows, detection now prefers tzlocal-provided IANA names and falls back to tzutil if unavailable; mirrored changes in SystemTimeDetector logic.
Tests — Time Utilities src/tests/test_time_utils.py	Added Windows-focused tests: test_get_timezone_windows (tzlocal present), test_get_timezone_windows_fallback (tzlocal absent, tzutil fallback), plus test_get_timezone_unknown_system and a test_get_time_format to validate time format retrieval.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I hopped through clocks on Windows' floor,
Found IANA names I'd longed for more,
tzlocal whispered the zone's true name,
tzutil next when it couldn't claim,
Now time and rabbit both know the score.

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: implementing tzlocal support for Windows timezone detection.
Linked Issues check	✅ Passed	The PR successfully addresses issue #188 by implementing tzlocal support for Windows IANA timezone detection with fallback to tzutil.
Out of Scope Changes check	✅ Passed	All changes are within scope: tzlocal dependency addition, Windows timezone detection implementation, and corresponding test coverage.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Merge Conflict Detection	✅ Passed	✅ No merge conflicts detected when merging into main

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

Issue Planner is now in beta. Read the docs and try it out! Share your feedback on Discord.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@src/tests/test_time_utils.py`:
- Around line 362-374: The test misses mocking os.environ.get("TZ") so it may
short-circuit and skip the Windows branch; update test_get_timezone_windows to
ensure TZ is unset by adding a mock for os.environ.get that returns None (e.g.,
add `@patch`("os.environ.get", return_value=None) or use patch.dict to clear TZ)
before calling SystemTimeDetector.get_timezone(), so the test always exercises
the Windows logic and uses mock_get_localzone_name -> "America/New_York".

🧹 Nitpick comments (1)

pyproject.toml (1)

48-49: Consider making tzlocal a Windows-only dependency.

tzlocal is only used in the Windows code path of SystemTimeDetector.get_timezone(), and the import is already guarded with try/except. Installing it unconditionally on Linux/macOS adds an unnecessary transitive dependency. Apply the same platform marker used for tzdata:

Proposed fix

  "tzdata; sys_platform == 'win32'",
- "tzlocal>=5.0"
+ "tzlocal>=5.0; sys_platform == 'win32'"

[Jamie-Clayton]

@jafin I'm really keen to see better time zone support in Australia. I'm not as experienced in Python, so did you get a chance to see the Code Rabit automated review? #189 (review)

[Jamie-Clayton]

@Maciek-roboblog - Would you mind reviewing this PR to help the software engineers who are in different time zones work with your great product?