Calendars and Calendar list

Calendars in gcsa are represented by the Calendar and CalendarListEntry classes.

Calendars vs Calendar List

The Calendars collection represents all existing calendars. It can be used to create and delete calendars. You can also retrieve or set global properties shared across all users with access to a calendar. For example, a calendar’s title and default time zone are global properties.

The Calendar List is a collection of all calendar entries that a user has added to their list (shown in the left panel of the web UI). You can use it to add and remove existing calendars to/from the users’ list. You also use it to retrieve and set the values of user-specific calendar properties, such as default reminders. Another example is foreground color, since different users can have different colors set for the same calendar.

The GoogleCalendar is a service responsible for processing API requests.

Calendars

gcsa allows you to create a new calendar, retrieve, update, delete and clear existing calendars.

To do so, create a GoogleCalendar instance (see Getting started to get your credentials):

from gcsa.google_calendar import GoogleCalendar

gc = GoogleCalendar()

Get calendar by id

This returns an objects that stores metadata of the calendar (see more in Calendar).

Get a calendar specified as a default in GoogleCalendar()

calendar = gc.get_calendar()

To get a calendar other than the one specified as a default in GoogleCalendar()

calendar = gc.get_calendar('<calendar_id>')

Add a secondary calendar

from gcsa.calendar import Calendar

calendar = Calendar(
    'Travel calendar',
    description='Calendar for travel related events'
)
calendar = gc.add_calendar(calendar)

Update calendar

calendar.summary = 'New summary'
calendar.description = 'New description'
calendar = gc.update_calendar(calendar)

Delete calendar

gc.delete_calendar(calendar)

or by id

gc.delete_calendar('<calendar_id>')

Calendar has to have calendar_id to be updated or deleted. Calendars that you get from get_calendar_list() method already have their ids. You can also delete the calendar by providing its id.

Clear calendar

You can only clear (remove all events from) primary calendar.

gc.clear_calendar()

Warning

This will always try to clear a primary calendar, regardless of the default_calendar value.

Calendar List

gcsa allows you to add an existing calendar into the user’s calendar list, retrieve user’s calendar list, retrieve, update, and delete single entries in the user’s calendar list.

To do so, create a GoogleCalendar instance (see Getting started to get your credentials):

from gcsa.google_calendar import GoogleCalendar

gc = GoogleCalendar()

Get user’s calendar list

This returns the collection of calendars in the user’s calendar list. (see more in CalendarListEntry).

for calendar in gc.get_calendar_list():
    print(calendar)

you can include deleted and hidden entries and specify the minimal access role:

from gcsa.calendar import AccessRoles

gc.get_calendar_list(
    min_access_role=AccessRoles.READER
    show_deleted=True,
    show_hidden=True
)

Get calendar list entry by id

Get a calendar specified as a default in GoogleCalendar()

gc.get_calendar_list_entry()

To get calendar other then the one specified as a default in GoogleCalendar()

gc.get_calendar_list_entry('calendar_id')

Add calendar list entry

This adds an existing calendar into the user’s calendar list (see more in CalendarListEntry):

from gcsa.calendar import CalendarListEntry

calendar_list_entry = CalendarListEntry(
    calendar_id='calendar_id',
    summary_override='Holidays in Czechia'
)
gc.add_calendar_list_entry(calendar_list_entry)

You can make a CalendarListEntry out of Calendar with to_calendar_list_entry() method:

calendar = Calendar(
    calendar_id='calendar_id',
    summary='Státní svátky v ČR'
)
calendar_list_entry = calendar.to_calendar_list_entry(
    summary_override='Holidays in Czechia'
)
gc.add_calendar_list_entry(calendar_list_entry)

Update calendar list entry

calendar_list_entry.summary_override = 'Holidays in Czechia 2022'
gc.update_calendar_list_entry(calendar_list_entry)

Delete calendar list entry

You can use CalendarListEntry, Calendar, or calendar id:

gc.delete_calendar_list_entry(calendar)

or

gc.delete_calendar_list_entry(calendar_list_entry)

or

gc.delete_calendar_list_entry('<calendar_id>')