0
# Core Calendar Operations
1

2
The GoogleCalendar class is the main entry point for interacting with the Google Calendar API. It provides authentication, basic calendar operations, and serves as the primary client for all calendar management tasks.
3

4
## Package Information
5

6
```python
7
from gcsa.google_calendar import GoogleCalendar
8
```
9

10
## GoogleCalendar Client
11

12
### Authentication and Initialization
13

14
```python { .api }
15
class GoogleCalendar:
16
    def __init__(
17
        self,
18
        default_calendar: str = 'primary',
19
        *,
20
        credentials = None,
21
        credentials_path = None,
22
        token_path = None,
23
        save_token: bool = True,
24
        read_only: bool = False,
25
        authentication_flow_host: str = 'localhost',
26
        authentication_flow_port: int = 8080,
27
        authentication_flow_bind_addr = None,
28
        open_browser = None
29
    ):
30
        """
31
        Initialize GoogleCalendar client with authentication options.
32
        
33
        :param default_calendar: Default calendar ID to use for operations ('primary' for user's main calendar)
34
        :param credentials: Pre-configured credentials object
35
        :param credentials_path: Path to credentials JSON file
36
        :param token_path: Path to store/load authentication token
37
        :param save_token: Whether to save authentication token for reuse
38
        :param read_only: Whether to request read-only access
39
        :param authentication_flow_host: Host for OAuth flow
40
        :param authentication_flow_port: Port for OAuth flow
41
        :param authentication_flow_bind_addr: Bind address for OAuth flow
42
        :param open_browser: Whether to automatically open browser for authentication
43
        """
44
```
45

46
### Basic Event Operations
47

48
```python { .api }
49
def get_events(
50
    self,
51
    calendar_id = None,
52
    time_min = None,
53
    time_max = None,
54
    time_zone = None,
55
    single_events = None,
56
    order_by = None,
57
    page_token = None,
58
    max_results = None,
59
    show_deleted = None,
60
    show_hidden_invitations = None,
61
    updated_min = None,
62
    sync_token = None,
63
    private_extended_property = None,
64
    shared_extended_property = None,
65
    q = None
66
):
67
    """
68
    Retrieve events from calendar with optional filtering and pagination.
69
    
70
    :param calendar_id: Calendar ID to query (defaults to default_calendar)
71
    :param time_min: Lower bound for event start time (datetime or RFC3339 string)
72
    :param time_max: Upper bound for event start time (datetime or RFC3339 string)
73
    :param time_zone: Time zone for returned times
74
    :param single_events: Whether to expand recurring events into instances
75
    :param order_by: Sort order ('startTime' or 'updated')
76
    :param page_token: Token for pagination
77
    :param max_results: Maximum number of events to return
78
    :param show_deleted: Whether to include deleted events
79
    :param show_hidden_invitations: Whether to include hidden invitations
80
    :param updated_min: Lower bound for last modification time
81
    :param sync_token: Token for incremental sync
82
    :param private_extended_property: Private extended property filter
83
    :param shared_extended_property: Shared extended property filter
84
    :param q: Free text search terms
85
    :return: Generator yielding Event objects
86
    """
87

88
def get_event(self, event_id: str, calendar_id = None):
89
    """
90
    Retrieve a specific event by ID.
91
    
92
    :param event_id: Unique identifier for the event
93
    :param calendar_id: Calendar ID (defaults to default_calendar)
94
    :return: Event object
95
    """
96

97
def add_event(self, event, calendar_id = None, send_updates = None):
98
    """
99
    Add a new event to the calendar.
100
    
101
    :param event: Event object to add
102
    :param calendar_id: Calendar ID (defaults to default_calendar)
103
    :param send_updates: Whether to send notifications ('all', 'externalOnly', 'none')
104
    :return: Created Event object with assigned ID
105
    """
106

107
def update_event(self, event, calendar_id = None, send_updates = None):
108
    """
109
    Update an existing event.
110
    
111
    :param event: Event object with changes
112
    :param calendar_id: Calendar ID (defaults to default_calendar)
113
    :param send_updates: Whether to send notifications ('all', 'externalOnly', 'none')
114
    :return: Updated Event object
115
    """
116

117
def delete_event(self, event_id: str, calendar_id = None, send_updates = None):
118
    """
119
    Delete an event from the calendar.
120
    
121
    :param event_id: ID of event to delete
122
    :param calendar_id: Calendar ID (defaults to default_calendar)
123
    :param send_updates: Whether to send notifications ('all', 'externalOnly', 'none')
124
    """
125
```
126

