Improve error message in zoneinfo module when tzdata is missing

[daram62]

Summary

Improve the error message in the zoneinfo module when timezone data cannot be found due to a missing tzdata package. The current error message doesn't explain why the error occurred or how to resolve it.

Current Behavior

When ZoneInfo cannot find timezone data (typically because the tzdata package is not installed and the system doesn't provide timezone data), users see:

>>> from zoneinfo import ZoneInfo
>>> z = ZoneInfo('America/New_York')
Traceback (most recent call last):
  ...
zoneinfo._common.ZoneInfoNotFoundError: 'No time zone found with key America/New_York'

Problems with current message:

• Doesn't explain why the timezone wasn't found
• Doesn't tell users how to fix the issue
• No guidance on where to find more information

Proposed Enhancement

Enhance the error message when ImportError occurs (indicating missing tzdata package) to provide:

1. Clear explanation of what went wrong
2. Actionable steps to resolve the issue
3. Link to documentation for more details

Proposed error message:

>>> from zoneinfo import ZoneInfo
>>> z = ZoneInfo('America/New_York')
Traceback (most recent call last):
  ...
zoneinfo._common.ZoneInfoNotFoundError: No time zone found with key America/New_York.

This error may occur if timezone data is not available. To resolve this:
  • Install the tzdata package: python -m pip install tzdata
  • Ensure your operating system has timezone data installed
  • Verify the timezone key is correct (e.g., 'America/New_York')

For more information, see:
https://docs.python.org/3/library/zoneinfo.html

Implementation Details

The implementation involves:

1. Separate ImportError handling in _common.py:

   • Currently all exceptions are caught together
   • Split ImportError to provide specific guidance for missing tzdata

2. Override __str__ in ZoneInfoNotFoundError:

   • Fix formatting issue where multi-line messages display with literal \n
   • This occurs because ZoneInfoNotFoundError inherits from KeyError, which wraps messages in repr() by default

Benefits

• Better user experience: Users immediately understand what went wrong
• Reduced support burden: Clear instructions mean fewer questions
• Consistency: Aligns with Python's philosophy of helpful error messages
• Minimal risk: Only affects error message text, not behavior

Testing

• All existing tests pass (254 tests)
• Manually verified improved error message formatting
• No breaking changes to API or behavior

Code Example

# In Lib/zoneinfo/_common.py
except ImportError:
    msg = (
        f"No time zone found with key {key}.\n\n"
        "This error may occur if timezone data is not available. "
        "To resolve this:\n"
        "  • Install the tzdata package: python -m pip install tzdata\n"
        "  • Ensure your operating system has timezone data installed\n"
        "  • Verify the timezone key is correct (e.g., 'America/New_York')\n\n"
        "For more information, see:\n"
        "https://docs.python.org/3/library/zoneinfo.html"
    )
    raise ZoneInfoNotFoundError(msg)

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

No response

Linked PRs

• gh-140039: Improve error message in zoneinfo when tzdata is missing #140040

[StanFromIreland]

What you are seeing is somewhat Windows-specific, on Unix, zoneinfo falls back to system provided data, e.g.:

>>> from zoneinfo import ZoneInfo
>>> z = ZoneInfo('America/New_York')
>>> import tzdata
Traceback (most recent call last):
  File "<python-input-2>", line 1, in <module>
    import tzdata
ModuleNotFoundError: No module named 'tzdata'

[daram62]

Thanks for pointing that out!
I’d like to address this by refining the message so it better handles the Windows-specific case, where zoneinfo doesn’t have system-provided timezone data and users often face a confusing ZoneInfoNotFoundError.

My plan is to keep the message general enough for Unix users (for example, handling invalid keys), while adding clearer guidance for Windows users to install tzdata.
This way, the error message will be more helpful and less OS-dependent overall.

[StanFromIreland]

Closing as per note on issue.