gh-140039: Improve ZoneInfo error messages with detailed guidance

This commit enhances the error messages when a timezone key is not found
in the zoneinfo module by using PEP-678 exception notes to provide clear,
actionable guidance to users.

Key improvements:
- Uses PEP-678 add_note() for better error message formatting
- Checks if tzdata package is actually missing before suggesting installation
- Provides different messages for missing tzdata vs incorrect timezone keys
- Uses hyphens instead of unicode bullet points for better compatibility
- Changes 'e.g.' to 'for example' for clarity
- Removes OS timezone data message that was confusing for Windows users

The error message now intelligently detects whether:
1. tzdata is not installed (suggests: pip install tzdata)
2. tzdata is installed but key is wrong (suggests: verify the key)

This makes debugging timezone issues much easier for Python developers.

Author: daram62

Lib/zoneinfo/_common.py

@@ -17,17 +17,28 @@ def load_tzdata(key):
     except ImportError:
         # If package_name doesn't exist, it means tzdata is not installed
         # or there's an error in the folder name like Amrica/New_York
-        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)
+        exc = ZoneInfoNotFoundError(f"No time zone found with key {key}")
+        
+        # Check if tzdata is actually missing
+        try:
+            import tzdata
+        except ImportError:
+            # tzdata is not installed, provide installation instructions
+            exc.add_note(
+                "This error may occur if timezone data is not available. "
+                "To resolve this:"
+            )
+            exc.add_note("  - Install the tzdata package: python -m pip install tzdata")
+            exc.add_note("  - Verify the timezone key is correct (for example, 'America/New_York')")
+            exc.add_note("")
+            exc.add_note("For more information, see:")
+            exc.add_note("https://docs.python.org/3/library/zoneinfo.html")
+        else:
+            # tzdata is installed but the key wasn't found
+            exc.add_note(f"The timezone key '{key}' was not found in the tzdata package.")
+            exc.add_note("Please verify the timezone key is correct (for example, 'America/New_York').")
+        
+        raise exc
     except (FileNotFoundError, UnicodeEncodeError, IsADirectoryError):
         # Other errors that amount to "we cannot find this key":
         #
@@ -177,10 +188,3 @@ def from_file(cls, stream):
 
 class ZoneInfoNotFoundError(KeyError):
     """Exception raised when a ZoneInfo key is not found."""
-    
-    def __str__(self):
-        # Override __str__ to return the message directly without repr() formatting
-        # that KeyError applies by default
-        if self.args:
-            return str(self.args[0])
-        return super().__str__()

Misc/NEWS.d/next/Library/2025-10-13-21-42-05.gh-issue-140039.abcdef.rst

@@ -0,0 +1,4 @@
+Improve error message in :mod:`zoneinfo` when timezone data is not found due
+to missing :pypi:`tzdata` package. The new error message provides clear
+instructions on how to resolve the issue, including installing the package
+and links to documentation. Patch by daram62.