tessl/pypi-gcsa

Simple API for Google Calendar management

—

Pending

Overview

Eval results

Files

Calendar Management

Name: tessl/pypi-gcsa
Author: tessl

GCSA provides comprehensive calendar management through the Calendar and CalendarListEntry classes. These classes handle calendar creation, configuration, user-specific settings, and calendar list management for organizing multiple calendars.

Package Information

from gcsa.calendar import Calendar, CalendarListEntry, NotificationType, AccessRoles
from gcsa.google_calendar import GoogleCalendar

Calendar Class

Basic Calendar Creation

class Calendar:
    def __init__(
        self,
        summary: str,
        calendar_id = None,
        description = None,
        location = None,
        timezone = None,
        allowed_conference_solution_types = None,
        _etag = None,
        _kind = None
    ):
        """
        Create a new calendar.
        
        :param summary: Calendar name/title (required)
        :param calendar_id: Unique identifier (auto-generated if not provided)
        :param description: Calendar description
        :param location: Calendar location
        :param timezone: Calendar time zone (e.g., 'America/New_York')
        :param allowed_conference_solution_types: List of allowed conference solutions
        """

Calendar Properties

@property
def id(self) -> str:
    """Unique identifier for the calendar."""

Calendar Conversion Method

def to_calendar_list_entry(self):
    """
    Convert Calendar to CalendarListEntry.
    
    :return: CalendarListEntry object with calendar data
    """

CalendarListEntry Class

Calendar List Entry Creation

class CalendarListEntry(Calendar):
    def __init__(
        self,
        calendar_id: str,
        summary_override = None,
        color_id = None,
        background_color = None,
        foreground_color = None,
        hidden = None,
        selected = None,
        default_reminders = None,
        notification_types = None,
        primary = None,
        deleted = None,
        access_role = None,
        summary = None,
        description = None,
        location = None,
        timezone = None,
        conference_properties = None,
        _etag = None,
        _kind = None
    ):
        """
        Create a calendar list entry with user-specific settings.
        
        :param calendar_id: Unique calendar identifier (required)
        :param summary_override: Override for calendar title display
        :param color_id: Color ID for calendar display (1-24)
        :param background_color: Custom background color (hex format)
        :param foreground_color: Custom foreground color (hex format)  
        :param hidden: Whether calendar is hidden from list
        :param selected: Whether calendar is selected/visible
        :param default_reminders: List of default reminder objects
        :param notification_types: List of notification type strings
        :param primary: Whether this is the primary calendar (read-only)
        :param deleted: Whether calendar is deleted (read-only)
        :param access_role: User's access role for this calendar (read-only)
        :param summary: Calendar summary/title
        :param description: Calendar description
        :param location: Calendar location
        :param timezone: Calendar time zone
        :param conference_properties: Conference solution properties
        """

Calendar List Entry Properties

@property
def color_id(self) -> str:
    """Color ID for the calendar (1-24)."""

@color_id.setter
def color_id(self, value: str):
    """
    Set color ID and reset custom colors.
    
    :param value: Color ID string (1-24)
    """

Calendar Service Methods