127
### Advanced Event Operations
128

129
```python { .api }
130
def get_instances(
131
    self,
132
    event,
133
    time_min = None,
134
    time_max = None,
135
    time_zone = None,
136
    max_results = None,
137
    order_by = None,
138
    page_token = None,
139
    show_deleted = None,
140
    original_start = None
141
):
142
    """
143
    Get instances of a recurring event.
144
    
145
    :param event: Recurring event object or event ID
146
    :param time_min: Lower bound for instance start time
147
    :param time_max: Upper bound for instance start time
148
    :param time_zone: Time zone for returned times
149
    :param max_results: Maximum number of instances to return
150
    :param order_by: Sort order ('startTime' or 'updated')
151
    :param page_token: Token for pagination
152
    :param show_deleted: Whether to include deleted instances
153
    :param original_start: Original start time for recurring event modifications
154
    :return: Generator yielding Event instances
155
    """
156

157
def add_quick_event(self, quick_add_text: str, calendar_id = None):
158
    """
159
    Quickly add an event using natural language.
160
    
161
    :param quick_add_text: Natural language description of event
162
    :param calendar_id: Calendar ID (defaults to default_calendar)
163
    :return: Created Event object
164
    """
165

166
def import_event(self, event, calendar_id = None):
167
    """
168
    Import an event into the calendar.
169
    
170
    :param event: Event object to import
171
    :param calendar_id: Calendar ID (defaults to default_calendar)
172
    :return: Imported Event object
173
    """
174

175
def move_event(
176
    self,
177
    event_id: str,
178
    destination_calendar_id: str,
179
    calendar_id = None,
180
    send_updates = None
181
):
182
    """
183
    Move an event to a different calendar.
184
    
185
    :param event_id: ID of event to move
186
    :param destination_calendar_id: Target calendar ID
187
    :param calendar_id: Source calendar ID (defaults to default_calendar)
188
    :param send_updates: Whether to send notifications ('all', 'externalOnly', 'none')
189
    :return: Moved Event object
190
    """
191
```
192

193
### Calendar Management Operations
194

195
```python { .api }
196
def get_calendar(self, calendar_id: str):
197
    """
198
    Retrieve calendar metadata by ID.
199
    
200
    :param calendar_id: Unique identifier for the calendar
201
    :return: Calendar object
202
    """
203

204
def add_calendar(self, calendar):
205
    """
206
    Create a new secondary calendar.
207
    
208
    :param calendar: Calendar object to create
209
    :return: Created Calendar object with assigned ID
210
    """
211

212
def update_calendar(self, calendar, calendar_id = None):
213
    """
214
    Update calendar metadata.
215
    
216
    :param calendar: Calendar object with changes
217
    :param calendar_id: Calendar ID (defaults to calendar.id)
218
    :return: Updated Calendar object
219
    """
220

221
def delete_calendar(self, calendar_id: str):
222
    """
223
    Delete a secondary calendar.
224
    
225
    :param calendar_id: ID of calendar to delete
226
    """
227

228
def clear_calendar(self, calendar_id = None):
229
    """
230
    Remove all events from a calendar.
231
    
232
    :param calendar_id: Calendar ID (defaults to default_calendar)
233
    """
234

235
def clear(self):
236
    """
237
    Alias for clear_calendar() using default calendar.
238
    """
239
```
240

241
### Iterator and Indexing Support
242

243
```python { .api }
244
def __iter__(self):
245
    """
246
    Iterate over events in the default calendar.
247
    
248
    :return: Generator yielding Event objects
249
    """
250

251
def __getitem__(self, key):
252
    """
253
    Access events by index or slice.
254
    
255
    :param key: Integer index or slice object
256
    :return: Event object or list of Event objects
257
    """
258
```
259

260
## Authentication Examples
261

262
### Basic Authentication
263

264
```python
265
from gcsa.google_calendar import GoogleCalendar
266

267
# Default authentication (uses 'credentials.json' and saves token)
268
gc = GoogleCalendar()
269

270
# Specify custom credentials file
271
gc = GoogleCalendar(credentials_path='path/to/credentials.json')
272

273
# Read-only access
274
gc = GoogleCalendar(read_only=True)
275
```
276

277
### Advanced Authentication
278

