gsuite-sdk 0.1.0__py3-none-any.whl

gsuite_calendar/__init__.py

@@ -0,0 +1,13 @@
+"""Google Suite Calendar - Simple Calendar API client."""
+
+__version__ = "0.1.0"
+
+from gsuite_calendar.calendar_entity import CalendarEntity
+from gsuite_calendar.client import Calendar
+from gsuite_calendar.event import Event
+
+__all__ = [
+    "Calendar",
+    "Event",
+    "CalendarEntity",
+]

gsuite_calendar/calendar_entity.py

@@ -0,0 +1,31 @@
+"""Calendar entity."""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class CalendarEntity:
+    """
+    A calendar.
+
+    Represents a single calendar (primary or shared).
+    """
+
+    id: str
+    summary: str
+    description: str | None = None
+    time_zone: str | None = None
+    primary: bool = False
+    access_role: str = "reader"  # freeBusyReader, reader, writer, owner
+    background_color: str | None = None
+    foreground_color: str | None = None
+
+    @property
+    def is_primary(self) -> bool:
+        """Check if this is the user's primary calendar."""
+        return self.primary
+
+    @property
+    def is_writable(self) -> bool:
+        """Check if user can write to this calendar."""
+        return self.access_role in ("writer", "owner")

gsuite_calendar/client.py

