tessl/pypi-gcsa

Simple API for Google Calendar management

—

Pending

Overview

Eval results

Files

Event Management

Name: tessl/pypi-gcsa
Author: tessl

The Event class is the core data model for calendar events in GCSA. It provides comprehensive support for event creation, modification, recurring events, attendee management, and rich metadata handling.

Package Information

from gcsa.event import Event, Visibility, Transparency

Event Class

Basic Event Creation

class Event:
    def __init__(
        self,
        summary: str,
        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,
        transparency = None,
        status = None,
        created = None,
        updated = None,
        creator = None,
        organizer = None,
        guests_can_invite_others = None,
        guests_can_modify = None,
        guests_can_see_other_guests = None,
        private_copy = None,
        locked = None,
        source = None,
        end_time_unspecified = None,
        sequence = None,
        hangout_link = None,
        gadget = None,
        anyone_can_add_self = None,
        original_start_time = None,
        extended_properties = None,
        _i_cal_uid = None,
        _html_link = None,
        _recurring_event_id = None,
        _etag = None
    ):
        """
        Create a new calendar event.
        
        :param summary: Event title/name (required)
        :param start: Event start time (datetime object or date for all-day events)
        :param end: Event end time (datetime object or date for all-day events)
        :param timezone: Time zone for event times (string like 'America/New_York')
        :param event_id: Unique identifier (auto-generated if not provided)
        :param description: Event description/details
        :param location: Event location
        :param recurrence: List of recurrence rules (RRULE, RDATE, EXRULE, EXDATE)
        :param color_id: Event color ID (1-11)
        :param visibility: Event visibility ('default', 'public', 'private')
        :param attendees: List of Attendee objects
        :param attachments: List of Attachment objects
        :param conference_solution: ConferenceSolution or ConferenceSolutionCreateRequest
        :param reminders: List of Reminder objects
        :param transparency: Whether event blocks time ('opaque', 'transparent')
        :param status: Event status ('confirmed', 'tentative', 'cancelled')
        :param created: Creation timestamp
        :param updated: Last modification timestamp
        :param creator: Person who created the event
        :param organizer: Event organizer
        :param guests_can_invite_others: Whether guests can invite others
        :param guests_can_modify: Whether guests can modify event
        :param guests_can_see_other_guests: Whether guests can see other attendees
        :param private_copy: Whether this is a private copy for the user
        :param locked: Whether event is locked against changes
        :param source: Source information for imported events
        :param end_time_unspecified: Whether end time is unspecified
        :param sequence: Event sequence number for updates
        :param hangout_link: Hangout video conference link
        :param gadget: Gadget/add-on information
        :param anyone_can_add_self: Whether anyone can add themselves as attendee
        :param original_start_time: Original start time for recurring event instances
        :param extended_properties: Extended properties dictionary
        """

Event Properties

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

@property 
def is_recurring_instance(self) -> bool:
    """True if this is an instance of a recurring event."""

Attendee Management Methods

def add_attendee(self, attendee):
    """
    Add a single attendee to the event.
    
    :param attendee: Attendee object to add
    """

def add_attendees(self, attendees):
    """
    Add multiple attendees to the event.
    
    :param attendees: List of Attendee objects to add
    """

Attachment Management Methods

def add_attachment(self, file_url: str, title: str = None, mime_type: str = None):
    """
    Add a file attachment to the event.
    
    :param file_url: URL of the file to attach (Google Drive files only)
    :param title: Display title for the attachment
    :param mime_type: MIME type of the file
    """

Reminder Management Methods

def add_email_reminder(
    self, 
    minutes_before_start: int = None, 
    days_before: int = None, 
    at = None
):
    """
    Add an email reminder to the event.
    
    :param minutes_before_start: Minutes before event start to send reminder
    :param days_before: Days before event to send reminder
    :param at: Specific time to send reminder (datetime or time object)
    """

