tessl/pypi-gcsa

Simple API for Google Calendar management

—

Pending

Overview

Eval results

Files

Reminders and Notifications

Name: tessl/pypi-gcsa
Author: tessl

GCSA provides comprehensive reminder and notification support through the Reminder, EmailReminder, and PopupReminder classes. These classes enable flexible timing options for both relative and absolute reminders to ensure users never miss important events.

Package Information

from gcsa.reminders import Reminder, EmailReminder, PopupReminder
from gcsa.event import Event

Reminder Base Class

Base Reminder Creation

class Reminder:
    def __init__(
        self,
        method: str,
        minutes_before_start = None,
        days_before = None,
        at = None
    ):
        """
        Create a base reminder object.
        
        :param method: Reminder method ('email' or 'popup')
        :param minutes_before_start: Minutes before event start to trigger reminder
        :param days_before: Days before event to trigger reminder
        :param at: Specific time to trigger reminder (time or datetime object)
        """

Reminder Conversion Method

def convert_to_relative(self, start):
    """
    Convert absolute reminder to relative reminder based on event start time.
    
    :param start: Event start datetime
    :return: New Reminder object with relative timing
    """

EmailReminder Class

Email Reminder Creation

class EmailReminder(Reminder):
    def __init__(
        self,
        minutes_before_start = None,
        days_before = None,
        at = None
    ):
        """
        Create an email reminder.
        
        :param minutes_before_start: Minutes before event start to send email
        :param days_before: Days before event to send email (used with 'at' parameter)
        :param at: Specific time to send email (time object like time(9, 0) for 9 AM)
        
        Note: Either use minutes_before_start OR combine days_before with at
        """

PopupReminder Class

Popup Reminder Creation

class PopupReminder(Reminder):
    def __init__(
        self,
        minutes_before_start = None,
        days_before = None,
        at = None
    ):
        """
        Create a popup reminder.
        
        :param minutes_before_start: Minutes before event start to show popup
        :param days_before: Days before event to show popup (used with 'at' parameter)
        :param at: Specific time to show popup (time object like time(9, 0) for 9 AM)
        
        Note: Either use minutes_before_start OR combine days_before with at
        """

Event Reminder Methods

