0
# GCSA - Google Calendar Simple API
1
2
A Python library that provides a simple, object-oriented interface to the Google Calendar API. GCSA abstracts away the complexity of the official Google Calendar API while maintaining full functionality, offering intuitive classes and methods for managing calendars, events, attendees, reminders, and access controls.
3
4
## Package Information
5
6
- **Package Name**: gcsa
7
- **Language**: Python
8
- **Installation**: `pip install gcsa`
9
- **Dependencies**: `google-api-python-client`, `google-auth-httplib2`, `google-auth-oauthlib`, `python-dateutil`, `beautiful_date`, `tzlocal`
10
11
## Core Imports
12
13
All classes and functions must be imported directly from their respective modules since `__init__.py` files are empty:
14
15
```python
16
from gcsa.google_calendar import GoogleCalendar
17
from gcsa.event import Event, Visibility, Transparency
18
from gcsa.calendar import Calendar, CalendarListEntry
19
from gcsa.attendee import Attendee, ResponseStatus
20
from gcsa.attachment import Attachment
21
from gcsa.reminders import EmailReminder, PopupReminder
22
from gcsa.recurrence import Recurrence, DAILY, WEEKLY, MONTHLY
23
```
24
25
## Basic Usage
26
27
```python
28
from gcsa.google_calendar import GoogleCalendar
29
from gcsa.event import Event
30
from datetime import datetime
31
32
# Initialize the Google Calendar client
33
gc = GoogleCalendar()
34
35
# Create a simple event
36
event = Event(
37
summary="Team Meeting",
38
start=datetime(2024, 1, 15, 10, 0),
39
end=datetime(2024, 1, 15, 11, 0),
40
description="Weekly team sync",
41
location="Conference Room A"
42
)
43
44
# Add the event to the calendar
45
gc.add_event(event)
46
47
# List upcoming events
48
for event in gc.get_events(time_min=datetime.now()):
49
print(f"{event.summary}: {event.start}")
50
51
# Get a specific event
52
event = gc.get_event("event_id")
53
54
# Update an event
55
event.summary = "Updated Meeting Title"
56
gc.update_event(event)
57
58
# Delete an event
59
gc.delete_event("event_id")
60
```
61
62
## Architecture
63
64
GCSA uses a service-oriented architecture with clear separation of concerns:
65
66
- **GoogleCalendar**: Main service class that inherits from all service mixins
67
- **Data Models**: Rich Python objects representing calendar entities (Event, Calendar, Attendee, etc.)
68
- **Service Classes**: Specialized API interaction classes for different Google Calendar resources
69
- **Serializers**: Handle conversion between Python objects and Google Calendar API format
70
- **Utilities**: Helper functions for date/time handling and data manipulation
71
72
The library provides both high-level convenience methods and direct access to Google Calendar API features, making it suitable for simple automation scripts and complex calendar management applications.
73
74
## Capabilities
75
76
### Core Calendar Operations
77
78
Main GoogleCalendar client and basic calendar management operations including authentication, calendar CRUD operations, and event management.
79
80
```python { .api }
81
class GoogleCalendar:
82
def __init__(
83
self,
84
default_calendar: str = 'primary',
85
*,
86
credentials = None,
87
credentials_path = None,
88
token_path = None,
89
save_token: bool = True,
90
read_only: bool = False,
91
authentication_flow_host: str = 'localhost',
92
authentication_flow_port: int = 8080,
93
authentication_flow_bind_addr = None,
94
open_browser = None
95
): ...
96
97
def get_events(self, **kwargs): ...
98
def add_event(self, event, **kwargs): ...
99
def update_event(self, event, **kwargs): ...
100
def delete_event(self, event_id, **kwargs): ...
101
```
102
103
[Core Calendar Operations](./core-operations.md)
104
105
### Event Management
106
107
Comprehensive event handling including creation, scheduling, recurring events, and event metadata management.
108
109
```python { .api }
110
class Event:
111
def __init__(
112
self,
113
summary,
114
start = None,
115
end = None,
116
timezone = None,
117
event_id = None,
118
description = None,
119
location = None,
120
recurrence = None,
121
color_id = None,
122
visibility = None,
123
attendees = None,
124
attachments = None,
125
conference_solution = None,
126
reminders = None
127
): ...
128
129
def add_attendee(self, attendee): ...
130
def add_attachment(self, file_url, title, mime_type): ...
131
def add_email_reminder(self, minutes_before_start, days_before=None, at=None): ...
132
def add_popup_reminder(self, minutes_before_start, days_before=None, at=None): ...
133
```
134
135
[Event Management](./events.md)
136
137
### Calendar Management
138
139
Calendar creation, configuration, and calendar list management with user-specific settings and permissions.
140
141
```python { .api }
142
class Calendar:
143
def __init__(
144
self,
145
summary,
146
calendar_id = None,
147
description = None,
148
location = None,
149
timezone = None,
150
allowed_conference_solution_types = None
151
): ...
152
153
class CalendarListEntry:
154
def __init__(
155
self,
156
calendar_id,
157
summary_override = None,
158
color_id = None,
159
background_color = None,
160
foreground_color = None,
161
hidden = None,
162
selected = None,
163
default_reminders = None,
164
notification_types = None
165
): ...
166
```
167
168
[Calendar Management](./calendars.md)
169
170
### Attendees and People
171
172
Managing event attendees, organizers, and participant information including RSVP status and permissions.
173
174
```python { .api }
175
class Attendee:
176
def __init__(
177
self,
178
email,
179
display_name = None,
180
comment = None,
181
optional = None,
182
is_resource = None,
183
additional_guests = None
184
): ...
185
186
class Person:
187
def __init__(
188
self,
189
email,
190
display_name = None
191
): ...
192
```
193
194
[Attendees and People](./attendees.md)
195
196
### Recurrence and Scheduling
197
198
Advanced scheduling features including recurring events, recurrence rules, and complex scheduling patterns.
199
200
```python { .api }
201
class Recurrence:
202
@staticmethod
203
def rule(
204
freq,
205
until = None,
206
count = None,
207
interval = None,
208
by_month = None,
209
by_month_day = None,
210
by_year_day = None,
211
by_week_no = None,
212
by_weekday = None,
213
by_hour = None,
214
by_minute = None,
215
by_second = None,
216
by_set_pos = None,
217
week_start = None
218
): ...
219
220
@staticmethod
221
def dates(*dates): ...
222
@staticmethod
223
def times(*datetimes): ...
224
```
225
226
[Recurrence and Scheduling](./recurrence.md)
227
228
### Reminders and Notifications
229
230
Event reminder system supporting email and popup notifications with flexible timing options.
231
232
```python { .api }
233
class EmailReminder:
234
def __init__(
235
self,
236
minutes_before_start = None,
237
days_before = None,
238
at = None
239
): ...
240
241
class PopupReminder:
242
def __init__(
243
self,
244
minutes_before_start = None,
245
days_before = None,
246
at = None
247
): ...
248
```
249
250
[Reminders and Notifications](./reminders.md)
251
252
### Conference Solutions
253
254
Integration with video conferencing platforms including Google Meet, Hangouts, and third-party solutions.
255
256
```python { .api }
257
class ConferenceSolution:
258
def __init__(
259
self,
260
entry_points = None,
261
solution_type = None,
262
name = None,
263
icon_uri = None,
264
conference_id = None,
265
signature = None,
266
notes = None
267
): ...
268
269
class ConferenceSolutionCreateRequest:
270
def __init__(
271
self,
272
solution_type,
273
request_id = None
274
): ...
275
```
276
277
[Conference Solutions](./conferences.md)
278
279
### Access Control and Permissions
280
281
Calendar sharing, access control rules, and permission management for collaborative calendar usage.
282
283
```python { .api }
284
class AccessControlRule:
285
def __init__(
286
self,
287
role,
288
scope_type,
289
acl_id = None,
290
scope_value = None
291
): ...
292
```
293
294
[Access Control and Permissions](./access-control.md)
295
296
### Free/Busy and Availability
297
298
Checking calendar availability, free/busy time queries, and scheduling conflict detection.
299
300
```python { .api }
301
class FreeBusy:
302
def __init__(
303
self,
304
time_min,
305
time_max,
306
groups = None,
307
calendars = None,
308
groups_errors = None,
309
calendars_errors = None
310
): ...
311
```
312
313
[Free/Busy and Availability](./free-busy.md)
314
315
## Core Types
316
317
```python { .api }
318
# Event visibility options
319
class Visibility:
320
DEFAULT = "default"
321
PUBLIC = "public"
322
PRIVATE = "private"
323
324
# Event transparency options
325
class Transparency:
326
OPAQUE = "opaque"
327
TRANSPARENT = "transparent"
328
329
# Attendee response status
330
class ResponseStatus:
331
NEEDS_ACTION = "needsAction"
332
DECLINED = "declined"
333
TENTATIVE = "tentative"
334
ACCEPTED = "accepted"
335
336
# Conference solution types
337
class SolutionType:
338
HANGOUT = "hangout"
339
NAMED_HANGOUT = "namedHangout"
340
HANGOUTS_MEET = "hangoutsMeet"
341
ADD_ON = "addOn"
342
343
# ACL roles and scope types
344
class ACLRole:
345
NONE = "none"
346
FREE_BUSY_READER = "freeBusyReader"
347
READER = "reader"
348
WRITER = "writer"
349
OWNER = "owner"
350
351
class ACLScopeType:
352
DEFAULT = "default"
353
USER = "user"
354
GROUP = "group"
355
DOMAIN = "domain"
356
357
# Recurrence frequency constants
358
SECONDLY = "SECONDLY"
359
MINUTELY = "MINUTELY"
360
HOURLY = "HOURLY"
361
DAILY = "DAILY"
362
WEEKLY = "WEEKLY"
363
MONTHLY = "MONTHLY"
364
YEARLY = "YEARLY"
365
366
# Day constants for recurrence
367
SUNDAY = "SU"
368
MONDAY = "MO"
369
TUESDAY = "TU"
370
WEDNESDAY = "WE"
371
THURSDAY = "TH"
372
FRIDAY = "FR"
373
SATURDAY = "SA"
374
```