feat: generate VTIMEZONEs and select components to merge

Author: SashankBhamidi

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"

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,69 @@ def __init__(
 
         self.calendars: list[Calendar] = []
         self._merged = False
+        self.generate_vtimezone = generate_vtimezone
+        self.components = (
+            [c.strip().upper() for c in components if c.strip()]
+            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 +156,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()
 
 

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()
 

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

tests/calendars/test_empty_calendar.ics

@@ -0,0 +1,5 @@
+BEGIN:VCALENDAR
+PRODID:-//Test//Test//EN
+VERSION:2.0
+CALSCALE:GREGORIAN
+END:VCALENDAR

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

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"
 
 

tests/test_component_selection.py

@@ -0,0 +1,107 @@
+"""Select which components to merge (Issue #182)."""
+
+from mergecal import CalendarMerger, merge_calendars
+
+
+def test_default_components_vevent_and_vtimezone_only(calendars):
+    """Only VEVENT and VTIMEZONE are merged by default."""
+    result = merge_calendars(calendars.color_rfc7986.stream)
+
+    assert len(list(result.events)) == 1
+    assert len(list(result.todos)) == 0
+    assert len(list(result.walk("VJOURNAL"))) == 0
+
+
+def test_select_events_only(calendars):
+    """Only VEVENTs are merged; no timezones when VTIMEZONE excluded."""
+    result = merge_calendars(calendars.color_rfc7986.stream, components=["VEVENT"])
+
+    assert len(list(result.events)) == 1
+    assert len(list(result.todos)) == 0
+    assert len(list(result.walk("VJOURNAL"))) == 0
+    assert len(list(result.timezones)) == 0
+
+
+def test_select_todos_only(calendars):
+    """Only VTODOs are merged."""
+    result = merge_calendars(calendars.color_rfc7986.stream, components=["VTODO"])
+
+    assert len(list(result.events)) == 0
+    assert len(list(result.todos)) == 1
+    assert len(list(result.timezones)) == 0
+
+
+def test_select_journals_only(calendars):
+    """Only VJOURNALs are merged."""
+    result = merge_calendars(calendars.color_rfc7986.stream, components=["VJOURNAL"])
+
+    assert len(list(result.events)) == 0
+    assert len(list(result.todos)) == 0
+    assert len(list(result.walk("VJOURNAL"))) == 1
+    assert len(list(result.timezones)) == 0
+
+
+def test_select_events_and_timezones(calendars):
+    """Timezones are generated when VTIMEZONE is included in components."""
+    result = merge_calendars(
+        calendars.no_vtimezone_google.stream, components=["VEVENT", "VTIMEZONE"]
+    )
+
+    assert len(list(result.events)) == 2
+    assert len(list(result.timezones)) > 0
+
+
+def test_calendar_merger_components_parameter(calendars):
+    """CalendarMerger respects the components parameter."""
+    result = CalendarMerger(
+        calendars.color_rfc7986.stream, components=["VEVENT", "VTODO"]
+    ).merge()
+
+    assert len(list(result.events)) == 1
+    assert len(list(result.todos)) == 1
+    assert len(list(result.walk("VJOURNAL"))) == 0
+    assert len(list(result.timezones)) == 0
+
+
+def test_empty_components_list(calendars):
+    """An empty components list produces an empty calendar."""
+    result = merge_calendars(calendars.color_rfc7986.stream, components=[])
+
+    assert len(list(result.events)) == 0
+    assert len(list(result.todos)) == 0
+    assert len(list(result.walk("VJOURNAL"))) == 0
+    assert len(list(result.timezones)) == 0
+
+
+def test_timezone_generation_only_when_vtimezone_in_components(calendars):
+    """generate_vtimezone has no effect when VTIMEZONE is not in the components list."""
+    cals = calendars.no_vtimezone_google.stream
+
+    result_with = merge_calendars(
+        cals, components=["VEVENT", "VTIMEZONE"], generate_vtimezone=True
+    )
+    result_without = merge_calendars(
+        cals, components=["VEVENT"], generate_vtimezone=True
+    )
+
+    assert len(list(result_with.timezones)) > 0
+    assert len(list(result_without.timezones)) == 0
+
+
+def test_multiple_calendars_component_filtering(calendars):
+    """Component filtering applies across all merged calendars."""
+    cals = calendars.one_event.stream + calendars.color_rfc7986.stream
+    result = merge_calendars(cals, components=["VEVENT"])
+
+    assert len(list(result.events)) == 2
+    assert len(list(result.todos)) == 0
+    assert len(list(result.walk("VJOURNAL"))) == 0
+
+
+def test_unknown_components_silently_ignored(calendars):
+    """Unknown component names do not crash the merger."""
+    cals = calendars.test_empty_calendar.stream
+
+    result = CalendarMerger(cals, components=["VEVENT", "UNKNOWN"]).merge()
+
+    assert len(list(result.events)) == 0