0
# Calendar Management
1

2
GCSA provides comprehensive calendar management through the Calendar and CalendarListEntry classes. These classes handle calendar creation, configuration, user-specific settings, and calendar list management for organizing multiple calendars.
3

4
## Package Information
5

6
```python
7
from gcsa.calendar import Calendar, CalendarListEntry, NotificationType, AccessRoles
8
from gcsa.google_calendar import GoogleCalendar
9
```
10

11
## Calendar Class
12

13
### Basic Calendar Creation
14

15
```python { .api }
16
class Calendar:
17
    def __init__(
18
        self,
19
        summary: str,
20
        calendar_id = None,
21
        description = None,
22
        location = None,
23
        timezone = None,
24
        allowed_conference_solution_types = None,
25
        _etag = None,
26
        _kind = None
27
    ):
28
        """
29
        Create a new calendar.
30
        
31
        :param summary: Calendar name/title (required)
32
        :param calendar_id: Unique identifier (auto-generated if not provided)
33
        :param description: Calendar description
34
        :param location: Calendar location
35
        :param timezone: Calendar time zone (e.g., 'America/New_York')
36
        :param allowed_conference_solution_types: List of allowed conference solutions
37
        """
38
```
39

40
### Calendar Properties
41

42
```python { .api }
43
@property
44
def id(self) -> str:
45
    """Unique identifier for the calendar."""
46
```
47

48
### Calendar Conversion Method
49

50
```python { .api }
51
def to_calendar_list_entry(self):
52
    """
53
    Convert Calendar to CalendarListEntry.
54
    
55
    :return: CalendarListEntry object with calendar data
56
    """
57
```
58

59
## CalendarListEntry Class
60

61
### Calendar List Entry Creation
62

63
```python { .api }
64
class CalendarListEntry(Calendar):
65
    def __init__(
66
        self,
67
        calendar_id: str,
68
        summary_override = None,
69
        color_id = None,
70
        background_color = None,
71
        foreground_color = None,
72
        hidden = None,
73
        selected = None,
74
        default_reminders = None,
75
        notification_types = None,
76
        primary = None,
77
        deleted = None,
78
        access_role = None,
79
        summary = None,
80
        description = None,
81
        location = None,
82
        timezone = None,
83
        conference_properties = None,
84
        _etag = None,
85
        _kind = None
86
    ):
87
        """
88
        Create a calendar list entry with user-specific settings.
89
        
90
        :param calendar_id: Unique calendar identifier (required)
91
        :param summary_override: Override for calendar title display
92
        :param color_id: Color ID for calendar display (1-24)
93
        :param background_color: Custom background color (hex format)
94
        :param foreground_color: Custom foreground color (hex format)  
95
        :param hidden: Whether calendar is hidden from list
96
        :param selected: Whether calendar is selected/visible
97
        :param default_reminders: List of default reminder objects
98
        :param notification_types: List of notification type strings
99
        :param primary: Whether this is the primary calendar (read-only)
100
        :param deleted: Whether calendar is deleted (read-only)
101
        :param access_role: User's access role for this calendar (read-only)
102
        :param summary: Calendar summary/title
103
        :param description: Calendar description
104
        :param location: Calendar location
105
        :param timezone: Calendar time zone
106
        :param conference_properties: Conference solution properties
107
        """
108
```
109

110
### Calendar List Entry Properties
111

112
```python { .api }
113
@property
114
def color_id(self) -> str:
115
    """Color ID for the calendar (1-24)."""
116

117
@color_id.setter
118
def color_id(self, value: str):
119
    """
120
    Set color ID and reset custom colors.
121
    
122
    :param value: Color ID string (1-24)
123
    """
124
```
125

126
## Calendar Service Methods
127

128
### Calendar CRUD Operations
129

