0
# Reminders and Notifications
1

2
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.
3

4
## Package Information
5

6
```python
7
from gcsa.reminders import Reminder, EmailReminder, PopupReminder
8
from gcsa.event import Event
9
```
10

11
## Reminder Base Class
12

13
### Base Reminder Creation
14

15
```python { .api }
16
class Reminder:
17
    def __init__(
18
        self,
19
        method: str,
20
        minutes_before_start = None,
21
        days_before = None,
22
        at = None
23
    ):
24
        """
25
        Create a base reminder object.
26
        
27
        :param method: Reminder method ('email' or 'popup')
28
        :param minutes_before_start: Minutes before event start to trigger reminder
29
        :param days_before: Days before event to trigger reminder
30
        :param at: Specific time to trigger reminder (time or datetime object)
31
        """
32
```
33

34
### Reminder Conversion Method
35

36
```python { .api }
37
def convert_to_relative(self, start):
38
    """
39
    Convert absolute reminder to relative reminder based on event start time.
40
    
41
    :param start: Event start datetime
42
    :return: New Reminder object with relative timing
43
    """
44
```
45

46
## EmailReminder Class
47

48
### Email Reminder Creation
49

50
```python { .api }
51
class EmailReminder(Reminder):
52
    def __init__(
53
        self,
54
        minutes_before_start = None,
55
        days_before = None,
56
        at = None
57
    ):
58
        """
59
        Create an email reminder.
60
        
61
        :param minutes_before_start: Minutes before event start to send email
62
        :param days_before: Days before event to send email (used with 'at' parameter)
63
        :param at: Specific time to send email (time object like time(9, 0) for 9 AM)
64
        
65
        Note: Either use minutes_before_start OR combine days_before with at
66
        """
67
```
68

69
## PopupReminder Class
70

71
### Popup Reminder Creation
72

73
```python { .api }
74
class PopupReminder(Reminder):
75
    def __init__(
76
        self,
77
        minutes_before_start = None,
78
        days_before = None,
79
        at = None
80
    ):
81
        """
82
        Create a popup reminder.
83
        
84
        :param minutes_before_start: Minutes before event start to show popup
85
        :param days_before: Days before event to show popup (used with 'at' parameter)
86
        :param at: Specific time to show popup (time object like time(9, 0) for 9 AM)
87
        
88
        Note: Either use minutes_before_start OR combine days_before with at
89
        """
90
```
91

92
## Event Reminder Methods
93

94
### Adding Reminders to Events
95

96
```python { .api }
97
def add_email_reminder(
98
    self,
99
    minutes_before_start: int = None,
100
    days_before: int = None,
101
    at = None
102
):
103
    """
104
    Add an email reminder to the event.
105
    
106
    :param minutes_before_start: Minutes before event start to send reminder
107
    :param days_before: Days before event to send reminder
108
    :param at: Specific time to send reminder (datetime or time object)
109
    """
110

111
def add_popup_reminder(
112
    self,
113
    minutes_before_start: int = None,
114
    days_before: int = None,
115
    at = None
116
):
117
    """
118
    Add a popup reminder to the event.
119
    
120
    :param minutes_before_start: Minutes before event start to show popup
121
    :param days_before: Days before event to show popup
122
    :param at: Specific time to show popup (datetime or time object)
123
    """
124

125
def add_reminder(self, reminder):
126
    """
127
    Add a generic reminder object to the event.
128
    
129
    :param reminder: EmailReminder or PopupReminder object
130
    """
131
```
132

133
## Basic Usage Examples
134

135
### Simple Relative Reminders
136

137
```python
138
from gcsa.google_calendar import GoogleCalendar
139
from gcsa.event import Event
140
from gcsa.reminders import EmailReminder, PopupReminder
141
from datetime import datetime
142

143
gc = GoogleCalendar()
144

145
# Event with basic reminders
146
meeting = Event(
147
    summary="Important Client Meeting",
148
    start=datetime(2024, 2, 15, 14, 0),
149
    end=datetime(2024, 2, 15, 15, 30),
150
    description="Quarterly review with key client"
151
)
152

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

157
gc.add_event(meeting)
158
```
159