@@ -0,0 +1,268 @@
+"""Calendar client - high-level interface."""
+
+import logging
+from datetime import date, datetime, timedelta
+
+from googleapiclient.discovery import build
+from googleapiclient.errors import HttpError
+
+from gsuite_calendar.calendar_entity import CalendarEntity
+from gsuite_calendar.event import Event
+from gsuite_calendar.parser import CalendarParser
+from gsuite_core import GoogleAuth, get_settings
+
+logger = logging.getLogger(__name__)
+
+
+class Calendar:
+    """
+    High-level Calendar client.
+
+    Example:
+        auth = GoogleAuth()
+        auth.authenticate()
+
+        cal = Calendar(auth)
+
+        # Get upcoming events
+        for event in cal.get_upcoming(days=7):
+            print(f"{event.start}: {event.summary}")
+
+        # Create event
+        cal.create_event(
+            summary="Meeting",
+            start=datetime(2026, 1, 30, 10, 0),
+            end=datetime(2026, 1, 30, 11, 0),
+        )
+    """
+
+    def __init__(self, auth: GoogleAuth, calendar_id: str = "primary"):
+        """
+        Initialize Calendar client.
+
+        Args:
+            auth: GoogleAuth instance with valid credentials
+            calendar_id: Default calendar ID ("primary" for main calendar)
+        """
+        self.auth = auth
+        self.calendar_id = calendar_id
+        self._service = None
+
+    @property
+    def service(self):
+        """Lazy-load Calendar API service."""
+        if self._service is None:
+            self._service = build("calendar", "v3", credentials=self.auth.credentials)
+        return self._service
+
+    # ========== Event retrieval ==========
+
+    def get_events(
+        self,
+        time_min: datetime | None = None,
+        time_max: datetime | None = None,
+        calendar_id: str | None = None,
+        max_results: int = 250,
+        single_events: bool = True,
+        order_by: str = "startTime",
+    ) -> list[Event]:
+        """
+        Get events in a time range.
+
+        Args:
+            time_min: Start of range (default: now)
+            time_max: End of range
+            calendar_id: Calendar ID (default: primary)
+            max_results: Maximum events to return
+            single_events: Expand recurring events
+            order_by: Sort order (startTime or updated)
+
+        Returns:
+            List of Event objects
+        """
+        cal_id = calendar_id or self.calendar_id
+        time_min = time_min or datetime.utcnow()
+
+        request_params = {
+            "calendarId": cal_id,
+            "timeMin": time_min.isoformat() + "Z",
+            "maxResults": max_results,
+            "singleEvents": single_events,
+            "orderBy": order_by,
+        }
+
+        if time_max:
+            request_params["timeMax"] = time_max.isoformat() + "Z"
+
+        response = self.service.events().list(**request_params).execute()
+
+        events = []
+        for event_data in response.get("items", []):
+            events.append(self._parse_event(event_data, cal_id))
+
+        return events
+
+    def get_upcoming(
+        self,
+        days: int = 7,
+        calendar_id: str | None = None,
+        max_results: int = 100,
+    ) -> list[Event]:
+        """
+        Get upcoming events.
+
+        Args:
+            days: Number of days ahead (default: 7)
+            calendar_id: Calendar ID
+            max_results: Maximum events
+
+        Returns:
+            List of upcoming events
+        """
+        time_min = datetime.utcnow()
+        time_max = time_min + timedelta(days=days)
+
+        return self.get_events(
+            time_min=time_min,
+            time_max=time_max,
+            calendar_id=calendar_id,
+            max_results=max_results,
+        )
+
+    def get_today(self, calendar_id: str | None = None) -> list[Event]:
+        """Get today's events."""
+        today = datetime.utcnow().replace(hour=0, minute=0, second=0, microsecond=0)
+        tomorrow = today + timedelta(days=1)
+
+        return self.get_events(time_min=today, time_max=tomorrow, calendar_id=calendar_id)
+
+    def get_event(self, event_id: str, calendar_id: str | None = None) -> Event | None:
+        """Get a specific event by ID."""
+        cal_id = calendar_id or self.calendar_id
+
+        try:
+            event_data = (
+                self.service.events()
+                .get(
+                    calendarId=cal_id,
+                    eventId=event_id,
+                )
+                .execute()
+            )
+            return self._parse_event(event_data, cal_id)
+        except HttpError as e:
+            if e.resp.status == 404:
+                logger.debug(f"Event not found: {event_id}")
+                return None
+            logger.error(f"Error getting event {event_id}: {e}")
+            raise
+        except Exception as e:
+            logger.error(f"Unexpected error getting event {event_id}: {e}")
+            return None
+
+    # ========== Calendars ==========
+
+    def get_calendars(self) -> list[CalendarEntity]:
+        """Get all accessible calendars."""
+        response = self.service.calendarList().list().execute()
+
+        return [CalendarParser.parse_calendar(cal_data) for cal_data in response.get("items", [])]
+
+    # ========== Create/Update ==========
+
+    def create_event(
+        self,
+        summary: str,
+        start: datetime | date,
+        end: datetime | date | None = None,
+        description: str | None = None,
+        location: str | None = None,
+        attendees: list[str] | None = None,
+        calendar_id: str | None = None,
+        all_day: bool = False,
+    ) -> Event:
+        """
+        Create a new event.
+
+        Args:
+            summary: Event title
+            start: Start time (datetime) or date (for all-day)
+            end: End time (default: start + 1 hour)
+            description: Event description
+            location: Event location
+            attendees: List of attendee emails
+            calendar_id: Calendar to create in
+            all_day: Create as all-day event
+
+        Returns:
+            Created Event
+        """
+        cal_id = calendar_id or self.calendar_id
+
+        # Handle all-day events
+        if all_day or isinstance(start, date) and not isinstance(start, datetime):
+            start_body = {
+                "date": start.isoformat() if isinstance(start, date) else start.date().isoformat()
+            }
+            end_date = end or start
+            if isinstance(end_date, datetime):
+                end_date = end_date.date()
+            end_body = {"date": (end_date + timedelta(days=1)).isoformat()}
+        else:
+            if end is None:
+                end = start + timedelta(hours=1)
+            settings = get_settings()
+            tz = settings.default_timezone
+            start_body = {"dateTime": start.isoformat(), "timeZone": tz}
+            end_body = {"dateTime": end.isoformat(), "timeZone": tz}
+
+        event_body = {
+            "summary": summary,
+            "start": start_body,
+            "end": end_body,
+        }
+
+        if description:
+            event_body["description"] = description
+        if location:
+            event_body["location"] = location
+        if attendees:
+            event_body["attendees"] = [{"email": email} for email in attendees]
+
+        created = (
+            self.service.events()
+            .insert(
+                calendarId=cal_id,
+                body=event_body,
+            )
+            .execute()
+        )
+
+        return self._parse_event(created, cal_id)
+
+    def delete_event(self, event_id: str, calendar_id: str | None = None) -> bool:
+        """Delete an event."""
+        cal_id = calendar_id or self.calendar_id
+
+        try:
+            self.service.events().delete(
+                calendarId=cal_id,
+                eventId=event_id,
+            ).execute()
+            logger.info(f"Deleted event {event_id}")
+            return True
+        except HttpError as e:
+            if e.resp.status == 404:
+                logger.warning(f"Event not found for deletion: {event_id}")
+            else:
+                logger.error(f"Error deleting event {event_id}: {e}")
+            return False
+        except Exception as e:
+            logger.error(f"Unexpected error deleting event {event_id}: {e}")
+            return False
+
+    # ========== Parsing ==========
+
+    def _parse_event(self, data: dict, calendar_id: str) -> Event:
+        """Parse Calendar API response to Event object."""
+        return CalendarParser.parse_event(data, calendar_id)