130
```python { .api }
131
def get_calendar(self, calendar_id: str):
132
    """
133
    Retrieve calendar metadata by ID.
134
    
135
    :param calendar_id: Unique identifier for the calendar
136
    :return: Calendar object
137
    """
138

139
def add_calendar(self, calendar):
140
    """
141
    Create a new secondary calendar.
142
    
143
    :param calendar: Calendar object to create
144
    :return: Created Calendar object with assigned ID
145
    """
146

147
def update_calendar(self, calendar, calendar_id = None):
148
    """
149
    Update calendar metadata.
150
    
151
    :param calendar: Calendar object with changes
152
    :param calendar_id: Calendar ID (defaults to calendar.id)
153
    :return: Updated Calendar object
154
    """
155

156
def delete_calendar(self, calendar_id: str):
157
    """
158
    Delete a secondary calendar and all its events.
159
    
160
    :param calendar_id: ID of calendar to delete
161
    """
162

163
def clear_calendar(self, calendar_id = None):
164
    """
165
    Remove all events from a calendar.
166
    
167
    :param calendar_id: Calendar ID (defaults to default_calendar)
168
    """
169
```
170

171
### Calendar List Operations
172

173
```python { .api }
174
def get_calendar_list(
175
    self,
176
    min_access_role = None,
177
    max_results = None,
178
    page_token = None,
179
    show_deleted = None,
180
    show_hidden = None,
181
    sync_token = None
182
):
183
    """
184
    Retrieve the user's calendar list.
185
    
186
    :param min_access_role: Minimum access role filter ('owner', 'reader', etc.)
187
    :param max_results: Maximum number of calendars to return
188
    :param page_token: Token for pagination
189
    :param show_deleted: Whether to include deleted calendars
190
    :param show_hidden: Whether to include hidden calendars
191
    :param sync_token: Token for incremental sync
192
    :return: Generator yielding CalendarListEntry objects
193
    """
194

195
def get_calendar_list_entry(self, calendar_id: str):
196
    """
197
    Get specific calendar list entry by ID.
198
    
199
    :param calendar_id: Calendar identifier
200
    :return: CalendarListEntry object
201
    """
202

203
def add_calendar_list_entry(self, calendar_list_entry):
204
    """
205
    Add an existing calendar to the user's calendar list.
206
    
207
    :param calendar_list_entry: CalendarListEntry object to add
208
    :return: Added CalendarListEntry object
209
    """
210

211
def update_calendar_list_entry(
212
    self,
213
    calendar_list_entry,
214
    calendar_id = None,
215
    color_rgb_format = None
216
):
217
    """
218
    Update user-specific settings for a calendar.
219
    
220
    :param calendar_list_entry: CalendarListEntry object with changes
221
    :param calendar_id: Calendar ID (defaults to entry.id)
222
    :param color_rgb_format: Whether to use RGB format for colors
223
    :return: Updated CalendarListEntry object
224
    """
225

226
def delete_calendar_list_entry(self, calendar_id: str):
227
    """
228
    Remove a calendar from the user's calendar list.
229
    
230
    :param calendar_id: Calendar ID to remove from list
231
    """
232
```
233

234
## Calendar Constants
235

236
### Notification Types
237

238
```python { .api }
239
class NotificationType:
240
    EVENT_CREATION = "eventCreation"       # New event created
241
    EVENT_CHANGE = "eventChange"           # Event modified
242
    EVENT_CANCELLATION = "eventCancellation" # Event cancelled
243
    EVENT_RESPONSE = "eventResponse"       # Attendee responded
244
    AGENDA = "agenda"                      # Daily agenda
245
```
246

247
### Access Roles
248

249
```python { .api }
250
class AccessRoles:
251
    FREE_BUSY_READER = "freeBusyReader"   # Can see free/busy information
252
    READER = "reader"                     # Can read events
253
    WRITER = "writer"                     # Can create and modify events  
254
    OWNER = "owner"                       # Full control over calendar
255
```
256

257
## Basic Usage Examples
258

259
### Creating and Managing Calendars
260

261
```python
262
from gcsa.google_calendar import GoogleCalendar
263
from gcsa.calendar import Calendar, CalendarListEntry
264
from gcsa.reminders import EmailReminder
265

266
gc = GoogleCalendar()
267

268
# Create a new calendar
269
project_calendar = Calendar(
270
    summary="Project Alpha",
271
    description="Calendar for Project Alpha milestones and meetings",
272
    location="Building A",
273
    timezone="America/New_York"
274
)
275
created_calendar = gc.add_calendar(project_calendar)
276
print(f"Created calendar: {created_calendar.id}")
277

278
# Update calendar metadata
279
created_calendar.description = "Updated: Project Alpha calendar with all events"
280
gc.update_calendar(created_calendar)
281

282
# Get calendar details
283
calendar = gc.get_calendar(created_calendar.id)
284
print(f"Calendar: {calendar.summary} in {calendar.timezone}")
285
```
286