Calendar CRUD 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 and all its events.
    
    :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)
    """

Calendar List Operations

def get_calendar_list(
    self,
    min_access_role = None,
    max_results = None,
    page_token = None,
    show_deleted = None,
    show_hidden = None,
    sync_token = None
):
    """
    Retrieve the user's calendar list.
    
    :param min_access_role: Minimum access role filter ('owner', 'reader', etc.)
    :param max_results: Maximum number of calendars to return
    :param page_token: Token for pagination
    :param show_deleted: Whether to include deleted calendars
    :param show_hidden: Whether to include hidden calendars
    :param sync_token: Token for incremental sync
    :return: Generator yielding CalendarListEntry objects
    """

def get_calendar_list_entry(self, calendar_id: str):
    """
    Get specific calendar list entry by ID.
    
    :param calendar_id: Calendar identifier
    :return: CalendarListEntry object
    """

def add_calendar_list_entry(self, calendar_list_entry):
    """
    Add an existing calendar to the user's calendar list.
    
    :param calendar_list_entry: CalendarListEntry object to add
    :return: Added CalendarListEntry object
    """

def update_calendar_list_entry(
    self,
    calendar_list_entry,
    calendar_id = None,
    color_rgb_format = None
):
    """
    Update user-specific settings for a calendar.
    
    :param calendar_list_entry: CalendarListEntry object with changes
    :param calendar_id: Calendar ID (defaults to entry.id)
    :param color_rgb_format: Whether to use RGB format for colors
    :return: Updated CalendarListEntry object
    """

def delete_calendar_list_entry(self, calendar_id: str):
    """
    Remove a calendar from the user's calendar list.
    
    :param calendar_id: Calendar ID to remove from list
    """

Calendar Constants

Notification Types

class NotificationType:
    EVENT_CREATION = "eventCreation"       # New event created
    EVENT_CHANGE = "eventChange"           # Event modified
    EVENT_CANCELLATION = "eventCancellation" # Event cancelled
    EVENT_RESPONSE = "eventResponse"       # Attendee responded
    AGENDA = "agenda"                      # Daily agenda

Access Roles

class AccessRoles:
    FREE_BUSY_READER = "freeBusyReader"   # Can see free/busy information
    READER = "reader"                     # Can read events
    WRITER = "writer"                     # Can create and modify events  
    OWNER = "owner"                       # Full control over calendar

Basic Usage Examples

Creating and Managing Calendars

from gcsa.google_calendar import GoogleCalendar
from gcsa.calendar import Calendar, CalendarListEntry
from gcsa.reminders import EmailReminder

gc = GoogleCalendar()

# Create a new calendar
project_calendar = Calendar(
    summary="Project Alpha",
    description="Calendar for Project Alpha milestones and meetings",
    location="Building A",
    timezone="America/New_York"
)
created_calendar = gc.add_calendar(project_calendar)
print(f"Created calendar: {created_calendar.id}")

# Update calendar metadata
created_calendar.description = "Updated: Project Alpha calendar with all events"
gc.update_calendar(created_calendar)

# Get calendar details
calendar = gc.get_calendar(created_calendar.id)
print(f"Calendar: {calendar.summary} in {calendar.timezone}")

Working with Calendar Lists

from gcsa.google_calendar import GoogleCalendar
from gcsa.calendar import CalendarListEntry, NotificationType

gc = GoogleCalendar()

# Get all calendars in user's list
print("User's calendars:")
for calendar_entry in gc.get_calendar_list():
    print(f"- {calendar_entry.summary} ({calendar_entry.access_role})")
    if calendar_entry.primary:
        print("  [PRIMARY CALENDAR]")

# Get specific calendar list entry
calendar_entry = gc.get_calendar_list_entry("calendar_id")

Customizing Calendar Appearance

from gcsa.google_calendar import GoogleCalendar
from gcsa.calendar import CalendarListEntry

gc = GoogleCalendar()

# Update calendar display settings
calendar_entry = gc.get_calendar_list_entry("calendar_id")
calendar_entry.color_id = "5"  # Yellow color
calendar_entry.summary_override = "My Project Calendar"
calendar_entry.hidden = False
calendar_entry.selected = True

gc.update_calendar_list_entry(calendar_entry)

# Use custom colors (instead of predefined color IDs)
calendar_entry.background_color = "#FF5722"  # Deep Orange
calendar_entry.foreground_color = "#FFFFFF"  # White
calendar_entry.color_id = None  # Clear predefined color
gc.update_calendar_list_entry(calendar_entry)

Setting Default Reminders

from gcsa.google_calendar import GoogleCalendar
from gcsa.calendar import CalendarListEntry
from gcsa.reminders import EmailReminder, PopupReminder

gc = GoogleCalendar()

# Set default reminders for a calendar
calendar_entry = gc.get_calendar_list_entry("calendar_id")
calendar_entry.default_reminders = [
    EmailReminder(minutes_before_start=60),    # 1 hour email reminder
    PopupReminder(minutes_before_start=15)     # 15 minute popup reminder
]

gc.update_calendar_list_entry(calendar_entry)

Notification Settings

from gcsa.google_calendar import GoogleCalendar
from gcsa.calendar import CalendarListEntry, NotificationType

gc = GoogleCalendar()

# Configure calendar notifications
calendar_entry = gc.get_calendar_list_entry("calendar_id")
calendar_entry.notification_types = [
    NotificationType.EVENT_CREATION,
    NotificationType.EVENT_CHANGE,
    NotificationType.EVENT_RESPONSE
]

gc.update_calendar_list_entry(calendar_entry)

Calendar Colors

Calendars support 24 predefined colors (color_id 1-24):

from gcsa.google_calendar import GoogleCalendar

gc = GoogleCalendar()

# Get available calendar colors
calendar_colors = gc.list_calendar_colors()
for color_id, color_info in calendar_colors.items():
    print(f"Color {color_id}: {color_info['background']} / {color_info['foreground']}")

# Apply color to calendar
calendar_entry = gc.get_calendar_list_entry("calendar_id")
calendar_entry.color_id = "10"  # Apply specific color
gc.update_calendar_list_entry(calendar_entry)

Managing Multiple Project Calendars

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

gc = GoogleCalendar()

# Create calendars for different projects
projects = [
    {"name": "Project Alpha", "color": "1"},
    {"name": "Project Beta", "color": "2"}, 
    {"name": "Project Gamma", "color": "3"}
]

created_calendars = []
for project in projects:
    # Create calendar
    calendar = Calendar(
        summary=project["name"],
        description=f"Calendar for {project['name']} events",
        timezone="America/New_York"
    )
    created_calendar = gc.add_calendar(calendar)
    
    # Configure display settings
    calendar_entry = gc.get_calendar_list_entry(created_calendar.id)
    calendar_entry.color_id = project["color"]
    gc.update_calendar_list_entry(calendar_entry)
    
    created_calendars.append(created_calendar)
    print(f"Created: {project['name']} ({created_calendar.id})")

# List all project calendars
print("\nProject calendars:")
for cal_entry in gc.get_calendar_list():
    if cal_entry.summary and "Project" in cal_entry.summary:
        print(f"- {cal_entry.summary} (Color: {cal_entry.color_id})")

Calendar Sharing Setup

from gcsa.google_calendar import GoogleCalendar
from gcsa.calendar import Calendar
from gcsa.acl import AccessControlRule, ACLRole, ACLScopeType

gc = GoogleCalendar()

# Create a shared team calendar
team_calendar = Calendar(
    summary="Team Calendar",
    description="Shared calendar for team events",
    timezone="America/New_York"
)
created_calendar = gc.add_calendar(team_calendar)

# Add sharing permissions (see access-control.md for details)
# Make calendar public for read access
public_rule = AccessControlRule(
    role=ACLRole.READER,
    scope_type=ACLScopeType.DEFAULT
)
gc.add_acl_rule(public_rule, calendar_id=created_calendar.id)

Calendar Cleanup

from gcsa.google_calendar import GoogleCalendar

gc = GoogleCalendar()

# Clear all events from a calendar
gc.clear_calendar("calendar_id")

# Remove calendar from user's list (but keep the calendar)
gc.delete_calendar_list_entry("calendar_id")

# Delete calendar completely (only for owned calendars)
gc.delete_calendar("calendar_id")

Working with Primary Calendar

from gcsa.google_calendar import GoogleCalendar

# Primary calendar is the user's main calendar
gc = GoogleCalendar()  # Uses 'primary' as default calendar

# Get primary calendar details
primary_calendar = gc.get_calendar('primary')
print(f"Primary calendar: {primary_calendar.summary}")

# Get primary calendar list entry for customization
primary_entry = gc.get_calendar_list_entry('primary')
print(f"Primary calendar timezone: {primary_entry.timezone}")

# Note: Cannot delete primary calendar, only clear its events
gc.clear_calendar('primary')  # Removes all events from primary calendar

Error Handling for Calendars

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

gc = GoogleCalendar()

try:
    # Attempt to get non-existent calendar
    calendar = gc.get_calendar("invalid_calendar_id")
except HttpError as e:
    if e.resp.status == 404:
        print("Calendar not found")
    elif e.resp.status == 403:
        print("Access denied to calendar")
    else:
        print(f"API error: {e}")

try:
    # Attempt to delete primary calendar (not allowed)
    gc.delete_calendar("primary")
except HttpError as e:
    print(f"Cannot delete primary calendar: {e}")

The Calendar and CalendarListEntry classes provide comprehensive calendar management capabilities, allowing users to create, organize, customize, and share calendars while maintaining fine-grained control over display settings, notifications, and access permissions.

Install with Tessl CLI