or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

access-control.mdattendees.mdcalendars.mdconferences.mdcore-operations.mdevents.mdfree-busy.mdindex.mdrecurrence.mdreminders.md
tile.json

tessl/pypi-gcsa

Simple API for Google Calendar management

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/gcsa@2.5.x

To install, run

npx @tessl/cli install tessl/pypi-gcsa@2.5.0

index.mddocs/

GCSA - Google Calendar Simple API

A Python library that provides a simple, object-oriented interface to the Google Calendar API. GCSA abstracts away the complexity of the official Google Calendar API while maintaining full functionality, offering intuitive classes and methods for managing calendars, events, attendees, reminders, and access controls.

Package Information

  • Package Name: gcsa
  • Language: Python
  • Installation: pip install gcsa
  • Dependencies: google-api-python-client, google-auth-httplib2, google-auth-oauthlib, python-dateutil, beautiful_date, tzlocal

Core Imports

All classes and functions must be imported directly from their respective modules since __init__.py files are empty:

from gcsa.google_calendar import GoogleCalendar
from gcsa.event import Event, Visibility, Transparency
from gcsa.calendar import Calendar, CalendarListEntry
from gcsa.attendee import Attendee, ResponseStatus
from gcsa.attachment import Attachment
from gcsa.reminders import EmailReminder, PopupReminder
from gcsa.recurrence import Recurrence, DAILY, WEEKLY, MONTHLY

Basic Usage

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

# Initialize the Google Calendar client
gc = GoogleCalendar()

# Create a simple 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"
)

# Add the event to the calendar
gc.add_event(event)

# List upcoming events
for event in gc.get_events(time_min=datetime.now()):
    print(f"{event.summary}: {event.start}")
    
# Get a specific event
event = gc.get_event("event_id")

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

# Delete an event
gc.delete_event("event_id")

Architecture

GCSA uses a service-oriented architecture with clear separation of concerns:

  • GoogleCalendar: Main service class that inherits from all service mixins
  • Data Models: Rich Python objects representing calendar entities (Event, Calendar, Attendee, etc.)
  • Service Classes: Specialized API interaction classes for different Google Calendar resources
  • Serializers: Handle conversion between Python objects and Google Calendar API format
  • Utilities: Helper functions for date/time handling and data manipulation

The library provides both high-level convenience methods and direct access to Google Calendar API features, making it suitable for simple automation scripts and complex calendar management applications.

Capabilities

Core Calendar Operations

Main GoogleCalendar client and basic calendar management operations including authentication, calendar CRUD operations, and event management.

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
    ): ...
    
    def get_events(self, **kwargs): ...
    def add_event(self, event, **kwargs): ...
    def update_event(self, event, **kwargs): ...
    def delete_event(self, event_id, **kwargs): ...

Core Calendar Operations

Event Management

Comprehensive event handling including creation, scheduling, recurring events, and event metadata management.

class Event:
    def __init__(
        self,
        summary,
        start = None,
        end = None,
        timezone = None,
        event_id = None,
        description = None,
        location = None,
        recurrence = None,
        color_id = None,
        visibility = None,
        attendees = None,
        attachments = None,
        conference_solution = None,
        reminders = None
    ): ...
    
    def add_attendee(self, attendee): ...
    def add_attachment(self, file_url, title, mime_type): ...
    def add_email_reminder(self, minutes_before_start, days_before=None, at=None): ...
    def add_popup_reminder(self, minutes_before_start, days_before=None, at=None): ...

Event Management

Calendar Management

Calendar creation, configuration, and calendar list management with user-specific settings and permissions.

class Calendar:
    def __init__(
        self,
        summary,
        calendar_id = None,
        description = None,
        location = None,
        timezone = None,
        allowed_conference_solution_types = None
    ): ...

class CalendarListEntry:
    def __init__(
        self,
        calendar_id,
        summary_override = None,
        color_id = None,
        background_color = None,
        foreground_color = None,
        hidden = None,
        selected = None,
        default_reminders = None,
        notification_types = None
    ): ...