287
### Working with Calendar Lists
288

289
```python
290
from gcsa.google_calendar import GoogleCalendar
291
from gcsa.calendar import CalendarListEntry, NotificationType
292

293
gc = GoogleCalendar()
294

295
# Get all calendars in user's list
296
print("User's calendars:")
297
for calendar_entry in gc.get_calendar_list():
298
    print(f"- {calendar_entry.summary} ({calendar_entry.access_role})")
299
    if calendar_entry.primary:
300
        print("  [PRIMARY CALENDAR]")
301

302
# Get specific calendar list entry
303
calendar_entry = gc.get_calendar_list_entry("calendar_id")
304
```
305

306
### Customizing Calendar Appearance
307

308
```python
309
from gcsa.google_calendar import GoogleCalendar
310
from gcsa.calendar import CalendarListEntry
311

312
gc = GoogleCalendar()
313

314
# Update calendar display settings
315
calendar_entry = gc.get_calendar_list_entry("calendar_id")
316
calendar_entry.color_id = "5"  # Yellow color
317
calendar_entry.summary_override = "My Project Calendar"
318
calendar_entry.hidden = False
319
calendar_entry.selected = True
320

321
gc.update_calendar_list_entry(calendar_entry)
322

323
# Use custom colors (instead of predefined color IDs)
324
calendar_entry.background_color = "#FF5722"  # Deep Orange
325
calendar_entry.foreground_color = "#FFFFFF"  # White
326
calendar_entry.color_id = None  # Clear predefined color
327
gc.update_calendar_list_entry(calendar_entry)
328
```
329

330
### Setting Default Reminders
331

332
```python
333
from gcsa.google_calendar import GoogleCalendar
334
from gcsa.calendar import CalendarListEntry
335
from gcsa.reminders import EmailReminder, PopupReminder
336

337
gc = GoogleCalendar()
338

339
# Set default reminders for a calendar
340
calendar_entry = gc.get_calendar_list_entry("calendar_id")
341
calendar_entry.default_reminders = [
342
    EmailReminder(minutes_before_start=60),    # 1 hour email reminder
343
    PopupReminder(minutes_before_start=15)     # 15 minute popup reminder
344
]
345

346
gc.update_calendar_list_entry(calendar_entry)
347
```
348

349
### Notification Settings
350

351
```python
352
from gcsa.google_calendar import GoogleCalendar
353
from gcsa.calendar import CalendarListEntry, NotificationType
354

355
gc = GoogleCalendar()
356

357
# Configure calendar notifications
358
calendar_entry = gc.get_calendar_list_entry("calendar_id")
359
calendar_entry.notification_types = [
360
    NotificationType.EVENT_CREATION,
361
    NotificationType.EVENT_CHANGE,
362
    NotificationType.EVENT_RESPONSE
363
]
364

365
gc.update_calendar_list_entry(calendar_entry)
366
```
367

368
### Calendar Colors
369

370
Calendars support 24 predefined colors (color_id 1-24):
371

372
```python
373
from gcsa.google_calendar import GoogleCalendar
374

375
gc = GoogleCalendar()
376

377
# Get available calendar colors
378
calendar_colors = gc.list_calendar_colors()
379
for color_id, color_info in calendar_colors.items():
380
    print(f"Color {color_id}: {color_info['background']} / {color_info['foreground']}")
381

382
# Apply color to calendar
383
calendar_entry = gc.get_calendar_list_entry("calendar_id")
384
calendar_entry.color_id = "10"  # Apply specific color
385
gc.update_calendar_list_entry(calendar_entry)
386
```
387

388
### Managing Multiple Project Calendars
389