Adding Reminders to Events

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 object to the event.
    
    :param reminder: EmailReminder or PopupReminder object
    """

Basic Usage Examples

Simple Relative Reminders

from gcsa.google_calendar import GoogleCalendar
from gcsa.event import Event
from gcsa.reminders import EmailReminder, PopupReminder
from datetime import datetime

gc = GoogleCalendar()

# Event with basic reminders
meeting = Event(
    summary="Important Client Meeting",
    start=datetime(2024, 2, 15, 14, 0),
    end=datetime(2024, 2, 15, 15, 30),
    description="Quarterly review with key client"
)

# Add reminders using event methods
meeting.add_email_reminder(minutes_before_start=60)   # 1 hour before
meeting.add_popup_reminder(minutes_before_start=15)   # 15 minutes before

gc.add_event(meeting)

Multiple Email Reminders

from gcsa.event import Event
from gcsa.reminders import EmailReminder
from datetime import datetime

# Event with multiple email reminders at different intervals
project_deadline = Event(
    summary="Project Deadline",
    start=datetime(2024, 3, 1, 17, 0),
    end=datetime(2024, 3, 1, 18, 0)
)

# Add multiple email reminders
reminders = [
    EmailReminder(minutes_before_start=10080),  # 1 week before (7 days × 24 hours × 60 minutes)
    EmailReminder(minutes_before_start=2880),   # 2 days before
    EmailReminder(minutes_before_start=1440),   # 1 day before  
    EmailReminder(minutes_before_start=240),    # 4 hours before
    EmailReminder(minutes_before_start=60)      # 1 hour before
]

for reminder in reminders:
    project_deadline.add_reminder(reminder)

gc.add_event(project_deadline)

Absolute Time Reminders

from gcsa.event import Event
from gcsa.reminders import EmailReminder, PopupReminder
from datetime import datetime, time

# Event with absolute time reminders
conference = Event(
    summary="Tech Conference",
    start=datetime(2024, 4, 15, 9, 0),
    end=datetime(2024, 4, 15, 17, 0),
    location="Convention Center"
)

# Email reminders at specific times
conference.add_email_reminder(days_before=7, at=time(9, 0))   # Week before at 9 AM
conference.add_email_reminder(days_before=3, at=time(18, 0))  # 3 days before at 6 PM
conference.add_email_reminder(days_before=1, at=time(8, 0))   # Day before at 8 AM

# Popup reminder 30 minutes before
conference.add_popup_reminder(minutes_before_start=30)

gc.add_event(conference)

Creating Reminders with Objects

from gcsa.event import Event
from gcsa.reminders import EmailReminder, PopupReminder
from datetime import datetime, time

# Create reminder objects first, then add to event
early_warning = EmailReminder(days_before=5, at=time(10, 0))
day_before = EmailReminder(days_before=1, at=time(9, 0))
last_minute = PopupReminder(minutes_before_start=30)

important_meeting = Event(
    summary="Board Meeting",
    start=datetime(2024, 5, 20, 10, 0),
    end=datetime(2024, 5, 20, 12, 0),
    reminders=[early_warning, day_before, last_minute]
)

gc.add_event(important_meeting)

Reminder Patterns for Different Event Types

from gcsa.event import Event
from gcsa.reminders import EmailReminder, PopupReminder
from datetime import datetime, time

# Doctor's appointment - early and immediate reminders
doctor_appointment = Event(
    summary="Doctor Appointment",
    start=datetime(2024, 3, 10, 14, 30),
    end=datetime(2024, 3, 10, 15, 30)
)
doctor_appointment.add_email_reminder(days_before=3, at=time(19, 0))  # 3 days at 7 PM
doctor_appointment.add_popup_reminder(minutes_before_start=60)         # 1 hour before

# Flight departure - multiple warnings
flight = Event(
    summary="Flight to New York",
    start=datetime(2024, 6, 1, 8, 0),
    end=datetime(2024, 6, 1, 10, 0),
    location="Airport Gate B12"
)
flight.add_email_reminder(days_before=1, at=time(20, 0))    # Night before at 8 PM
flight.add_popup_reminder(minutes_before_start=180)         # 3 hours before (for travel time)
flight.add_popup_reminder(minutes_before_start=60)          # 1 hour before

# Birthday reminder - well in advance
birthday = Event(
    summary="John's Birthday",
    start=datetime(2024, 7, 15, 0, 0),
    end=datetime(2024, 7, 16, 0, 0)
)
birthday.add_email_reminder(days_before=14, at=time(9, 0))   # 2 weeks before
birthday.add_email_reminder(days_before=7, at=time(9, 0))    # 1 week before  
birthday.add_email_reminder(days_before=1, at=time(9, 0))    # Day before

gc.add_event(doctor_appointment)
gc.add_event(flight)
gc.add_event(birthday)

Working with All-Day Events

from gcsa.event import Event
from gcsa.reminders import EmailReminder
from datetime import date, time

# All-day event with timed reminders
company_picnic = Event(
    summary="Annual Company Picnic",
    start=date(2024, 8, 15),  # All-day event
    end=date(2024, 8, 16),
    location="City Park"
)

# Add reminders at specific times for all-day events
company_picnic.add_email_reminder(days_before=7, at=time(12, 0))   # Week before at noon
company_picnic.add_email_reminder(days_before=2, at=time(17, 0))   # 2 days before at 5 PM
company_picnic.add_email_reminder(days_before=0, at=time(8, 0))    # Day of event at 8 AM

gc.add_event(company_picnic)

Customizing Default Calendar 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=1440),  # 1 day before via email
    PopupReminder(minutes_before_start=30)     # 30 minutes before via popup
]

gc.update_calendar_list_entry(calendar_entry)

# New events on this calendar will automatically get these reminders
# unless overridden with custom reminders

Complex Reminder Schedules

from gcsa.event import Event
from gcsa.reminders import EmailReminder, PopupReminder
from datetime import datetime, time

# Project milestone with escalating reminders
milestone = Event(
    summary="Project Phase 1 Completion",
    start=datetime(2024, 4, 30, 23, 59),  # End of day deadline
    end=datetime(2024, 5, 1, 0, 0),
    description="All deliverables must be completed"
)

# Escalating reminder schedule
milestone.add_email_reminder(days_before=30, at=time(9, 0))    # Monthly notice
milestone.add_email_reminder(days_before=14, at=time(9, 0))    # Bi-weekly notice
milestone.add_email_reminder(days_before=7, at=time(9, 0))     # Weekly notice
milestone.add_email_reminder(days_before=3, at=time(17, 0))    # 3 days at EOD
milestone.add_email_reminder(days_before=1, at=time(8, 0))     # Day before morning
milestone.add_popup_reminder(minutes_before_start=480)         # 8 hours before
milestone.add_popup_reminder(minutes_before_start=120)         # 2 hours before
milestone.add_popup_reminder(minutes_before_start=30)          # 30 minutes before

gc.add_event(milestone)

Recurring Events with Reminders

from gcsa.event import Event
from gcsa.reminders import EmailReminder, PopupReminder
from gcsa.recurrence import Recurrence, WEEKLY, MONDAY
from datetime import datetime

# Weekly recurring meeting with consistent reminders
weekly_standup = Event(
    summary="Weekly Team Standup",
    start=datetime(2024, 1, 15, 9, 0),
    end=datetime(2024, 1, 15, 9, 30),
    recurrence=[
        Recurrence.rule(freq=WEEKLY, by_weekday=MONDAY, count=26)
    ]
)

# Reminders apply to all instances
weekly_standup.add_email_reminder(minutes_before_start=1440)  # Day before
weekly_standup.add_popup_reminder(minutes_before_start=15)    # 15 minutes before

gc.add_event(weekly_standup)

Working with Time Zones

from gcsa.event import Event
from gcsa.reminders import EmailReminder
from datetime import datetime, time
import pytz

# Event in specific timezone with reminders
eastern = pytz.timezone('America/New_York')
event_time = eastern.localize(datetime(2024, 3, 15, 14, 0))

timezone_meeting = Event(
    summary="Cross-Timezone Meeting",
    start=event_time,
    end=event_time.replace(hour=15),
    timezone='America/New_York'
)

# Reminders will respect the event's timezone
timezone_meeting.add_email_reminder(days_before=1, at=time(9, 0))  # 9 AM Eastern
timezone_meeting.add_popup_reminder(minutes_before_start=30)

gc.add_event(timezone_meeting)

Reminder Validation and Error Handling

from gcsa.event import Event
from gcsa.reminders import EmailReminder, PopupReminder
from datetime import datetime, time

try:
    event = Event(
        summary="Test Event",
        start=datetime(2024, 2, 15, 10, 0),
        end=datetime(2024, 2, 15, 11, 0)
    )
    
    # Valid reminder combinations
    event.add_email_reminder(minutes_before_start=60)           # Relative reminder
    event.add_email_reminder(days_before=1, at=time(9, 0))     # Absolute reminder
    
    # Invalid: mixing relative and absolute parameters
    # event.add_email_reminder(minutes_before_start=60, days_before=1, at=time(9, 0))
    
    gc.add_event(event)
    
except ValueError as e:
    print(f"Reminder validation error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

Modifying Reminders on Existing Events

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

gc = GoogleCalendar()

# Get existing event and modify reminders
event = gc.get_event("event_id")

# Clear existing reminders and add new ones
event.reminders = []
event.add_email_reminder(minutes_before_start=120)  # 2 hours before
event.add_popup_reminder(minutes_before_start=15)   # 15 minutes before

# Update the event
gc.update_event(event)

# Or add additional reminders to existing ones
event.add_email_reminder(days_before=1, at=time(18, 0))  # Day before at 6 PM
gc.update_event(event)

Business Hours Reminder Patterns

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

def create_business_reminders(event_start):
    """Create reminder pattern that respects business hours"""
    business_day_reminder = EmailReminder(days_before=1, at=time(9, 0))   # 9 AM day before
    business_hour_reminder = EmailReminder(days_before=0, at=time(8, 0))  # 8 AM day of
    
    return [business_day_reminder, business_hour_reminder]

# Weekend event with business hour reminders
weekend_event = Event(
    summary="Weekend Workshop",
    start=datetime(2024, 3, 16, 10, 0),  # Saturday
    end=datetime(2024, 3, 16, 16, 0)
)

# Add business hour reminders
for reminder in create_business_reminders(weekend_event.start):
    weekend_event.add_reminder(reminder)

gc.add_event(weekend_event)

The reminder system in GCSA provides flexible options for ensuring users are notified about upcoming events through both email and popup notifications. The system supports both relative timing (minutes/hours before) and absolute timing (specific times on specific days before the event), making it suitable for various scheduling needs from simple meetings to complex project deadlines.

Install with Tessl CLI