160
### Multiple Email Reminders
161

162
```python
163
from gcsa.event import Event
164
from gcsa.reminders import EmailReminder
165
from datetime import datetime
166

167
# Event with multiple email reminders at different intervals
168
project_deadline = Event(
169
    summary="Project Deadline",
170
    start=datetime(2024, 3, 1, 17, 0),
171
    end=datetime(2024, 3, 1, 18, 0)
172
)
173

174
# Add multiple email reminders
175
reminders = [
176
    EmailReminder(minutes_before_start=10080),  # 1 week before (7 days × 24 hours × 60 minutes)
177
    EmailReminder(minutes_before_start=2880),   # 2 days before
178
    EmailReminder(minutes_before_start=1440),   # 1 day before  
179
    EmailReminder(minutes_before_start=240),    # 4 hours before
180
    EmailReminder(minutes_before_start=60)      # 1 hour before
181
]
182

183
for reminder in reminders:
184
    project_deadline.add_reminder(reminder)
185

186
gc.add_event(project_deadline)
187
```
188

189
### Absolute Time Reminders
190

191
```python
192
from gcsa.event import Event
193
from gcsa.reminders import EmailReminder, PopupReminder
194
from datetime import datetime, time
195

196
# Event with absolute time reminders
197
conference = Event(
198
    summary="Tech Conference",
199
    start=datetime(2024, 4, 15, 9, 0),
200
    end=datetime(2024, 4, 15, 17, 0),
201
    location="Convention Center"
202
)
203

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

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

212
gc.add_event(conference)
213
```
214

215
### Creating Reminders with Objects
216

217
```python
218
from gcsa.event import Event
219
from gcsa.reminders import EmailReminder, PopupReminder
220
from datetime import datetime, time
221

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

227
important_meeting = Event(
228
    summary="Board Meeting",
229
    start=datetime(2024, 5, 20, 10, 0),
230
    end=datetime(2024, 5, 20, 12, 0),
231
    reminders=[early_warning, day_before, last_minute]
232
)
233

234
gc.add_event(important_meeting)
235
```
236

237
### Reminder Patterns for Different Event Types
238

239
```python
240
from gcsa.event import Event
241
from gcsa.reminders import EmailReminder, PopupReminder
242
from datetime import datetime, time
243

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

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

264
# Birthday reminder - well in advance
265
birthday = Event(
266
    summary="John's Birthday",
267
    start=datetime(2024, 7, 15, 0, 0),
268
    end=datetime(2024, 7, 16, 0, 0)
269
)
270
birthday.add_email_reminder(days_before=14, at=time(9, 0))   # 2 weeks before
271
birthday.add_email_reminder(days_before=7, at=time(9, 0))    # 1 week before  
272
birthday.add_email_reminder(days_before=1, at=time(9, 0))    # Day before
273

274
gc.add_event(doctor_appointment)
275
gc.add_event(flight)
276
gc.add_event(birthday)
277
```
278

279
### Working with All-Day Events
280

281
```python
282
from gcsa.event import Event
283
from gcsa.reminders import EmailReminder
284
from datetime import date, time
285

286
# All-day event with timed reminders
287
company_picnic = Event(
288
    summary="Annual Company Picnic",
289
    start=date(2024, 8, 15),  # All-day event
290
    end=date(2024, 8, 16),
291
    location="City Park"
292
)
293

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

299
gc.add_event(company_picnic)
300
```
301

302
### Customizing Default Calendar Reminders
303

