{"id":4856,"library":"x-wr-timezone","title":"x-wr-timezone","description":"The x-wr-timezone library helps make iCalendar (ICS) files, particularly those generated by Google Calendar, compliant with the RFC 5545 standard. Google Calendar often includes a non-standard `X-WR-TIMEZONE` property, which strict parsers ignore, leading to incorrect event times. This Python module converts such calendars to a standard format by adding a `VTIMEZONE` component. The current version is 2.0.1, and it maintains an active development status with updates driven by the underlying `icalendar` library.","status":"active","version":"2.0.1","language":"en","source_language":"en","source_url":"https://github.com/niccokunzmann/x-wr-timezone","tags":["icalendar","timezone","rfc5545","google-calendar","ics","calendar"],"install":[{"cmd":"pip install x-wr-timezone","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core dependency for parsing and generating iCalendar objects.","package":"icalendar","optional":false},{"reason":"Used for command-line interface functionality.","package":"click","optional":true},{"reason":"Transitive dependency of icalendar for robust date/time parsing.","package":"python-dateutil","optional":false},{"reason":"Transitive dependency of icalendar for timezone data.","package":"tzdata","optional":false}],"imports":[{"symbol":"x_wr_timezone","correct":"import x_wr_timezone"},{"note":"The primary function to standardize a calendar object.","symbol":"to_standard","correct":"from x_wr_timezone import to_standard"}],"quickstart":{"code":"import icalendar\nimport x_wr_timezone\n\n# Example: Create a dummy in.ics with X-WR-TIMEZONE for demonstration\n# In a real scenario, you would load an existing .ics file.\nics_content_in = \"\"\"BEGIN:VCALENDAR\nPRODID:-//Google Inc//Google Calendar 70.9054//EN\nVERSION:2.0\nCALSCALE:GREGORIAN\nMETHOD:PUBLISH\nX-WR-CALNAME:Test Calendar\nX-WR-TIMEZONE:America/New_York\nBEGIN:VEVENT\nDTSTART:20260412T100000\nDTEND:20260412T110000\nDTSTAMP:20260412T000000Z\nUID:dummy_event_1@example.com\nSUMMARY:Test Event with X-WR-TIMEZONE\nEND:VEVENT\nEND:VCALENDAR\"\"\"\n\nwith open(\"in.ics\", 'w') as f:\n    f.write(ics_content_in)\n\nprint(\"Created 'in.ics' with non-standard X-WR-TIMEZONE.\")\n\n# Load the calendar from the (dummy) file\nwith open(\"in.ics\", 'rb') as file:\n    calendar = icalendar.from_ical(file.read())\n\n# Standardize the calendar\n# This will convert X-WR-TIMEZONE into an RFC 5545 compliant VTIMEZONE component\nnew_calendar = x_wr_timezone.to_standard(calendar)\n\n# Save the standardized calendar to a new file\nwith open(\"out.ics\", 'wb') as file:\n    file.write(new_calendar.to_ical())\n\nprint(\"Processed 'in.ics' and saved standardized calendar to 'out.ics'.\")\nprint(\"You can inspect 'out.ics' to see the added VTIMEZONE component.\")","lang":"python","description":"This quickstart demonstrates how to load an iCalendar file containing the non-standard `X-WR-TIMEZONE` property, process it using `x_wr_timezone.to_standard()`, and save the resulting RFC 5545 compliant calendar. The example first creates a simple `in.ics` file for demonstration purposes."},"warnings":[{"fix":"Use `x_wr_timezone.to_standard()` to convert calendars containing `X-WR-TIMEZONE` to include RFC 5545-compliant `VTIMEZONE` components.","message":"The `X-WR-TIMEZONE` property is a non-standard iCalendar extension, primarily used by Google Calendar. Strict RFC 5545 compliant parsers will typically ignore it, which can lead to events being displayed with incorrect times if not handled by this library. Understanding this discrepancy is crucial for proper usage.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always capture the return value of `to_standard()`, e.g., `new_calendar = x_wr_timezone.to_standard(original_calendar)`.","message":"The `x_wr_timezone.to_standard(calendar, ...)` function does not modify the input `icalendar.Calendar` object in place. It returns a *new* `icalendar.Calendar` object with the standardized timezone information. Users must assign the return value to a variable to use the standardized calendar.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Carefully consider whether the `timezone` parameter should be used. If the `X-WR-TIMEZONE` property itself dictates the desired target, omit the `timezone` parameter. If a specific target timezone is required regardless of `X-WR-TIMEZONE`, pass it explicitly.","message":"When providing the optional `timezone` parameter to `to_standard(calendar, timezone=...)`, the library will explicitly use this provided timezone for standardization and *will not* test or use the value found in `calendar['X-WR-TIMEZONE']`. This allows overriding the calendar's default `X-WR-TIMEZONE` value but means users should be mindful of the source of truth for the target timezone.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to the `icalendar` documentation for specific version compatibility. For `icalendar` versions 5.0 and above, Python 3.7+ is required. Ensure you are using `icalendar.from_ical()` and `calendar_object.to_ical()` methods.","message":"This library depends on `icalendar`, which has undergone significant breaking changes in its major versions, particularly concerning minimum Python versions and API changes (e.g., `to_ical()` and `from_ical()` for serialization/deserialization). Ensure your `icalendar` version is compatible with your Python environment and `x-wr-timezone`.","severity":"breaking","affected_versions":"Dependent on `icalendar` version (e.g., `icalendar` 4.x for Python 2.7/3.4+, `icalendar` 5.x+ for Python 3.7+)"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}