Calendar Management

Attendees and People

Managing event attendees, organizers, and participant information including RSVP status and permissions.

class Attendee:
    def __init__(
        self,
        email,
        display_name = None,
        comment = None,
        optional = None,
        is_resource = None,
        additional_guests = None
    ): ...

class Person:
    def __init__(
        self,
        email,
        display_name = None
    ): ...

Attendees and People

Recurrence and Scheduling

Advanced scheduling features including recurring events, recurrence rules, and complex scheduling patterns.

class Recurrence:
    @staticmethod
    def rule(
        freq,
        until = None,
        count = None,
        interval = None,
        by_month = None,
        by_month_day = None,
        by_year_day = None,
        by_week_no = None,
        by_weekday = None,
        by_hour = None,
        by_minute = None,
        by_second = None,
        by_set_pos = None,
        week_start = None
    ): ...
    
    @staticmethod
    def dates(*dates): ...
    @staticmethod
    def times(*datetimes): ...

Recurrence and Scheduling

Reminders and Notifications

Event reminder system supporting email and popup notifications with flexible timing options.

class EmailReminder:
    def __init__(
        self,
        minutes_before_start = None,
        days_before = None,
        at = None
    ): ...

class PopupReminder:
    def __init__(
        self,
        minutes_before_start = None,
        days_before = None,
        at = None
    ): ...

Reminders and Notifications

Conference Solutions

Integration with video conferencing platforms including Google Meet, Hangouts, and third-party solutions.

class ConferenceSolution:
    def __init__(
        self,
        entry_points = None,
        solution_type = None,
        name = None,
        icon_uri = None,
        conference_id = None,
        signature = None,
        notes = None
    ): ...

class ConferenceSolutionCreateRequest:
    def __init__(
        self,
        solution_type,
        request_id = None
    ): ...

Conference Solutions

Access Control and Permissions

Calendar sharing, access control rules, and permission management for collaborative calendar usage.

class AccessControlRule:
    def __init__(
        self,
        role,
        scope_type,
        acl_id = None,
        scope_value = None
    ): ...

Access Control and Permissions

Free/Busy and Availability

Checking calendar availability, free/busy time queries, and scheduling conflict detection.

class FreeBusy:
    def __init__(
        self,
        time_min,
        time_max,
        groups = None,
        calendars = None,
        groups_errors = None,
        calendars_errors = None
    ): ...

Free/Busy and Availability

Core Types

# Event visibility options
class Visibility:
    DEFAULT = "default"
    PUBLIC = "public"
    PRIVATE = "private"

# Event transparency options  
class Transparency:
    OPAQUE = "opaque"
    TRANSPARENT = "transparent"

# Attendee response status
class ResponseStatus:
    NEEDS_ACTION = "needsAction"
    DECLINED = "declined"
    TENTATIVE = "tentative"
    ACCEPTED = "accepted"

# Conference solution types
class SolutionType:
    HANGOUT = "hangout"
    NAMED_HANGOUT = "namedHangout"
    HANGOUTS_MEET = "hangoutsMeet"
    ADD_ON = "addOn"

# ACL roles and scope types
class ACLRole:
    NONE = "none"
    FREE_BUSY_READER = "freeBusyReader"
    READER = "reader"
    WRITER = "writer"
    OWNER = "owner"

class ACLScopeType:
    DEFAULT = "default"
    USER = "user"
    GROUP = "group"
    DOMAIN = "domain"

# Recurrence frequency constants
SECONDLY = "SECONDLY"
MINUTELY = "MINUTELY"
HOURLY = "HOURLY"
DAILY = "DAILY"
WEEKLY = "WEEKLY"
MONTHLY = "MONTHLY"
YEARLY = "YEARLY"

# Day constants for recurrence
SUNDAY = "SU"
MONDAY = "MO"
TUESDAY = "TU"
WEDNESDAY = "WE"
THURSDAY = "TH"
FRIDAY = "FR"
SATURDAY = "SA"