calendar meeting series skill

Helper functions for building an RFC 5545 iCalendar file with one VEVENT,
an RRULE, and one VALARM, using CRLF line endings.

1. parse_utc_stamp(dtstr)
   - Parameters: dtstr (str) - a UTC timestamp string ending in 'Z',
     e.g. "20250503T060000Z"
   - Returns: an aware datetime.datetime in UTC
   - Example: parse_utc_stamp("20250503T060000Z")

2. create_vevent(uid, summary, location, dtstart, dtend, byday, count, alarm_minutes)
   - Parameters:
       uid (str), summary (str), location (str)
       dtstart (str), dtend (str): UTC timestamp strings ending in 'Z'
       byday (list[str]): weekday codes like ["MO", "SA", "FR"]
       count (int): RRULE COUNT
       alarm_minutes (int): minutes before dtstart the VALARM triggers
   - Returns: icalendar.Event populated with DTSTART, DTEND, SUMMARY,
     LOCATION, UID, RRULE (FREQ=WEEKLY;BYDAY=...;COUNT=...), and a VALARM
     child component with ACTION:DISPLAY and a negative-duration TRIGGER.
   - Example:
       create_vevent("call-0139@stark.example", "Retro", "Room 5",
                     "20250503T060000Z", "20250503T063000Z",
                     ["MO", "SA", "FR"], 15, 30)

3. create_calendar(prodid, events)
   - Parameters:
       prodid (str): PRODID value
       events: a single icalendar.Event or a list of them
   - Returns: icalendar.Calendar with VERSION:2.0, the given PRODID, and
     the given VEVENT(s) added.
   - Example: create_calendar("-//Stark//Cal//EN", event)

4. serialize_calendar(cal)
   - Parameters: cal (icalendar.Calendar)
   - Returns: bytes of the serialized calendar with CRLF line endings
   - Example: serialize_calendar(cal)

5. write_ics(path, data_bytes)
   - Parameters: path (str) output file path, data_bytes (bytes) content
   - Returns: None (writes file to disk in binary mode)
   - Example: write_ics("/tmp/out.ics", data_bytes)

import os
import datetime
from icalendar import Calendar, Event, Alarm


def parse_utc_stamp(dtstr):
    """Parse a UTC timestamp string like '20250503T060000Z' into a
    timezone-aware datetime.datetime (UTC).

    Parameters:
        dtstr (str): timestamp string ending in 'Z', format %Y%m%dT%H%M%SZ

    Returns:
        datetime.datetime: aware UTC datetime

    Example:
        parse_utc_stamp("20250503T060000Z")
    """
    dt = datetime.datetime.strptime(dtstr, "%Y%m%dT%H%M%SZ")
    return dt.replace(tzinfo=datetime.timezone.utc)


def create_vevent(uid, summary, location, dtstart, dtend, byday, count,
                   alarm_minutes):
    """Build an icalendar Event component with an RRULE and a VALARM.

    Parameters:
        uid (str): unique identifier for the event
        summary (str): SUMMARY text
        location (str): LOCATION text
        dtstart (str): UTC timestamp string (e.g. '20250503T060000Z')
        dtend (str): UTC timestamp string (e.g. '20250503T063000Z')
        byday (list[str]): list of weekday codes, e.g. ["MO", "SA", "FR"]
        count (int): number of occurrences for the RRULE COUNT
        alarm_minutes (int): number of minutes before start the alarm fires

    Returns:
        icalendar.Event: fully populated event component (with VALARM)

    Example:
        create_vevent("uid@example", "Retro", "Room 5",
                      "20250503T060000Z", "20250503T063000Z",
                      ["MO", "SA", "FR"], 15, 30)
    """
    event = Event()
    event.add("uid", uid)
    event.add("summary", summary)
    event.add("location", location)
    event.add("dtstart", parse_utc_stamp(dtstart))
    event.add("dtend", parse_utc_stamp(dtend))
    event.add("rrule", {"freq": "weekly", "byday": list(byday), "count": int(count)})

    alarm = Alarm()
    alarm.add("action", "DISPLAY")
    alarm.add("description", summary)
    alarm.add("trigger", datetime.timedelta(minutes=-abs(int(alarm_minutes))))
    event.add_component(alarm)

    return event


def create_calendar(prodid, events):
    """Build an icalendar Calendar with VERSION:2.0, the given PRODID, and
    the given event component(s).

    Parameters:
        prodid (str): PRODID value for the calendar
        events (icalendar.Event or list[icalendar.Event]): one or more
            events to add as VEVENT components

    Returns:
        icalendar.Calendar: fully populated calendar

    Example:
        create_calendar("-//Stark//Cal//EN", event)
    """
    cal = Calendar()
    cal.add("prodid", prodid)
    cal.add("version", "2.0")
    if not isinstance(events, (list, tuple)):
        events = [events]
    for ev in events:
        cal.add_component(ev)
    return cal


def serialize_calendar(cal):
    """Serialize an icalendar Calendar to bytes using CRLF line endings.

    Parameters:
        cal (icalendar.Calendar): the calendar to serialize

    Returns:
        bytes: the serialized .ics content with CRLF line endings

    Example:
        serialize_calendar(cal)
    """
    data = cal.to_ical()
    text = data.decode("utf-8")
    text = text.replace("\r\n", "\n").replace("\n", "\r\n")
    return text.encode("utf-8")


def write_ics(path, data_bytes):
    """Write raw bytes to a file path (binary mode, no newline translation).

    Parameters:
        path (str): filesystem path to write to
        data_bytes (bytes): the content to write

    Returns:
        None

    Example:
        write_ics("/tmp/out.ics", b"BEGIN:VCALENDAR\\r\\n...")
    """
    with open(path, "wb") as f:
        f.write(data_bytes)