x-wr-timezone

Warnings

• gotcha 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.
  Fix: Use `x_wr_timezone.to_standard()` to convert calendars containing `X-WR-TIMEZONE` to include RFC 5545-compliant `VTIMEZONE` components.
• gotcha 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.
  Fix: Always capture the return value of `to_standard()`, e.g., `new_calendar = x_wr_timezone.to_standard(original_calendar)`.
• gotcha 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.
  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.
• breaking 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`.
  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.

Install

• pip install x-wr-timezone Install with pip

Imports

• x_wr_timezone

  import x_wr_timezone

• to_standard

  from x_wr_timezone import to_standard

  The primary function to standardize a calendar object.

Quickstart

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.

import icalendar
import x_wr_timezone

# Example: Create a dummy in.ics with X-WR-TIMEZONE for demonstration
# In a real scenario, you would load an existing .ics file.
ics_content_in = """BEGIN:VCALENDAR
PRODID:-//Google Inc//Google Calendar 70.9054//EN
VERSION:2.0
CALSCALE:GREGORIAN
METHOD:PUBLISH
X-WR-CALNAME:Test Calendar
X-WR-TIMEZONE:America/New_York
BEGIN:VEVENT
DTSTART:20260412T100000
DTEND:20260412T110000
DTSTAMP:20260412T000000Z
UID:dummy_event_1@example.com
SUMMARY:Test Event with X-WR-TIMEZONE
END:VEVENT
END:VCALENDAR"""

with open("in.ics", 'w') as f:
    f.write(ics_content_in)

print("Created 'in.ics' with non-standard X-WR-TIMEZONE.")

# Load the calendar from the (dummy) file
with open("in.ics", 'rb') as file:
    calendar = icalendar.from_ical(file.read())

# Standardize the calendar
# This will convert X-WR-TIMEZONE into an RFC 5545 compliant VTIMEZONE component
new_calendar = x_wr_timezone.to_standard(calendar)

# Save the standardized calendar to a new file
with open("out.ics", 'wb') as file:
    file.write(new_calendar.to_ical())

print("Processed 'in.ics' and saved standardized calendar to 'out.ics'.")
print("You can inspect 'out.ics' to see the added VTIMEZONE component.")