390
```python
391
from gcsa.google_calendar import GoogleCalendar
392
from gcsa.calendar import Calendar, CalendarListEntry
393

394
gc = GoogleCalendar()
395

396
# Create calendars for different projects
397
projects = [
398
    {"name": "Project Alpha", "color": "1"},
399
    {"name": "Project Beta", "color": "2"}, 
400
    {"name": "Project Gamma", "color": "3"}
401
]
402

403
created_calendars = []
404
for project in projects:
405
    # Create calendar
406
    calendar = Calendar(
407
        summary=project["name"],
408
        description=f"Calendar for {project['name']} events",
409
        timezone="America/New_York"
410
    )
411
    created_calendar = gc.add_calendar(calendar)
412
    
413
    # Configure display settings
414
    calendar_entry = gc.get_calendar_list_entry(created_calendar.id)
415
    calendar_entry.color_id = project["color"]
416
    gc.update_calendar_list_entry(calendar_entry)
417
    
418
    created_calendars.append(created_calendar)
419
    print(f"Created: {project['name']} ({created_calendar.id})")
420

421
# List all project calendars
422
print("\nProject calendars:")
423
for cal_entry in gc.get_calendar_list():
424
    if cal_entry.summary and "Project" in cal_entry.summary:
425
        print(f"- {cal_entry.summary} (Color: {cal_entry.color_id})")
426
```
427

428
### Calendar Sharing Setup
429

430
```python
431
from gcsa.google_calendar import GoogleCalendar
432
from gcsa.calendar import Calendar
433
from gcsa.acl import AccessControlRule, ACLRole, ACLScopeType
434

435
gc = GoogleCalendar()
436

437
# Create a shared team calendar
438
team_calendar = Calendar(
439
    summary="Team Calendar",
440
    description="Shared calendar for team events",
441
    timezone="America/New_York"
442
)
443
created_calendar = gc.add_calendar(team_calendar)
444

445
# Add sharing permissions (see access-control.md for details)
446
# Make calendar public for read access
447
public_rule = AccessControlRule(
448
    role=ACLRole.READER,
449
    scope_type=ACLScopeType.DEFAULT
450
)
451
gc.add_acl_rule(public_rule, calendar_id=created_calendar.id)
452
```
453

454
### Calendar Cleanup
455

456
```python
457
from gcsa.google_calendar import GoogleCalendar
458

459
gc = GoogleCalendar()
460

461
# Clear all events from a calendar
462
gc.clear_calendar("calendar_id")
463

464
# Remove calendar from user's list (but keep the calendar)
465
gc.delete_calendar_list_entry("calendar_id")
466

467
# Delete calendar completely (only for owned calendars)
468
gc.delete_calendar("calendar_id")
469
```
470

471
### Working with Primary Calendar
472

473
```python
474
from gcsa.google_calendar import GoogleCalendar
475

476
# Primary calendar is the user's main calendar
477
gc = GoogleCalendar()  # Uses 'primary' as default calendar
478

479
# Get primary calendar details
480
primary_calendar = gc.get_calendar('primary')
481
print(f"Primary calendar: {primary_calendar.summary}")
482

483
# Get primary calendar list entry for customization
484
primary_entry = gc.get_calendar_list_entry('primary')
485
print(f"Primary calendar timezone: {primary_entry.timezone}")
486

487
# Note: Cannot delete primary calendar, only clear its events
488
gc.clear_calendar('primary')  # Removes all events from primary calendar
489
```
490

491
### Error Handling for Calendars
492

493
```python
494
from gcsa.google_calendar import GoogleCalendar
495
from gcsa.calendar import Calendar
496
from googleapiclient.errors import HttpError
497

498
gc = GoogleCalendar()
499

500
try:
501
    # Attempt to get non-existent calendar
502
    calendar = gc.get_calendar("invalid_calendar_id")
503
except HttpError as e:
504
    if e.resp.status == 404:
505
        print("Calendar not found")
506
    elif e.resp.status == 403:
507
        print("Access denied to calendar")
508
    else:
509
        print(f"API error: {e}")
510

511
try:
512
    # Attempt to delete primary calendar (not allowed)
513
    gc.delete_calendar("primary")
514
except HttpError as e:
515
    print(f"Cannot delete primary calendar: {e}")
516
```
517

518
The Calendar and CalendarListEntry classes provide comprehensive calendar management capabilities, allowing users to create, organize, customize, and share calendars while maintaining fine-grained control over display settings, notifications, and access permissions.