feat: generate VTIMEZONEs and select components to merge

SashankBhamidi · SashankBhamidi · commit 42044a076f0b · 2026-03-03T23:15:58.000+05:30
diff --git a/pyproject.toml b/pyproject.toml
@@ -25,7 +25,7 @@ classifiers = [
 ]
 
 dependencies = [
-  "icalendar>=7.0.2",
+  "icalendar>=7.0.3",
   "rich>=10",
   "typer>=0.15,<1",
   "x-wr-timezone>=2.0.1"
diff --git a/src/mergecal/calendar_merger.py b/src/mergecal/calendar_merger.py
@@ -1,10 +1,18 @@
+from __future__ import annotations
+
 from dataclasses import dataclass, field
 
-from icalendar import Calendar, Component
+from icalendar import Calendar, Component, Timezone
 from x_wr_timezone import to_standard
 
 ComponentId = tuple[str, int, str | None]
 
+# Avoids expensive re-generation of VTIMEZONE components across CalendarMerger
+# instances.
+_timezone_cache: dict[str, Timezone] = {}
+
+DEFAULT_COMPONENTS = ["VEVENT", "VTIMEZONE"]
+
 
 def calendars_from_ical(data: bytes) -> list[Calendar]:
     """Parse ICS data, returning one Calendar per VCALENDAR component found."""
@@ -52,6 +60,8 @@ def __init__(
         version: str = "2.0",
         calscale: str = "GREGORIAN",
         method: str | None = None,
+        generate_vtimezone: bool = True,
+        components: list[str] | None = None,
     ):
         self.merged_calendar = Calendar()
 
@@ -64,13 +74,67 @@ def __init__(
 
         self.calendars: list[Calendar] = []
         self._merged = False
+        self.generate_vtimezone = generate_vtimezone
+        self.components = (
+            list(components) if components is not None else list(DEFAULT_COMPONENTS)
+        )
 
         for calendar in calendars:
             self.add_calendar(calendar)
 
+    def _get_components(self, cal: Calendar) -> list[Component]:
+        result: list[Component] = []
+        if "VEVENT" in self.components:
+            result.extend(cal.events)
+        if "VTODO" in self.components:
+            result.extend(cal.todos)
+        if "VJOURNAL" in self.components:
+            result.extend(cal.walk("VJOURNAL"))
+        return result
+
+    def _should_generate_timezones(self) -> bool:
+        return "VTIMEZONE" in self.components and self.generate_vtimezone
+
     def add_calendar(self, calendar: Calendar) -> None:
         """Add a calendar to be merged."""
-        self.calendars.append(to_standard(calendar, add_timezone_component=True))
+        cal = to_standard(
+            calendar, add_timezone_component=self._should_generate_timezones()
+        )
+
+        if self._should_generate_timezones():
+            for tz in cal.timezones:
+                if tz.tz_name not in _timezone_cache:
+                    _timezone_cache[tz.tz_name] = tz
+
+            # to_standard() may add a VTIMEZONE even when one already exists for
+            # the same TZID, causing get_missing_tzids() to raise KeyError
+            # (collective/icalendar#1124). Deduplicate before calling
+            # add_missing_timezones().
+            seen_tzids: set[str] = set()
+            deduped: list[Component] = []
+            for c in cal.subcomponents:
+                if isinstance(c, Timezone):
+                    if c.tz_name in seen_tzids:
+                        continue
+                    seen_tzids.add(c.tz_name)
+                deduped.append(c)
+            cal.subcomponents[:] = deduped
+
+            if cal.get_used_tzids():
+                missing_tzids = cal.get_missing_tzids()
+
+                for tzid in missing_tzids:
+                    if tzid in _timezone_cache:
+                        cal.add_component(_timezone_cache[tzid])
+
+                remaining = cal.get_missing_tzids()
+                if remaining:
+                    cal.add_missing_timezones()
+                    for tz in cal.timezones:
+                        if tz.tz_name in remaining:
+                            _timezone_cache[tz.tz_name] = tz
+
+        self.calendars.append(cal)
 
     def merge(self) -> Calendar:
         """Merge the calendars."""
@@ -90,20 +154,36 @@ def merge(self) -> Calendar:
             if calendar_color and not self.merged_calendar.color:
                 self.merged_calendar.color = calendar_color
 
-            for timezone in cal.timezones:
-                if timezone.tz_name not in tzids:
-                    self.merged_calendar.add_component(timezone)
-                    tzids.add(timezone.tz_name)
-
-            for component in cal.events + cal.todos + cal.journals:
+            if "VTIMEZONE" in self.components:
+                for timezone in cal.timezones:
+                    if timezone.tz_name == "UTC":
+                        # UTC needs no VTIMEZONE per RFC 5545 §3.6.5; skip spurious
+                        # entries generated by add_missing_timezones()
+                        # (collective/icalendar#1124)
+                        continue
+                    if timezone.tz_name not in tzids:
+                        self.merged_calendar.add_component(timezone)
+                        tzids.add(timezone.tz_name)
+
+            for component in self._get_components(cal):
                 tracker.add(component, calendar_color)
 
         return self.merged_calendar
 
 
-def merge_calendars(calendars: list[Calendar], **kwargs: object) -> Calendar:
+def merge_calendars(
+    calendars: list[Calendar],
+    generate_vtimezone: bool = True,
+    components: list[str] | None = None,
+    **kwargs: object,
+) -> Calendar:
     """Convenience function to merge calendars."""
-    merger = CalendarMerger(calendars, **kwargs)  # type: ignore
+    merger = CalendarMerger(
+        calendars,
+        generate_vtimezone=generate_vtimezone,
+        components=components,
+        **kwargs,  # type: ignore[arg-type]
+    )
     return merger.merge()
 
 
diff --git a/src/mergecal/cli.py b/src/mergecal/cli.py
@@ -7,13 +7,22 @@
 
 app = typer.Typer()
 
-# Define arguments and options outside of the function
 calendars_arg = typer.Argument(..., help="Paths to the calendar files to merge")
 output_opt = typer.Option(
     "merged_calendar.ics", "--output", "-o", help="Output file path"
 )
 prodid_opt = typer.Option(None, "--prodid", help="Product ID for the merged calendar")
 method_opt = typer.Option(None, "--method", help="Calendar method")
+no_generate_vtimezone_opt = typer.Option(
+    False,
+    "--no-generate-vtimezone",
+    help="Disable VTIMEZONE generation for performance",
+)
+components_opt = typer.Option(
+    None,
+    "--components",
+    help="Comma-separated component types to merge (VEVENT,VTODO,VJOURNAL,VTIMEZONE)",
+)
 
 
 @app.command()
@@ -22,6 +31,8 @@ def main(
     output: Path = output_opt,
     prodid: str | None = prodid_opt,
     method: str | None = method_opt,
+    no_generate_vtimezone: bool = no_generate_vtimezone_opt,
+    components: str | None = components_opt,
 ) -> None:
     """Merge multiple iCalendar files into one."""
     try:
@@ -31,7 +42,15 @@ def main(
                 calendar_objects.extend(calendars_from_ical(cal_file.read()))
 
         merger = CalendarMerger(
-            calendars=calendar_objects, prodid=prodid, method=method
+            calendars=calendar_objects,
+            prodid=prodid,
+            method=method,
+            generate_vtimezone=not no_generate_vtimezone,
+            components=(
+                [p.strip() for p in components.split(",") if p.strip()]
+                if components
+                else None
+            ),
         )
         merged_calendar = merger.merge()
 
diff --git a/tests/calendars/no_vtimezone_google.ics b/tests/calendars/no_vtimezone_google.ics
@@ -0,0 +1,34 @@
+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;TZID=America/New_York:20240315T090000
+DTEND;TZID=America/New_York:20240315T100000
+DTSTAMP:20240301T120000Z
+UID:test-event-1@google.com
+CREATED:20240301T120000Z
+DESCRIPTION:Test event with timezone reference but no VTIMEZONE component
+LAST-MODIFIED:20240301T120000Z
+SEQUENCE:0
+STATUS:CONFIRMED
+SUMMARY:Meeting in New York timezone
+TRANSP:OPAQUE
+END:VEVENT
+BEGIN:VEVENT
+DTSTART;TZID=Europe/London:20240320T140000
+DTEND;TZID=Europe/London:20240320T150000
+DTSTAMP:20240301T120000Z
+UID:test-event-2@google.com
+CREATED:20240301T120000Z
+DESCRIPTION:Another event with different timezone but no VTIMEZONE
+LAST-MODIFIED:20240301T120000Z
+SEQUENCE:0
+STATUS:CONFIRMED
+SUMMARY:London meeting
+TRANSP:OPAQUE
+END:VEVENT
+END:VCALENDAR
diff --git a/tests/calendars/test_empty_calendar.ics b/tests/calendars/test_empty_calendar.ics
@@ -0,0 +1,5 @@
+BEGIN:VCALENDAR
+PRODID:-//Test//Test//EN
+VERSION:2.0
+CALSCALE:GREGORIAN
+END:VCALENDAR
diff --git a/tests/calendars/test_single_event.ics b/tests/calendars/test_single_event.ics
@@ -0,0 +1,12 @@
+BEGIN:VCALENDAR
+PRODID:-//Test//Test//EN
+VERSION:2.0
+CALSCALE:GREGORIAN
+BEGIN:VEVENT
+UID:test-single-event@test.com
+SUMMARY:Test Single Event
+DTSTART;TZID=America/Chicago:20240101T120000
+DTEND;TZID=America/Chicago:20240101T130000
+DTSTAMP:20240101T000000Z
+END:VEVENT
+END:VCALENDAR
diff --git a/tests/test_color_merging.py b/tests/test_color_merging.py
@@ -4,7 +4,10 @@
 
 
 def test_component_inherits_calendar_color(calendars, component_type):
-    result = merge_calendars(calendars.color_rfc7986.stream)
+    result = merge_calendars(
+        calendars.color_rfc7986.stream,
+        components=["VEVENT", "VTODO", "VJOURNAL"],
+    )
     assert result.walk(component_type)[0].color == "turquoise"
 
 
@@ -14,7 +17,10 @@ def test_event_inherits_apple_calendar_color(calendars):
 
 
 def test_component_own_color_not_overwritten(calendars, component_type):
-    result = merge_calendars(calendars.color_event_own.stream)
+    result = merge_calendars(
+        calendars.color_event_own.stream,
+        components=["VEVENT", "VTODO", "VJOURNAL"],
+    )
     assert result.walk(component_type)[0].color == "navy"
 
 
@@ -38,7 +44,7 @@ def test_merged_calendar_color_when_only_one_has_color(calendars):
 
 def test_component_own_color_preserved_across_calendars(calendars, component_type):
     cals = calendars.color_event_own.stream + calendars.color_rfc7986.stream
-    result = merge_calendars(cals)
+    result = merge_calendars(cals, components=["VEVENT", "VTODO", "VJOURNAL"])
     assert result.walk(component_type)[0].color == "navy"
 
 
diff --git a/tests/test_component_selection.py b/tests/test_component_selection.py
diff --git a/tests/test_issue_7_generate_vtimezones.py b/tests/test_issue_7_generate_vtimezones.py

Original file line number	Diff line number	Diff line change
`@@ -25,7 +25,7 @@ classifiers = [`
`25`	`25`	`]`
`26`	`26`
`27`	`27`	`dependencies = [`
`28`		`- "icalendar>=7.0.2",`
	`28`	`+ "icalendar>=7.0.3",`
`29`	`29`	`"rich>=10",`
`30`	`30`	`"typer>=0.15,<1",`
`31`	`31`	`"x-wr-timezone>=2.0.1"`