From 38c814a1c869584c55326094e51276cc964d77d0 Mon Sep 17 00:00:00 2001 From: Minseo Kim Date: Mon, 13 Oct 2025 21:19:04 +0900 Subject: [PATCH 1/3] gh-140039: Improve error message in zoneinfo when tzdata is missing Add more helpful error messages when ZoneInfo cannot find timezone data, specifically when the ImportError occurs due to missing tzdata package. The new error message provides: - Clear explanation of why the error occurred - Step-by-step instructions to resolve the issue - Link to official documentation for more information Also override __str__ in ZoneInfoNotFoundError to properly display multi-line error messages (KeyError wraps messages in repr() by default). This improves user experience by making it immediately clear what went wrong and how to fix it, rather than just stating the key wasn't found. --- Lib/zoneinfo/_common.py | 29 +++++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-) diff --git a/Lib/zoneinfo/_common.py b/Lib/zoneinfo/_common.py index 03cc42149f9b74..fee91a06243a1f 100644 --- a/Lib/zoneinfo/_common.py +++ b/Lib/zoneinfo/_common.py @@ -14,13 +14,23 @@ def load_tzdata(key): if path.is_dir(): raise IsADirectoryError return path.open("rb") - except (ImportError, FileNotFoundError, UnicodeEncodeError, IsADirectoryError): - # There are four types of exception that can be raised that all amount - # to "we cannot find this 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) + except (FileNotFoundError, UnicodeEncodeError, IsADirectoryError): + # Other errors that amount to "we cannot find this key": # - # ImportError: If package_name doesn't exist (e.g. if tzdata is not - # installed, or if there's an error in the folder name like - # Amrica/New_York) # FileNotFoundError: If resource_name doesn't exist in the package # (e.g. Europe/Krasnoy) # UnicodeEncodeError: If package_name or resource_name are not UTF-8, @@ -167,3 +177,10 @@ 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__() From bad8647d09c8b0adf35303465e27159a011bee73 Mon Sep 17 00:00:00 2001 From: Minseo Kim Date: Mon, 13 Oct 2025 21:42:32 +0900 Subject: [PATCH 2/3] 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. --- Lib/zoneinfo/_common.py | 40 ++++++++++--------- ...-10-13-21-42-05.gh-issue-140039.abcdef.rst | 4 ++ 2 files changed, 26 insertions(+), 18 deletions(-) create mode 100644 Misc/NEWS.d/next/Library/2025-10-13-21-42-05.gh-issue-140039.abcdef.rst diff --git a/Lib/zoneinfo/_common.py b/Lib/zoneinfo/_common.py index fee91a06243a1f..4bec34e7241003 100644 --- a/Lib/zoneinfo/_common.py +++ b/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__() diff --git a/Misc/NEWS.d/next/Library/2025-10-13-21-42-05.gh-issue-140039.abcdef.rst b/Misc/NEWS.d/next/Library/2025-10-13-21-42-05.gh-issue-140039.abcdef.rst new file mode 100644 index 00000000000000..b777aaa596df25 --- /dev/null +++ b/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. \ No newline at end of file From 36677ba901e307d73cff29964d332752020aea2e Mon Sep 17 00:00:00 2001 From: Minseo Kim Date: Mon, 13 Oct 2025 23:40:51 +0900 Subject: [PATCH 3/3] Address review feedback: simplify error message wording - Change 'To resolve this:' to 'Try:' to avoid implying guaranteed solution - Remove else block as ZoneInfoNotFoundError is clear enough without extra notes - Simplify message structure for better readability --- Lib/zoneinfo/_common.py | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/Lib/zoneinfo/_common.py b/Lib/zoneinfo/_common.py index 4bec34e7241003..f9c38280eabd72 100644 --- a/Lib/zoneinfo/_common.py +++ b/Lib/zoneinfo/_common.py @@ -24,19 +24,13 @@ def load_tzdata(key): 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("This error may occur if timezone data is not available.") + exc.add_note("Try:") + exc.add_note(" - Installing the tzdata package: python -m pip install tzdata") + exc.add_note(" - Verifying 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):