Registry / serialization / x-wr-timezone

x-wr-timezone

library2.0.1pypypi✓ verified 24d ago

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.

serialization database

pip install x-wr-timezone

github ↗package ↗

INSTALL

IMPORT

SIG · X-WR-TIMEZONE

x-wr-timezone

serializationpythonv2.0.1

Install

2.2s avg

Import

360ms

Disk

25MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.374s · 27.7MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.2s · import 0.346s · 28MB

25MB installed

● package 25MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

x_wr_timezone

✓ import x_wr_timezone

to_standard

✓ from x_wr_timezone import to_standard

The primary function to standardize a calendar object.

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.")

Debug

Known issues

gotchaThe `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.

affects: All versions

gotchaThe `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)`.

affects: All versions

gotchaWhen 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.

affects: All versions

breakingThis 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.

affects: Dependent on `icalendar` version (e.g., `icalendar` 4.x for Python 2.7/3.4+, `icalendar` 5.x+ for Python 3.7+)

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'x_wr_timezone'

The x-wr-timezone library is not installed in your Python environment or the module name 'x_wr_timezone' is misspelled in your import statement.

fix

Install the library using `pip install x-wr-timezone` and ensure your import statement uses the correct module name, e.g., `from x_wr_timezone import convert`.

AttributeError: 'str' object has no attribute 'walk'

The `convert` function expects an `icalendar.Calendar` object as its first argument, but a raw ICS string was passed directly instead of a parsed calendar object.

fix

First, parse your ICS string into a `Calendar` object using `from icalendar import Calendar; cal = Calendar.from_ical(ics_string)` before passing `cal` to `convert`.

ImportError: cannot import name 'fix_timezone' from 'x_wr_timezone'

You are attempting to import a function (e.g., `fix_timezone`, `convert_calendar`) that does not exist or is incorrectly named within the `x_wr_timezone` module; the primary conversion function is named `convert`.

fix

Use the correct import statement for the main conversion function: `from x_wr_timezone import convert`.

icalendar.parser.ContentlineError: No ':' in line

This error occurs in the underlying `icalendar` library when it fails to parse your input ICS data due to malformed syntax (e.g., a missing colon separator in a content line), preventing `x-wr-timezone` from processing it.

fix

Ensure that the input ICS string is a syntactically valid iCalendar format that `icalendar.Calendar.from_ical()` can parse successfully before attempting to convert it.

Upgrade

Version history

2.0.1latest on PyPI · released Feb 6, 2025

Audit

Dependencies

icalendarrequiredCore dependency for parsing and generating iCalendar objects.

clickoptionalUsed for command-line interface functionality.

python-dateutilrequiredTransitive dependency of icalendar for robust date/time parsing.

tzdatarequiredTransitive dependency of icalendar for timezone data.

Agent activity

38 hits · last 30 days

node