304
```python
305
from gcsa.google_calendar import GoogleCalendar
306
from gcsa.calendar import CalendarListEntry
307
from gcsa.reminders import EmailReminder, PopupReminder
308

309
gc = GoogleCalendar()
310

311
# Set default reminders for a calendar
312
calendar_entry = gc.get_calendar_list_entry("calendar_id")
313
calendar_entry.default_reminders = [
314
    EmailReminder(minutes_before_start=1440),  # 1 day before via email
315
    PopupReminder(minutes_before_start=30)     # 30 minutes before via popup
316
]
317

318
gc.update_calendar_list_entry(calendar_entry)
319

320
# New events on this calendar will automatically get these reminders
321
# unless overridden with custom reminders
322
```
323

324
### Complex Reminder Schedules
325

326
```python
327
from gcsa.event import Event
328
from gcsa.reminders import EmailReminder, PopupReminder
329
from datetime import datetime, time
330

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

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

349
gc.add_event(milestone)
350
```
351

352
### Recurring Events with Reminders
353

354
```python
355
from gcsa.event import Event
356
from gcsa.reminders import EmailReminder, PopupReminder
357
from gcsa.recurrence import Recurrence, WEEKLY, MONDAY
358
from datetime import datetime
359

360
# Weekly recurring meeting with consistent reminders
361
weekly_standup = Event(
362
    summary="Weekly Team Standup",
363
    start=datetime(2024, 1, 15, 9, 0),
364
    end=datetime(2024, 1, 15, 9, 30),
365
    recurrence=[
366
        Recurrence.rule(freq=WEEKLY, by_weekday=MONDAY, count=26)
367
    ]
368
)
369

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

374
gc.add_event(weekly_standup)
375
```
376

377
### Working with Time Zones
378

379
```python
380
from gcsa.event import Event
381
from gcsa.reminders import EmailReminder
382
from datetime import datetime, time
383
import pytz
384

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

389
timezone_meeting = Event(
390
    summary="Cross-Timezone Meeting",
391
    start=event_time,
392
    end=event_time.replace(hour=15),
393
    timezone='America/New_York'
394
)
395

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

400
gc.add_event(timezone_meeting)
401
```
402

403
### Reminder Validation and Error Handling
404

405
```python
406
from gcsa.event import Event
407
from gcsa.reminders import EmailReminder, PopupReminder
408
from datetime import datetime, time
409

410
try:
411
    event = Event(
412
        summary="Test Event",
413
        start=datetime(2024, 2, 15, 10, 0),
414
        end=datetime(2024, 2, 15, 11, 0)
415
    )
416
    
417
    # Valid reminder combinations
418
    event.add_email_reminder(minutes_before_start=60)           # Relative reminder
419
    event.add_email_reminder(days_before=1, at=time(9, 0))     # Absolute reminder
420
    
421
    # Invalid: mixing relative and absolute parameters
422
    # event.add_email_reminder(minutes_before_start=60, days_before=1, at=time(9, 0))
423
    
424
    gc.add_event(event)
425
    
426
except ValueError as e:
427
    print(f"Reminder validation error: {e}")
428
except Exception as e:
429
    print(f"Unexpected error: {e}")
430
```
431

432
### Modifying Reminders on Existing Events
433

434
```python
435
from gcsa.google_calendar import GoogleCalendar
436
from gcsa.reminders import EmailReminder, PopupReminder
437

438
gc = GoogleCalendar()
439

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

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

448
# Update the event
449
gc.update_event(event)
450

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

456
### Business Hours Reminder Patterns
457

458
```python
459
from gcsa.event import Event
460
from gcsa.reminders import EmailReminder
461
from datetime import datetime, time
462

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

470
# Weekend event with business hour reminders
471
weekend_event = Event(
472
    summary="Weekend Workshop",
473
    start=datetime(2024, 3, 16, 10, 0),  # Saturday
474
    end=datetime(2024, 3, 16, 16, 0)
475
)
476

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

481
gc.add_event(weekend_event)
482
```
483

484
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.