GoogleCalendar

class gcsa.google_calendar.GoogleCalendar(default_calendar='primary', *, credentials=None, credentials_path=None, token_path=None, save_token=True, read_only=False, authentication_flow_host='localhost', authentication_flow_port=8080)

Collection of all supported methods for events and calendars management.

Specify credentials to use in requests or credentials_path and token_path to get credentials from.

Parameters

  • default_calendar (str) –

    Users email address or name/id of the calendar. Default: primary calendar of the user

    If user’s email or “primary” is specified, then primary calendar of the user is used. You don’t need to specify this parameter in this case as it is a default behaviour.

    To use a different calendar you need to specify its id. Go to calendar’s settings and sharing -> Integrate calendar -> Calendar ID.

  • credentials (Credentials) – Credentials with token and refresh token. If specified, credentials_path, token_path, and save_token are ignored. If not specified, credentials are retrieved from “token.pickle” file (specified in token_path or default path) or with authentication flow using secret from “credentials.json” (specified in credentials_path or default path)

  • credentials_path (str) – Path to “credentials.json” file. Default: ~/.credentials

  • token_path (str) – Existing path to load the token from, or path to save the token after initial authentication flow. Default: “token.pickle” in the same directory as the credentials_path

  • save_token (bool) – Whether to pickle token after authentication flow for future uses

  • read_only (bool) – If require read only access. Default: False

  • authentication_flow_host (str) – Host to receive response during authentication flow

  • authentication_flow_port (int) – Port to receive response during authentication flow

get_events(time_min=None, time_max=None, order_by=None, timezone='Etc/UTC', single_events=False, query=None, calendar_id=None, **kwargs)

Lists events.

Parameters

  • time_min (Optional[Union[date, datetime, BeautifulDate]]) – Staring date/datetime

  • time_max (Optional[Union[date, datetime, BeautifulDate]]) – Ending date/datetime

  • order_by (Optional[str]) – Order of the events. Possible values: “startTime”, “updated”. Default is unspecified stable order.

  • timezone (str) – Timezone formatted as an IANA Time Zone Database name, e.g. “Europe/Zurich”. By default, the computers local timezone is used if it is configured. UTC is used otherwise.

  • single_events (bool) – Whether to expand recurring events into instances and only return single one-off events and instances of recurring events, but not the underlying recurring events themselves.

  • query (Optional[str]) – Free text search terms to find events that match these terms in any field, except for extended properties.

  • calendar_id (Optional[str]) – Calendar identifier. Default is default_calendar specified in GoogleCalendar. To retrieve calendar IDs call the get_calendar_list(). If you want to access the primary calendar of the currently logged-in user, use the “primary” keyword.

  • kwargs – Additional API parameters. See https://developers.google.com/calendar/v3/reference/events/list#optional-parameters

Returns

Iterable of Event objects

Return type

Iterable[Event]

get_instances(recurring_event, time_min=None, time_max=None, timezone='Etc/UTC', calendar_id=None, **kwargs)

Lists instances of recurring event

Parameters

  • recurring_event – Recurring event (Event object) or id of a recurring event

  • time_min – Staring date/datetime

  • time_max – Ending date/datetime

  • timezone – Timezone formatted as an IANA Time Zone Database name, e.g. “Europe/Zurich”. By default, the computers local timezone is used if it is configured. UTC is used otherwise.

  • calendar_id (Optional[str]) – Calendar identifier. Default is default_calendar specified in GoogleCalendar. To retrieve calendar IDs call the get_calendar_list(). If you want to access the primary calendar of the currently logged-in user, use the “primary” keyword.

  • kwargs – Additional API parameters. See https://developers.google.com/calendar/v3/reference/events/instances#optional-parameters

Returns

Iterable of event objects

Return type

Iterable[Event]

get_event(event_id, calendar_id=None, **kwargs)

Returns the event with the corresponding event_id.

Parameters
Returns

The corresponding event object.

Return type

Event

add_event(event, send_updates='none', calendar_id=None, **kwargs)

Creates event in the calendar

Parameters
Returns

Created event object with id.

Return type

Event

add_quick_event(event_string, send_updates='none', calendar_id=None, **kwargs)

Creates event in the calendar by string description.

Example:

Appointment at Somewhere on June 3rd 10am-10:25am

Parameters
Returns

Created event object with id.

Return type

Event

update_event(event, send_updates='none', calendar_id=None, **kwargs)

Updates existing event in the calendar

Parameters
Returns

Updated event object.

Return type

Event

import_event(event, calendar_id=None, **kwargs)

Imports an event in the calendar

This operation is used to add a private copy of an existing event to a calendar.

Parameters
Returns

Created event object with id.

Return type

Event

move_event(event, destination_calendar_id, send_updates='none', source_calendar_id=None, **kwargs)

