tessl/pypi-gcsa

Simple API for Google Calendar management

—

Pending

Overview

Eval results

Files

Core Calendar Operations

Name: tessl/pypi-gcsa
Author: tessl

The GoogleCalendar class is the main entry point for interacting with the Google Calendar API. It provides authentication, basic calendar operations, and serves as the primary client for all calendar management tasks.

Package Information

from gcsa.google_calendar import GoogleCalendar

GoogleCalendar Client

Authentication and Initialization

class GoogleCalendar:
    def __init__(
        self,
        default_calendar: str = 'primary',
        *,
        credentials = None,
        credentials_path = None,
        token_path = None,
        save_token: bool = True,
        read_only: bool = False,
        authentication_flow_host: str = 'localhost',
        authentication_flow_port: int = 8080,
        authentication_flow_bind_addr = None,
        open_browser = None
    ):
        """
        Initialize GoogleCalendar client with authentication options.
        
        :param default_calendar: Default calendar ID to use for operations ('primary' for user's main calendar)
        :param credentials: Pre-configured credentials object
        :param credentials_path: Path to credentials JSON file
        :param token_path: Path to store/load authentication token
        :param save_token: Whether to save authentication token for reuse
        :param read_only: Whether to request read-only access
        :param authentication_flow_host: Host for OAuth flow
        :param authentication_flow_port: Port for OAuth flow
        :param authentication_flow_bind_addr: Bind address for OAuth flow
        :param open_browser: Whether to automatically open browser for authentication
        """

Basic Event Operations

def get_events(
    self,
    calendar_id = None,
    time_min = None,
    time_max = None,
    time_zone = None,
    single_events = None,
    order_by = None,
    page_token = None,
    max_results = None,
    show_deleted = None,
    show_hidden_invitations = None,
    updated_min = None,
    sync_token = None,
    private_extended_property = None,
    shared_extended_property = None,
    q = None
):
    """
    Retrieve events from calendar with optional filtering and pagination.
    
    :param calendar_id: Calendar ID to query (defaults to default_calendar)
    :param time_min: Lower bound for event start time (datetime or RFC3339 string)
    :param time_max: Upper bound for event start time (datetime or RFC3339 string)
    :param time_zone: Time zone for returned times
    :param single_events: Whether to expand recurring events into instances
    :param order_by: Sort order ('startTime' or 'updated')
    :param page_token: Token for pagination
    :param max_results: Maximum number of events to return
    :param show_deleted: Whether to include deleted events
    :param show_hidden_invitations: Whether to include hidden invitations
    :param updated_min: Lower bound for last modification time
    :param sync_token: Token for incremental sync
    :param private_extended_property: Private extended property filter
    :param shared_extended_property: Shared extended property filter
    :param q: Free text search terms
    :return: Generator yielding Event objects
    """

def get_event(self, event_id: str, calendar_id = None):
    """
    Retrieve a specific event by ID.
    
    :param event_id: Unique identifier for the event
    :param calendar_id: Calendar ID (defaults to default_calendar)
    :return: Event object
    """

def add_event(self, event, calendar_id = None, send_updates = None):
    """
    Add a new event to the calendar.
    
    :param event: Event object to add
    :param calendar_id: Calendar ID (defaults to default_calendar)
    :param send_updates: Whether to send notifications ('all', 'externalOnly', 'none')
    :return: Created Event object with assigned ID
    """

def update_event(self, event, calendar_id = None, send_updates = None):
    """
    Update an existing event.
    
    :param event: Event object with changes
    :param calendar_id: Calendar ID (defaults to default_calendar)
    :param send_updates: Whether to send notifications ('all', 'externalOnly', 'none')
    :return: Updated Event object
    """

def delete_event(self, event_id: str, calendar_id = None, send_updates = None):
    """
    Delete an event from the calendar.
    
    :param event_id: ID of event to delete
    :param calendar_id: Calendar ID (defaults to default_calendar)
    :param send_updates: Whether to send notifications ('all', 'externalOnly', 'none')
    """

Advanced Event Operations

def get_instances(
    self,
    event,
    time_min = None,
    time_max = None,
    time_zone = None,
    max_results = None,
    order_by = None,
    page_token = None,
    show_deleted = None,
    original_start = None
):
    """
    Get instances of a recurring event.
    
    :param event: Recurring event object or event ID
    :param time_min: Lower bound for instance start time
    :param time_max: Upper bound for instance start time
    :param time_zone: Time zone for returned times
    :param max_results: Maximum number of instances to return
    :param order_by: Sort order ('startTime' or 'updated')
    :param page_token: Token for pagination
    :param show_deleted: Whether to include deleted instances
    :param original_start: Original start time for recurring event modifications
    :return: Generator yielding Event instances
    """

def add_quick_event(self, quick_add_text: str, calendar_id = None):
    """
    Quickly add an event using natural language.
    
    :param quick_add_text: Natural language description of event
    :param calendar_id: Calendar ID (defaults to default_calendar)
    :return: Created Event object
    """

def import_event(self, event, calendar_id = None):
    """
    Import an event into the calendar.
    
    :param event: Event object to import
    :param calendar_id: Calendar ID (defaults to default_calendar)
    :return: Imported Event object
    """

def move_event(
    self,
    event_id: str,
    destination_calendar_id: str,
    calendar_id = None,
    send_updates = None
):
    """
    Move an event to a different calendar.
    
    :param event_id: ID of event to move
    :param destination_calendar_id: Target calendar ID
    :param calendar_id: Source calendar ID (defaults to default_calendar)
    :param send_updates: Whether to send notifications ('all', 'externalOnly', 'none')
    :return: Moved Event object
    """