279
```python
280
from google.oauth2.credentials import Credentials
281
from gcsa.google_calendar import GoogleCalendar
282

283
# Use pre-configured credentials
284
creds = Credentials.from_authorized_user_info(info)
285
gc = GoogleCalendar(credentials=creds)
286

287
# Custom OAuth flow settings
288
gc = GoogleCalendar(
289
    authentication_flow_host='0.0.0.0',
290
    authentication_flow_port=9090,
291
    open_browser=False
292
)
293
```
294

295
## Basic Usage Examples
296

297
### Simple Event Management
298

299
```python
300
from gcsa.google_calendar import GoogleCalendar
301
from gcsa.event import Event
302
from datetime import datetime, timedelta
303

304
# Initialize client
305
gc = GoogleCalendar()
306

307
# Create and add an event
308
event = Event(
309
    summary="Team Meeting",
310
    start=datetime(2024, 1, 15, 10, 0),
311
    end=datetime(2024, 1, 15, 11, 0),
312
    description="Weekly team sync",
313
    location="Conference Room A"
314
)
315
created_event = gc.add_event(event)
316
print(f"Created event: {created_event.id}")
317

318
# Get upcoming events
319
today = datetime.now()
320
next_week = today + timedelta(days=7)
321

322
for event in gc.get_events(time_min=today, time_max=next_week):
323
    print(f"{event.summary}: {event.start}")
324

325
# Update an event
326
event.summary = "Updated Team Meeting"
327
gc.update_event(event)
328

329
# Delete an event
330
gc.delete_event(created_event.id)
331
```
332

333
### Working with Multiple Calendars
334

335
```python
336
from gcsa.google_calendar import GoogleCalendar
337
from gcsa.calendar import Calendar
338

339
gc = GoogleCalendar()
340

341
# Create a new calendar
342
new_calendar = Calendar(
343
    summary="Project Calendar",
344
    description="Calendar for project events",
345
    timezone="America/New_York"
346
)
347
created_calendar = gc.add_calendar(new_calendar)
348

349
# Use specific calendar for events
350
gc_project = GoogleCalendar(default_calendar=created_calendar.id)
351

352
# Add event to specific calendar
353
project_event = Event(
354
    summary="Project Milestone",
355
    start=datetime(2024, 2, 1, 9, 0),
356
    end=datetime(2024, 2, 1, 10, 0)
357
)
358
gc_project.add_event(project_event)
359
```
360

361
### Advanced Event Queries
362

363
```python
364
from datetime import datetime, timedelta
365

366
gc = GoogleCalendar()
367

368
# Search events by text
369
meetings = gc.get_events(q="meeting")
370

371
# Get events with pagination
372
events_page1 = gc.get_events(max_results=10)
373
# Get next page using page_token from previous response
374

375
# Get only updated events since last sync
376
updated_events = gc.get_events(
377
    updated_min=datetime(2024, 1, 1),
378
    show_deleted=True
379
)
380

381
# Get events ordered by update time
382
recent_events = gc.get_events(
383
    order_by="updated",
384
    max_results=20
385
)
386
```
387

388
## Error Handling
389

390
```python
391
from gcsa.google_calendar import GoogleCalendar
392
from googleapiclient.errors import HttpError
393

394
gc = GoogleCalendar()
395

396
try:
397
    event = gc.get_event("invalid_event_id")
398
except HttpError as e:
399
    if e.resp.status == 404:
400
        print("Event not found")
401
    else:
402
        print(f"API error: {e}")
403
except Exception as e:
404
    print(f"Unexpected error: {e}")
405
```
406

407
## Send Updates Constants
408

409
```python { .api }
410
class SendUpdatesMode:
411
    ALL = "all"                    # Send notifications to all attendees
412
    EXTERNAL_ONLY = "externalOnly" # Send only to external attendees
413
    NONE = "none"                  # Do not send notifications
414
```
415

416
## Integration with Calendar List
417

418
```python
419
from gcsa.google_calendar import GoogleCalendar
420

421
gc = GoogleCalendar()
422

423
# Get user's calendar list
424
calendar_list = gc.get_calendar_list()
425
for cal_entry in calendar_list:
426
    print(f"Calendar: {cal_entry.summary} (ID: {cal_entry.id})")
427
    
428
    # Get events from this specific calendar
429
    events = gc.get_events(calendar_id=cal_entry.id, max_results=5)
430
    for event in events:
431
        print(f"  Event: {event.summary}")
432
```
433

434
The GoogleCalendar class serves as the central hub for all calendar operations, inheriting functionality from specialized service classes for events, calendars, ACL, free/busy queries, and more. It provides both high-level convenience methods and access to advanced Google Calendar API features.