0
# Event Management
1

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

4
## Package Information
5

6
```python
7
from gcsa.event import Event, Visibility, Transparency
8
```
9

10
## Event Class
11

12
### Basic Event Creation
13

14
```python { .api }
15
class Event:
16
    def __init__(
17
        self,
18
        summary: str,
19
        start = None,
20
        end = None,
21
        timezone = None,
22
        event_id = None,
23
        description = None,
24
        location = None,
25
        recurrence = None,
26
        color_id = None,
27
        visibility = None,
28
        attendees = None,
29
        attachments = None,
30
        conference_solution = None,
31
        reminders = None,
32
        transparency = None,
33
        status = None,
34
        created = None,
35
        updated = None,
36
        creator = None,
37
        organizer = None,
38
        guests_can_invite_others = None,
39
        guests_can_modify = None,
40
        guests_can_see_other_guests = None,
41
        private_copy = None,
42
        locked = None,
43
        source = None,
44
        end_time_unspecified = None,
45
        sequence = None,
46
        hangout_link = None,
47
        gadget = None,
48
        anyone_can_add_self = None,
49
        original_start_time = None,
50
        extended_properties = None,
51
        _i_cal_uid = None,
52
        _html_link = None,
53
        _recurring_event_id = None,
54
        _etag = None
55
    ):
56
        """
57
        Create a new calendar event.
58
        
59
        :param summary: Event title/name (required)
60
        :param start: Event start time (datetime object or date for all-day events)
61
        :param end: Event end time (datetime object or date for all-day events)
62
        :param timezone: Time zone for event times (string like 'America/New_York')
63
        :param event_id: Unique identifier (auto-generated if not provided)
64
        :param description: Event description/details
65
        :param location: Event location
66
        :param recurrence: List of recurrence rules (RRULE, RDATE, EXRULE, EXDATE)
67
        :param color_id: Event color ID (1-11)
68
        :param visibility: Event visibility ('default', 'public', 'private')
69
        :param attendees: List of Attendee objects
70
        :param attachments: List of Attachment objects
71
        :param conference_solution: ConferenceSolution or ConferenceSolutionCreateRequest
72
        :param reminders: List of Reminder objects
73
        :param transparency: Whether event blocks time ('opaque', 'transparent')
74
        :param status: Event status ('confirmed', 'tentative', 'cancelled')
75
        :param created: Creation timestamp
76
        :param updated: Last modification timestamp
77
        :param creator: Person who created the event
78
        :param organizer: Event organizer
79
        :param guests_can_invite_others: Whether guests can invite others
80
        :param guests_can_modify: Whether guests can modify event
81
        :param guests_can_see_other_guests: Whether guests can see other attendees
82
        :param private_copy: Whether this is a private copy for the user
83
        :param locked: Whether event is locked against changes
84
        :param source: Source information for imported events
85
        :param end_time_unspecified: Whether end time is unspecified
86
        :param sequence: Event sequence number for updates
87
        :param hangout_link: Hangout video conference link
88
        :param gadget: Gadget/add-on information
89
        :param anyone_can_add_self: Whether anyone can add themselves as attendee
90
        :param original_start_time: Original start time for recurring event instances
91
        :param extended_properties: Extended properties dictionary
92
        """
93
```
94

95
### Event Properties
96

97
```python { .api }
98
@property
99
def id(self) -> str:
100
    """Unique identifier for the event."""
101

102
@property 
103
def is_recurring_instance(self) -> bool:
104
    """True if this is an instance of a recurring event."""
105
```
106

107
### Attendee Management Methods
108

109
```python { .api }
110
def add_attendee(self, attendee):
111
    """
112
    Add a single attendee to the event.
113
    
114
    :param attendee: Attendee object to add
115
    """
116

117
def add_attendees(self, attendees):
118
    """
119
    Add multiple attendees to the event.
120
    
121
    :param attendees: List of Attendee objects to add
122
    """
123
```
124

125
### Attachment Management Methods
126

127
```python { .api }
128
def add_attachment(self, file_url: str, title: str = None, mime_type: str = None):
129
    """
130
    Add a file attachment to the event.
131
    
132
    :param file_url: URL of the file to attach (Google Drive files only)
133
    :param title: Display title for the attachment
134
    :param mime_type: MIME type of the file
135
    """
136
```
137

138
### Reminder Management Methods
139