Calendar Management Operations

def get_calendar(self, calendar_id: str):
    """
    Retrieve calendar metadata by ID.
    
    :param calendar_id: Unique identifier for the calendar
    :return: Calendar object
    """

def add_calendar(self, calendar):
    """
    Create a new secondary calendar.
    
    :param calendar: Calendar object to create
    :return: Created Calendar object with assigned ID
    """

def update_calendar(self, calendar, calendar_id = None):
    """
    Update calendar metadata.
    
    :param calendar: Calendar object with changes
    :param calendar_id: Calendar ID (defaults to calendar.id)
    :return: Updated Calendar object
    """

def delete_calendar(self, calendar_id: str):
    """
    Delete a secondary calendar.
    
    :param calendar_id: ID of calendar to delete
    """

def clear_calendar(self, calendar_id = None):
    """
    Remove all events from a calendar.
    
    :param calendar_id: Calendar ID (defaults to default_calendar)
    """

def clear(self):
    """
    Alias for clear_calendar() using default calendar.
    """

Iterator and Indexing Support

def __iter__(self):
    """
    Iterate over events in the default calendar.
    
    :return: Generator yielding Event objects
    """

def __getitem__(self, key):
    """
    Access events by index or slice.
    
    :param key: Integer index or slice object
    :return: Event object or list of Event objects
    """

Authentication Examples

Basic Authentication

from gcsa.google_calendar import GoogleCalendar

# Default authentication (uses 'credentials.json' and saves token)
gc = GoogleCalendar()

# Specify custom credentials file
gc = GoogleCalendar(credentials_path='path/to/credentials.json')

# Read-only access
gc = GoogleCalendar(read_only=True)

Advanced Authentication

from google.oauth2.credentials import Credentials
from gcsa.google_calendar import GoogleCalendar

# Use pre-configured credentials
creds = Credentials.from_authorized_user_info(info)
gc = GoogleCalendar(credentials=creds)

# Custom OAuth flow settings
gc = GoogleCalendar(
    authentication_flow_host='0.0.0.0',
    authentication_flow_port=9090,
    open_browser=False
)

Basic Usage Examples

Simple Event Management

from gcsa.google_calendar import GoogleCalendar
from gcsa.event import Event
from datetime import datetime, timedelta

# Initialize client
gc = GoogleCalendar()

# Create and add an event
event = Event(
    summary="Team Meeting",
    start=datetime(2024, 1, 15, 10, 0),
    end=datetime(2024, 1, 15, 11, 0),
    description="Weekly team sync",
    location="Conference Room A"
)
created_event = gc.add_event(event)
print(f"Created event: {created_event.id}")

# Get upcoming events
today = datetime.now()
next_week = today + timedelta(days=7)

for event in gc.get_events(time_min=today, time_max=next_week):
    print(f"{event.summary}: {event.start}")

# Update an event
event.summary = "Updated Team Meeting"
gc.update_event(event)

# Delete an event
gc.delete_event(created_event.id)

Working with Multiple Calendars

from gcsa.google_calendar import GoogleCalendar
from gcsa.calendar import Calendar

gc = GoogleCalendar()

# Create a new calendar
new_calendar = Calendar(
    summary="Project Calendar",
    description="Calendar for project events",
    timezone="America/New_York"
)
created_calendar = gc.add_calendar(new_calendar)

# Use specific calendar for events
gc_project = GoogleCalendar(default_calendar=created_calendar.id)

# Add event to specific calendar
project_event = Event(
    summary="Project Milestone",
    start=datetime(2024, 2, 1, 9, 0),
    end=datetime(2024, 2, 1, 10, 0)
)
gc_project.add_event(project_event)

Advanced Event Queries

from datetime import datetime, timedelta

gc = GoogleCalendar()

# Search events by text
meetings = gc.get_events(q="meeting")

# Get events with pagination
events_page1 = gc.get_events(max_results=10)
# Get next page using page_token from previous response

# Get only updated events since last sync
updated_events = gc.get_events(
    updated_min=datetime(2024, 1, 1),
    show_deleted=True
)

# Get events ordered by update time
recent_events = gc.get_events(
    order_by="updated",
    max_results=20
)

Error Handling

from gcsa.google_calendar import GoogleCalendar
from googleapiclient.errors import HttpError

gc = GoogleCalendar()

try:
    event = gc.get_event("invalid_event_id")
except HttpError as e:
    if e.resp.status == 404:
        print("Event not found")
    else:
        print(f"API error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Send Updates Constants

class SendUpdatesMode:
    ALL = "all"                    # Send notifications to all attendees
    EXTERNAL_ONLY = "externalOnly" # Send only to external attendees
    NONE = "none"                  # Do not send notifications

Integration with Calendar List

from gcsa.google_calendar import GoogleCalendar

gc = GoogleCalendar()

# Get user's calendar list
calendar_list = gc.get_calendar_list()
for cal_entry in calendar_list:
    print(f"Calendar: {cal_entry.summary} (ID: {cal_entry.id})")
    
    # Get events from this specific calendar
    events = gc.get_events(calendar_id=cal_entry.id, max_results=5)
    for event in events:
        print(f"  Event: {event.summary}")

The GoogleCalendar class serves as the central hub for all calendar operations, inheriting functionality from specialized service classes for events, calendars, ACL, free/busy queries, and more. It provides both high-level convenience methods and access to advanced Google Calendar API features.

Install with Tessl CLI