import logging from datetime import date, datetime, time, timedelta, timezone from typing import Any from zoneinfo import ZoneInfo from google.oauth2.credentials import Credentials from googleapiclient.discovery import Resource, build logging.basicConfig( level=logging.DEBUG, format="%(asctime)s - %(name)s - %(levelname)s - %(message)s", ) logger = logging.getLogger(__name__) def parse_datetime(datetime_str: str, time_zone: str) -> datetime: """ Parse a datetime string in ISO 8601 format and ensure it is timezone-aware. Args: datetime_str (str): The datetime string to parse. Expected format: 'YYYY-MM-DDTHH:MM:SS'. time_zone (str): The timezone to apply if the datetime string is naive. Returns: datetime: A timezone-aware datetime object. Raises: ValueError: If the datetime string is not in the correct format. """ datetime_str = datetime_str.upper().strip().rstrip("Z") try: dt = datetime.fromisoformat(datetime_str) if dt.tzinfo is None: dt = dt.replace(tzinfo=ZoneInfo(time_zone)) except ValueError as e: raise ValueError( f"Invalid datetime format: '{datetime_str}'. " "Expected ISO 8601 format, e.g., '2024-12-31T15:30:00'." ) from e return dt def build_oauth_service(auth_token: str | None) -> Resource: # type: ignore[no-any-unimported] """ Build an OAuth2 service object. """ auth_token = auth_token or "" return build("oauth2", "v2", credentials=Credentials(auth_token)) def build_calendar_service(auth_token: str | None) -> Resource: # type: ignore[no-any-unimported] """ Build a Calendar service object. """ auth_token = auth_token or "" return build("calendar", "v3", credentials=Credentials(auth_token)) def weekday_to_name(weekday: int) -> str: return ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"][weekday] def get_time_boundaries_for_date( current_date: date, global_start: datetime, global_end: datetime, start_time_boundary: time, end_time_boundary: time, tz: ZoneInfo, ) -> tuple[datetime, datetime]: """Compute the allowed start and end times for the given day, adjusting for global bounds.""" day_start_time = datetime.combine(current_date, start_time_boundary).replace(tzinfo=tz) day_end_time = datetime.combine(current_date, end_time_boundary).replace(tzinfo=tz) if current_date == global_start.date(): day_start_time = max(day_start_time, global_start) if current_date == global_end.date(): day_end_time = min(day_end_time, global_end) return day_start_time, day_end_time def gather_busy_intervals( busy_data: dict[str, Any], day_start: datetime, day_end: datetime, business_tz: ZoneInfo, ) -> list[tuple[datetime, datetime]]: """ Collect busy intervals from all calendars that intersect with the day's business hours. Busy intervals are clipped to lie within [day_start, day_end]. """ busy_intervals = [] for calendar in busy_data: for slot in busy_data[calendar].get("busy", []): slot_start = parse_rfc3339_datetime_str(slot["start"]).astimezone(business_tz) slot_end = parse_rfc3339_datetime_str(slot["end"]).astimezone(business_tz) if slot_end > day_start and slot_start < day_end: busy_intervals.append((max(slot_start, day_start), min(slot_end, day_end))) return busy_intervals def subtract_busy_intervals( business_start: datetime, business_end: datetime, busy_intervals: list[tuple[datetime, datetime]], ) -> list[dict[str, Any]]: """ Subtract the merged busy intervals from the business hours and return free time slots. """ free_slots = [] merged_busy = merge_intervals(busy_intervals) # If there are no busy intervals, return the entire business window as free. if not merged_busy: return [ { "start": { "datetime": business_start.isoformat(), "weekday": weekday_to_name(business_start.weekday()), }, "end": { "datetime": business_end.isoformat(), "weekday": weekday_to_name(business_end.weekday()), }, } ] current_free_start = business_start for busy_start, busy_end in merged_busy: if current_free_start < busy_start: free_slots.append({ "start": { "datetime": current_free_start.isoformat(), "weekday": weekday_to_name(current_free_start.weekday()), }, "end": { "datetime": busy_start.isoformat(), "weekday": weekday_to_name(busy_start.weekday()), }, }) current_free_start = max(current_free_start, busy_end) if current_free_start < business_end: free_slots.append({ "start": { "datetime": current_free_start.isoformat(), "weekday": weekday_to_name(current_free_start.weekday()), }, "end": { "datetime": business_end.isoformat(), "weekday": weekday_to_name(business_end.weekday()), }, }) return free_slots def compute_free_time_intersection( busy_data: dict[str, Any], global_start: datetime, global_end: datetime, start_time_boundary: time, end_time_boundary: time, include_weekends: bool, tz: ZoneInfo, ) -> list[dict[str, Any]]: """ Returns the free time slots across all calendars within the global bounds, ensuring that the global start is not in the past. Only considers business days (Monday to Friday) and business hours (08:00-19:00) in the provided timezone. """ # Ensure global_start is never in the past relative to now. now = get_now(tz) if now > global_start: global_start = now # If after adjusting the start, there's no interval left, return empty. if global_start >= global_end: return [] free_slots = [] current_date = global_start.date() while current_date <= global_end.date(): if not include_weekends and current_date.weekday() >= 5: current_date += timedelta(days=1) continue day_start, day_end = get_time_boundaries_for_date( current_date=current_date, global_start=global_start, global_end=global_end, start_time_boundary=start_time_boundary, end_time_boundary=end_time_boundary, tz=tz, ) # Skip if the day's allowed time window is empty. if day_start >= day_end: current_date += timedelta(days=1) continue busy_intervals = gather_busy_intervals(busy_data, day_start, day_end, tz) free_slots.extend(subtract_busy_intervals(day_start, day_end, busy_intervals)) current_date += timedelta(days=1) return free_slots def get_now(tz: ZoneInfo | None = None) -> datetime: if not tz: tz = ZoneInfo("UTC") return datetime.now(tz) def parse_rfc3339_datetime_str(dt_str: str, tz: timezone = timezone.utc) -> datetime: """ Parse an RFC3339 datetime string into a timezone-aware datetime. Converts a trailing 'Z' (UTC) into +00:00. If the parsed datetime is naive, assume it is in the provided timezone. """ if dt_str.endswith("Z"): dt_str = dt_str[:-1] + "+00:00" dt = datetime.fromisoformat(dt_str) if dt.tzinfo is None: dt = dt.replace(tzinfo=tz) return dt def merge_intervals(intervals: list[tuple[datetime, datetime]]) -> list[tuple[datetime, datetime]]: """ Given a list of (start, end) tuples, merge overlapping or adjacent intervals. """ merged: list[tuple[datetime, datetime]] = [] for start, end in sorted(intervals, key=lambda x: x[0]): if not merged: merged.append((start, end)) else: last_start, last_end = merged[-1] if start <= last_end: merged[-1] = (last_start, max(last_end, end)) else: merged.append((start, end)) return merged