140
```python { .api }
141
def add_email_reminder(
142
    self, 
143
    minutes_before_start: int = None, 
144
    days_before: int = None, 
145
    at = None
146
):
147
    """
148
    Add an email reminder to the event.
149
    
150
    :param minutes_before_start: Minutes before event start to send reminder
151
    :param days_before: Days before event to send reminder
152
    :param at: Specific time to send reminder (datetime or time object)
153
    """
154

155
def add_popup_reminder(
156
    self,
157
    minutes_before_start: int = None,
158
    days_before: int = None,
159
    at = None
160
):
161
    """
162
    Add a popup reminder to the event.
163
    
164
    :param minutes_before_start: Minutes before event start to show popup
165
    :param days_before: Days before event to show popup
166
    :param at: Specific time to show popup (datetime or time object)
167
    """
168

169
def add_reminder(self, reminder):
170
    """
171
    Add a generic reminder to the event.
172
    
173
    :param reminder: EmailReminder or PopupReminder object
174
    """
175
```
176

177
## Event Constants
178

179
### Visibility Options
180

181
```python { .api }
182
class Visibility:
183
    DEFAULT = "default"    # Default visibility based on calendar settings
184
    PUBLIC = "public"      # Event is public
185
    PRIVATE = "private"    # Event is private
186
```
187

188
### Transparency Options
189

190
```python { .api }
191
class Transparency:
192
    OPAQUE = "opaque"           # Event blocks time (shows as busy)
193
    TRANSPARENT = "transparent" # Event doesn't block time (shows as free)
194
```
195

196
## Basic Usage Examples
197

198
### Simple Event Creation
199

200
```python
201
from gcsa.google_calendar import GoogleCalendar
202
from gcsa.event import Event, Visibility, Transparency
203
from datetime import datetime, date
204

205
gc = GoogleCalendar()
206

207
# Basic timed event
208
event = Event(
209
    summary="Team Meeting",
210
    start=datetime(2024, 1, 15, 10, 0),
211
    end=datetime(2024, 1, 15, 11, 0),
212
    description="Weekly team sync meeting",
213
    location="Conference Room A"
214
)
215
gc.add_event(event)
216

217
# All-day event
218
all_day_event = Event(
219
    summary="Company Holiday",
220
    start=date(2024, 1, 1),
221
    end=date(2024, 1, 2),  # End date is exclusive for all-day events
222
    transparency=Transparency.TRANSPARENT
223
)
224
gc.add_event(all_day_event)
225
```
226

227
### Event with Advanced Properties
228

229
```python
230
from gcsa.event import Event, Visibility
231
from gcsa.attendee import Attendee
232
from datetime import datetime
233

234
# Event with multiple properties
235
event = Event(
236
    summary="Project Kickoff",
237
    start=datetime(2024, 2, 1, 9, 0),
238
    end=datetime(2024, 2, 1, 10, 30),
239
    timezone="America/New_York",
240
    description="Initial project planning meeting",
241
    location="Building A, Room 101",
242
    color_id="2",  # Green color
243
    visibility=Visibility.PRIVATE,
244
    guests_can_invite_others=False,
245
    guests_can_modify=True,
246
    guests_can_see_other_guests=True
247
)
248

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

253
gc.add_event(event)
254
```
255

256
### Recurring Events
257

258
```python
259
from gcsa.event import Event
260
from gcsa.recurrence import Recurrence, WEEKLY, MONDAY, WEDNESDAY, FRIDAY
261
from datetime import datetime
262

263
# Weekly recurring meeting
264
recurring_event = Event(
265
    summary="Daily Standup",
266
    start=datetime(2024, 1, 15, 9, 0),
267
    end=datetime(2024, 1, 15, 9, 30),
268
    recurrence=[
269
        Recurrence.rule(
270
            freq=WEEKLY,
271
            by_weekday=[MONDAY, WEDNESDAY, FRIDAY],
272
            count=20  # 20 occurrences
273
        )
274
    ]
275
)
276
gc.add_event(recurring_event)
277
```
278

279
### Event with Reminders
280

281
```python
282
from gcsa.event import Event
283
from datetime import datetime, time
284

285
event = Event(
286
    summary="Important Deadline",
287
    start=datetime(2024, 3, 1, 17, 0),
288
    end=datetime(2024, 3, 1, 18, 0)
289
)
290

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

296
gc.add_event(event)
297
```
298

299
### Event with Attachments
300

301
```python
302
from gcsa.event import Event
303
from datetime import datetime
304

305
event = Event(
306
    summary="Document Review Meeting",
307
    start=datetime(2024, 2, 15, 14, 0),
308
    end=datetime(2024, 2, 15, 15, 0)
309
)
310

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

318
gc.add_event(event)
319
```
320