Moves existing event from calendar to another calendar

Parameters
Returns

Moved event object.

Return type

Event

delete_event(event, send_updates='none', calendar_id=None, **kwargs)

Deletes an event.

Parameters
get_calendar(calendar_id=None)

Returns the calendar with the corresponding calendar_id.

Parameters

calendar_id (Optional[str]) – Calendar identifier. Default is default_calendar specified in GoogleCalendar. To retrieve calendar IDs call the get_calendar_list(). If you want to access the primary calendar of the currently logged-in user, use the “primary” keyword.

Returns

The corresponding Calendar object.

Return type

Calendar

add_calendar(calendar)

Creates a secondary calendar.

Parameters

calendar (Calendar) – Calendar object.

Returns

Created calendar object with ID.

update_calendar(calendar)

Updates metadata for a calendar.

Parameters

calendar (Calendar) – Calendar object with set calendar_id

Returns

Updated calendar object

delete_calendar(calendar)

Deletes a secondary calendar.

Use clear_calendar() for clearing all events on primary calendars.

Parameters

calendar (Union[Calendar, str]) – Calendar’s ID or Calendar object with set calendar_id.

clear_calendar()

Clears a primary calendar. This operation deletes all events associated with the primary calendar of an account.

Currently, there is no way to clear a secondary calendar. You can use delete_event() method with the secondary calendar’s ID to delete events from a secondary calendar.

clear()

Kept for back-compatibility. Use clear_calendar() instead.

Clears a primary calendar. This operation deletes all events associated with the primary calendar of an account.

Currently, there is no way to clear a secondary calendar. You can use delete_event() method with the secondary calendar’s ID to delete events from a secondary calendar.

get_calendar_list(min_access_role=None, show_deleted=False, show_hidden=False)

Returns the calendars on the user’s calendar list.

Parameters

  • min_access_role (Optional[str]) – The minimum access role for the user in the returned entries. See AccessRoles The default is no restriction.

  • show_deleted (bool) – Whether to include deleted calendar list entries in the result. The default is False.

  • show_hidden (bool) – Whether to show hidden entries. The default is False.

Returns

Iterable of CalendarListEntry objects.

Return type

Iterable[CalendarListEntry]

get_calendar_list_entry(calendar_id=None)

Returns a calendar with the corresponding calendar_id from the user’s calendar list.

Parameters

calendar_id (Optional[str]) – Calendar identifier. Default is default_calendar specified in GoogleCalendar To retrieve calendar IDs call the get_calendar_list(). If you want to access the primary calendar of the currently logged-in user, use the “primary” keyword.

Returns

The corresponding CalendarListEntry object.

Return type

CalendarListEntry

add_calendar_list_entry(calendar, color_rgb_format=None)

Adds an existing calendar into the user’s calendar list.

Parameters

  • calendar (CalendarListEntry) – CalendarListEntry object.

  • color_rgb_format (Optional[bool]) – Whether to use the foreground_color and background_color fields to write the calendar colors (RGB). If this feature is used, the index-based color_id field will be set to the best matching option automatically. The default is True if foreground_color or background_color is set, False otherwise.

Returns

Created CalendarListEntry object with id.

Return type

CalendarListEntry

update_calendar_list_entry(calendar, color_rgb_format=None)

Updates an existing calendar on the user’s calendar list.

Parameters

  • calendar (CalendarListEntry) – Calendar object with set calendar_id

  • color_rgb_format (Optional[bool]) – Whether to use the foreground_color and background_color fields to write the calendar colors (RGB). If this feature is used, the index-based color_id field will be set to the best matching option automatically. The default is True if foreground_color or background_color is set, False otherwise.

Returns

Updated calendar list entry object

Return type

CalendarListEntry

delete_calendar_list_entry(calendar)

Removes a calendar from the user’s calendar list.

Parameters

calendar (Union[Calendar, CalendarListEntry, str]) – Calendar’s ID or Calendar/CalendarListEntry object with the set calendar_id.

list_event_colors()

A global palette of event colors, mapping from the color ID to its definition. An Event may refer to one of these color IDs in its color_id field.

Return type

dict

list_calendar_colors()

A global palette of calendar colors, mapping from the color ID to its definition. CalendarListEntry resource refers to one of these color IDs in its color_id field.

Return type

dict

get_settings()

Returns user settings for the authenticated user.

Return type

Settings

class gcsa.google_calendar.SendUpdatesMode

Possible values of the mode for sending updates or invitations to attendees.

  • ALL - Send updates to all participants. This is the default value.

  • EXTERNAL_ONLY - Send updates only to attendees not using google calendar.

  • NONE - Do not send updates.

ALL = 'all'
EXTERNAL_ONLY = 'externalOnly'
NONE = 'none'