gsuite_calendar/event.py

@@ -0,0 +1,57 @@
+"""Calendar Event entity."""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass
+class Attendee:
+    """Event attendee."""
+
+    email: str
+    name: str | None = None
+    response_status: str = "needsAction"  # needsAction, declined, tentative, accepted
+    organizer: bool = False
+    self_: bool = False
+
+
+@dataclass
+class Event:
+    """
+    Calendar event.
+
+    Represents a single calendar event with all its metadata.
+    """
+
+    id: str
+    summary: str
+    description: str | None = None
+    location: str | None = None
+    start: datetime | None = None
+    end: datetime | None = None
+    all_day: bool = False
+    recurring: bool = False
+    recurrence: list[str] | None = None
+    attendees: list[Attendee] = field(default_factory=list)
+    organizer: str | None = None
+    calendar_id: str = "primary"
+    html_link: str | None = None
+    status: str = "confirmed"  # confirmed, tentative, cancelled
+
+    @property
+    def duration_minutes(self) -> int | None:
+        """Get event duration in minutes."""
+        if self.start and self.end:
+            delta = self.end - self.start
+            return int(delta.total_seconds() / 60)
+        return None
+
+    @property
+    def is_all_day(self) -> bool:
+        """Check if this is an all-day event."""
+        return self.all_day
+
+    @property
+    def is_recurring(self) -> bool:
+        """Check if this is a recurring event."""
+        return self.recurring or bool(self.recurrence)

gsuite_calendar/parser.py

