Confluence Utils

Calendar utilities for expanding ICS events and extracting bookings.

This module provides two public entry points:

  • get_all_events: expand recurring ICS events within a date window and return normalized event dicts (AWST timezone).

  • get_booked_auto_obs: filter events for specific automated observation tickets.

All date handling is normalized to the Australia/Perth timezone (AWST).

ska_sci_ops_data_analysis.confluence_utils.get_all_events(calendar_name: str, dates: Sequence[str | date | datetime]) → List[Dict[str, Any]]

Return all events on the given date(s), sorted by start time.

The function downloads the ICS for the calendar, expands recurring events, keeps only events whose start falls within the inclusive window, and returns AWST-aware datetimes. The interval is from 00:00 of the earliest day up to (but not including) 00:00 of the day after the latest day.

Parameters:

  • calendar_name – Key in CALENDAR_METADATA (for example, “DEV-ITF” or “AA”).

  • dates – Either a two-item inclusive range [start, end] or a list of per-day entries. Each entry may be “YYYY-MM-DD”, a date, or a datetime.

Returns:

Event dictionaries sorted by start time. Each dict has keys summary (str), start (datetime, AWST), end (datetime, AWST), and type (str).

Raises:

ValueError – If calendar_name is unknown or the date range is invalid.

ska_sci_ops_data_analysis.confluence_utils.get_booked_auto_obs(dates: Sequence[str | date | datetime], ticket: str, calendar_name: str = 'AA') → List[Dict[str, Any]]

Find automated observation bookings within a date window.

Supported tickets are "LCO-12" (Automated frequency sweeps) and "LCO-66" (sun drift). The function calls get_all_events, filters by a ticket-specific key phrase contained in the event summary, and returns compact booking records.

Parameters:

  • dates – Either [start, end] (inclusive) or a list of per-day entries. Each entry may be “YYYY-MM-DD”, a date, or a datetime.

  • ticket – One of "LCO-12" or "LCO-66".

  • calendar_name – Key in CALENDAR_METADATA. Defaults to "AA".

Returns:

Booking dictionaries with keys booking_start_time (datetime, AWST), booking_end_time (datetime, AWST), booking_summary (str), and associated_ticket (str).

Raises:

ValueError – If ticket is not supported.