def add_popup_reminder(
    self,
    minutes_before_start: int = None,
    days_before: int = None,
    at = None
):
    """
    Add a popup reminder to the event.
    
    :param minutes_before_start: Minutes before event start to show popup
    :param days_before: Days before event to show popup
    :param at: Specific time to show popup (datetime or time object)
    """

def add_reminder(self, reminder):
    """
    Add a generic reminder to the event.
    
    :param reminder: EmailReminder or PopupReminder object
    """

Event Constants

Visibility Options

class Visibility:
    DEFAULT = "default"    # Default visibility based on calendar settings
    PUBLIC = "public"      # Event is public
    PRIVATE = "private"    # Event is private

Transparency Options

class Transparency:
    OPAQUE = "opaque"           # Event blocks time (shows as busy)
    TRANSPARENT = "transparent" # Event doesn't block time (shows as free)

Basic Usage Examples

Simple Event Creation

from gcsa.google_calendar import GoogleCalendar
from gcsa.event import Event, Visibility, Transparency
from datetime import datetime, date

gc = GoogleCalendar()

# Basic timed event
event = Event(
    summary="Team Meeting",
    start=datetime(2024, 1, 15, 10, 0),
    end=datetime(2024, 1, 15, 11, 0),
    description="Weekly team sync meeting",
    location="Conference Room A"
)
gc.add_event(event)

# All-day event
all_day_event = Event(
    summary="Company Holiday",
    start=date(2024, 1, 1),
    end=date(2024, 1, 2),  # End date is exclusive for all-day events
    transparency=Transparency.TRANSPARENT
)
gc.add_event(all_day_event)

Event with Advanced Properties

from gcsa.event import Event, Visibility
from gcsa.attendee import Attendee
from datetime import datetime

# Event with multiple properties
event = Event(
    summary="Project Kickoff",
    start=datetime(2024, 2, 1, 9, 0),
    end=datetime(2024, 2, 1, 10, 30),
    timezone="America/New_York",
    description="Initial project planning meeting",
    location="Building A, Room 101",
    color_id="2",  # Green color
    visibility=Visibility.PRIVATE,
    guests_can_invite_others=False,
    guests_can_modify=True,
    guests_can_see_other_guests=True
)

# Add attendees
event.add_attendee(Attendee("john@example.com", display_name="John Doe"))
event.add_attendee(Attendee("jane@example.com", display_name="Jane Smith", optional=True))

gc.add_event(event)

Recurring Events

from gcsa.event import Event
from gcsa.recurrence import Recurrence, WEEKLY, MONDAY, WEDNESDAY, FRIDAY
from datetime import datetime

# Weekly recurring meeting
recurring_event = Event(
    summary="Daily Standup",
    start=datetime(2024, 1, 15, 9, 0),
    end=datetime(2024, 1, 15, 9, 30),
    recurrence=[
        Recurrence.rule(
            freq=WEEKLY,
            by_weekday=[MONDAY, WEDNESDAY, FRIDAY],
            count=20  # 20 occurrences
        )
    ]
)
gc.add_event(recurring_event)

Event with Reminders

from gcsa.event import Event
from datetime import datetime, time

event = Event(
    summary="Important Deadline",
    start=datetime(2024, 3, 1, 17, 0),
    end=datetime(2024, 3, 1, 18, 0)
)

# Add multiple reminders
event.add_email_reminder(minutes_before_start=60)  # 1 hour before
event.add_email_reminder(days_before=1, at=time(9, 0))  # Day before at 9 AM
event.add_popup_reminder(minutes_before_start=15)  # 15 minutes before

gc.add_event(event)

Event with Attachments

from gcsa.event import Event
from datetime import datetime

event = Event(
    summary="Document Review Meeting",
    start=datetime(2024, 2, 15, 14, 0),
    end=datetime(2024, 2, 15, 15, 0)
)

# Add Google Drive attachments
event.add_attachment(
    file_url="https://drive.google.com/file/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
    title="Meeting Agenda",
    mime_type="application/vnd.google-apps.document"
)