321
## Working with Recurring Event Instances
322

323
```python
324
from gcsa.google_calendar import GoogleCalendar
325
from datetime import datetime, timedelta
326

327
gc = GoogleCalendar()
328

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

332
# Get individual instances of the recurring event
333
instances = gc.get_instances(
334
    recurring_event,
335
    time_min=datetime.now(),
336
    time_max=datetime.now() + timedelta(days=30)
337
)
338

339
# Modify a specific instance
340
for instance in instances:
341
    if instance.start.date() == datetime(2024, 1, 22).date():
342
        instance.summary = "Cancelled - Holiday"
343
        instance.status = "cancelled"
344
        gc.update_event(instance)
345
        break
346
```
347

348
## Event Status and Lifecycle
349

350
```python
351
from gcsa.event import Event
352
from datetime import datetime
353

354
# Create tentative event
355
event = Event(
356
    summary="Tentative Meeting",
357
    start=datetime(2024, 2, 1, 10, 0),
358
    end=datetime(2024, 2, 1, 11, 0),
359
    status="tentative"
360
)
361
gc.add_event(event)
362

363
# Confirm the event later
364
event.status = "confirmed"
365
gc.update_event(event)
366

367
# Cancel the event
368
event.status = "cancelled"
369
gc.update_event(event)
370
```
371

372
## Event Colors
373

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

376
```python
377
from gcsa.event import Event
378
from datetime import datetime
379

380
# Create events with different colors
381
colors = {
382
    "1": "Lavender",
383
    "2": "Sage", 
384
    "3": "Grape",
385
    "4": "Flamingo",
386
    "5": "Banana",
387
    "6": "Tangerine",
388
    "7": "Peacock",
389
    "8": "Graphite",
390
    "9": "Blueberry",
391
    "10": "Basil",
392
    "11": "Tomato"
393
}
394

395
for color_id, color_name in colors.items():
396
    event = Event(
397
        summary=f"{color_name} Event",
398
        start=datetime(2024, 2, int(color_id), 10, 0),
399
        end=datetime(2024, 2, int(color_id), 11, 0),
400
        color_id=color_id
401
    )
402
    gc.add_event(event)
403
```
404

405
## Extended Properties
406

407
```python
408
from gcsa.event import Event
409
from datetime import datetime
410

411
# Event with custom extended properties
412
event = Event(
413
    summary="Project Task",
414
    start=datetime(2024, 3, 1, 9, 0),
415
    end=datetime(2024, 3, 1, 10, 0),
416
    extended_properties={
417
        "private": {
418
            "project_id": "PROJ-123",
419
            "priority": "high"
420
        },
421
        "shared": {
422
            "category": "development",
423
            "team": "backend"
424
        }
425
    }
426
)
427
gc.add_event(event)
428
```
429

430
## Conference Integration
431

432
```python
433
from gcsa.event import Event
434
from gcsa.conference import ConferenceSolutionCreateRequest, SolutionType
435
from datetime import datetime
436

437
# Event with Google Meet
438
event = Event(
439
    summary="Video Conference",
440
    start=datetime(2024, 2, 1, 14, 0),
441
    end=datetime(2024, 2, 1, 15, 0),
442
    conference_solution=ConferenceSolutionCreateRequest(
443
        solution_type=SolutionType.HANGOUTS_MEET
444
    )
445
)
446
gc.add_event(event)
447
```
448

449
## Error Handling for Events
450

451
```python
452
from gcsa.google_calendar import GoogleCalendar
453
from gcsa.event import Event
454
from googleapiclient.errors import HttpError
455
from datetime import datetime
456

457
gc = GoogleCalendar()
458

459
try:
460
    # Create event with validation
461
    event = Event(
462
        summary="Test Event",
463
        start=datetime(2024, 1, 15, 10, 0),
464
        end=datetime(2024, 1, 15, 9, 0)  # Invalid: end before start
465
    )
466
    gc.add_event(event)
467
except HttpError as e:
468
    print(f"Google Calendar API error: {e}")
469
except ValueError as e:
470
    print(f"Validation error: {e}")
471
```
472

473
## Event Updates and Notifications
474

475
```python
476
from gcsa.google_calendar import GoogleCalendar
477
from gcsa.event import Event
478

479
gc = GoogleCalendar()
480

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

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

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

492
# Don't send notifications
493
gc.update_event(event, send_updates="none")
494
```
495

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