@@ -0,0 +1,119 @@
+"""Calendar response parsers - converts API responses to domain entities."""
+
+from datetime import datetime
+
+from gsuite_calendar.calendar_entity import CalendarEntity
+from gsuite_calendar.event import Attendee, Event
+
+
+class CalendarParser:
+    """Parser for Calendar API responses."""
+
+    @staticmethod
+    def parse_event(data: dict, calendar_id: str) -> Event:
+        """
+        Parse Calendar API response to Event entity.
+
+        Args:
+            data: Raw API response dict
+            calendar_id: Calendar ID the event belongs to
+
+        Returns:
+            Event entity
+        """
+        # Parse start/end times
+        start_data = data.get("start", {})
+        end_data = data.get("end", {})
+
+        all_day = "date" in start_data
+
+        if all_day:
+            start = CalendarParser._parse_date(start_data.get("date"))
+            end = CalendarParser._parse_date(end_data.get("date"))
+        else:
+            start = CalendarParser._parse_datetime(start_data.get("dateTime"))
+            end = CalendarParser._parse_datetime(end_data.get("dateTime"))
+
+        # Parse attendees
+        attendees = [
+            CalendarParser.parse_attendee(att_data) for att_data in data.get("attendees", [])
+        ]
+
+        return Event(
+            id=data["id"],
+            summary=data.get("summary", ""),
+            description=data.get("description"),
+            location=data.get("location"),
+            start=start,
+            end=end,
+            all_day=all_day,
+            recurring="recurringEventId" in data,
+            recurrence=data.get("recurrence"),
+            attendees=attendees,
+            organizer=data.get("organizer", {}).get("email"),
+            calendar_id=calendar_id,
+            html_link=data.get("htmlLink"),
+            status=data.get("status", "confirmed"),
+        )
+
+    @staticmethod
+    def parse_attendee(data: dict) -> Attendee:
+        """
+        Parse attendee data to Attendee entity.
+
+        Args:
+            data: Raw attendee dict from API
+
+        Returns:
+            Attendee entity
+        """
+        return Attendee(
+            email=data.get("email", ""),
+            name=data.get("displayName"),
+            response_status=data.get("responseStatus", "needsAction"),
+            organizer=data.get("organizer", False),
+            self_=data.get("self", False),
+        )
+
+    @staticmethod
+    def parse_calendar(data: dict) -> CalendarEntity:
+        """
+        Parse Calendar API response to CalendarEntity.
+
+        Args:
+            data: Raw API response dict
+
+        Returns:
+            CalendarEntity
+        """
+        return CalendarEntity(
+            id=data["id"],
+            summary=data.get("summary", ""),
+            description=data.get("description"),
+            time_zone=data.get("timeZone"),
+            primary=data.get("primary", False),
+            access_role=data.get("accessRole", "reader"),
+            background_color=data.get("backgroundColor"),
+            foreground_color=data.get("foregroundColor"),
+        )
+
+    @staticmethod
+    def _parse_datetime(dt_string: str | None) -> datetime | None:
+        """Parse ISO datetime string to datetime object."""
+        if not dt_string:
+            return None
+        try:
+            # Handle Z suffix and timezone offset
+            return datetime.fromisoformat(dt_string.replace("Z", "+00:00"))
+        except (ValueError, TypeError):
+            return None
+
+    @staticmethod
+    def _parse_date(date_string: str | None) -> datetime | None:
+        """Parse ISO date string to datetime object."""
+        if not date_string:
+            return None
+        try:
+            return datetime.fromisoformat(date_string)
+        except (ValueError, TypeError):
+            return None

gsuite_core/__init__.py

@@ -0,0 +1,62 @@
+"""Google Suite Core - Shared auth, config, and utilities."""
+
+__version__ = "0.1.0"
+
+from gsuite_core.api_utils import api_call, api_call_optional, map_http_error
+from gsuite_core.auth.oauth import GoogleAuth
+from gsuite_core.auth.scopes import Scopes
+from gsuite_core.config import Settings, get_settings
+from gsuite_core.exceptions import (
+    APIError,
+    AuthenticationError,
+    ConfigurationError,
+    CredentialsNotFoundError,
+    GSuiteError,
+    NotAuthenticatedError,
+    NotFoundError,
+    PermissionDeniedError,
+    QuotaExceededError,
+    RateLimitError,
+    TokenExpiredError,
+    TokenRefreshError,
+    ValidationError,
+)
+from gsuite_core.storage import SQLiteTokenStore, TokenStore
+
+__all__ = [
+    # Auth
+    "GoogleAuth",
+    "Scopes",
+    # Config
+    "Settings",
+    "get_settings",
+    # API Utils
+    "api_call",
+    "api_call_optional",
+    "map_http_error",
+    # Storage
+    "TokenStore",
+    "SQLiteTokenStore",
+    # Exceptions
+    "GSuiteError",
+    "AuthenticationError",
+    "CredentialsNotFoundError",
+    "TokenExpiredError",
+    "TokenRefreshError",
+    "NotAuthenticatedError",
+    "APIError",
+    "RateLimitError",
+    "QuotaExceededError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "ValidationError",
+    "ConfigurationError",
+]
+
+# Conditionally export SecretManagerTokenStore
+try:
+    from gsuite_core.storage import SecretManagerTokenStore
+
+    __all__.append("SecretManagerTokenStore")
+except ImportError:
+    pass