gc.add_event(event)

Working with Recurring Event Instances

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

gc = GoogleCalendar()

# Get a recurring event
recurring_event = gc.get_event("recurring_event_id")

# Get individual instances of the recurring event
instances = gc.get_instances(
    recurring_event,
    time_min=datetime.now(),
    time_max=datetime.now() + timedelta(days=30)
)

# Modify a specific instance
for instance in instances:
    if instance.start.date() == datetime(2024, 1, 22).date():
        instance.summary = "Cancelled - Holiday"
        instance.status = "cancelled"
        gc.update_event(instance)
        break

Event Status and Lifecycle

from gcsa.event import Event
from datetime import datetime

# Create tentative event
event = Event(
    summary="Tentative Meeting",
    start=datetime(2024, 2, 1, 10, 0),
    end=datetime(2024, 2, 1, 11, 0),
    status="tentative"
)
gc.add_event(event)

# Confirm the event later
event.status = "confirmed"
gc.update_event(event)

# Cancel the event
event.status = "cancelled"
gc.update_event(event)

Event Colors

Events support 11 predefined colors (color_id 1-11):

from gcsa.event import Event
from datetime import datetime

# Create events with different colors
colors = {
    "1": "Lavender",
    "2": "Sage", 
    "3": "Grape",
    "4": "Flamingo",
    "5": "Banana",
    "6": "Tangerine",
    "7": "Peacock",
    "8": "Graphite",
    "9": "Blueberry",
    "10": "Basil",
    "11": "Tomato"
}

for color_id, color_name in colors.items():
    event = Event(
        summary=f"{color_name} Event",
        start=datetime(2024, 2, int(color_id), 10, 0),
        end=datetime(2024, 2, int(color_id), 11, 0),
        color_id=color_id
    )
    gc.add_event(event)

Extended Properties

from gcsa.event import Event
from datetime import datetime

# Event with custom extended properties
event = Event(
    summary="Project Task",
    start=datetime(2024, 3, 1, 9, 0),
    end=datetime(2024, 3, 1, 10, 0),
    extended_properties={
        "private": {
            "project_id": "PROJ-123",
            "priority": "high"
        },
        "shared": {
            "category": "development",
            "team": "backend"
        }
    }
)
gc.add_event(event)

Conference Integration

from gcsa.event import Event
from gcsa.conference import ConferenceSolutionCreateRequest, SolutionType
from datetime import datetime

# Event with Google Meet
event = Event(
    summary="Video Conference",
    start=datetime(2024, 2, 1, 14, 0),
    end=datetime(2024, 2, 1, 15, 0),
    conference_solution=ConferenceSolutionCreateRequest(
        solution_type=SolutionType.HANGOUTS_MEET
    )
)
gc.add_event(event)

Error Handling for Events

from gcsa.google_calendar import GoogleCalendar
from gcsa.event import Event
from googleapiclient.errors import HttpError
from datetime import datetime

gc = GoogleCalendar()

try:
    # Create event with validation
    event = Event(
        summary="Test Event",
        start=datetime(2024, 1, 15, 10, 0),
        end=datetime(2024, 1, 15, 9, 0)  # Invalid: end before start
    )
    gc.add_event(event)
except HttpError as e:
    print(f"Google Calendar API error: {e}")
except ValueError as e:
    print(f"Validation error: {e}")

Event Updates and Notifications

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

gc = GoogleCalendar()

# Update event and send notifications
event = gc.get_event("event_id")
event.summary = "Updated Meeting Title"
event.location = "New Location"

# Send notifications to all attendees
gc.update_event(event, send_updates="all")

# Send notifications only to external attendees
gc.update_event(event, send_updates="externalOnly")

# Don't send notifications
gc.update_event(event, send_updates="none")

The Event class provides a rich, flexible interface for managing calendar events with support for all Google Calendar features including recurring events, attendee management, reminders, attachments, and conference solutions.

Install with Tessl CLI