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 (date | datetime | BeautifulDate) – Staring date/datetime

  • time_max (date | datetime | BeautifulDate) – Ending date/datetime

  • order_by (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 (str) – Free text search terms to find events that match these terms in any field, except for extended properties.

  • calendar_id (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 (Event | str) – Recurring event or instance of recurring event (Event object) or id of the recurring event

  • time_min (date | datetime | BeautifulDate) – Staring date/datetime

  • time_max (date | datetime | BeautifulDate) – Ending date/datetime

  • 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.

  • calendar_id (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 (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 (Calendar | CalendarListEntry | 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 (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 (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 (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 (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 (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_acl_rules(calendar_id=None, show_deleted=False)

Returns the rules in the access control list for the calendar.

Parameters:

  • calendar_id (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.

  • show_deleted (bool) – Whether to include deleted ACLs in the result. Deleted ACLs are represented by role equal to “none”. Deleted ACLs will always be included if syncToken is provided. Optional. The default is False.

Returns:

Iterable of AccessControlRule objects

Return type:

Iterable[AccessControlRule]

get_acl_rule(rule_id, calendar_id=None)

Returns an access control rule

Parameters:

  • rule_id (str) – ACL rule identifier.

  • calendar_id (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 AccessControlRule object

Return type:

AccessControlRule

add_acl_rule(acl_rule, send_notifications=True, calendar_id=None)

Adds access control rule

Parameters:

  • acl_rule (AccessControlRule) – AccessControlRule object.

  • send_notifications (bool) – Whether to send notifications about the calendar sharing change. The default is True.

  • calendar_id (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:

Created access control rule with id.

update_acl_rule(acl_rule, send_notifications=True, calendar_id=None)

Updates given access control rule

Parameters:

  • acl_rule (AccessControlRule) – AccessControlRule object.

  • send_notifications (bool) – Whether to send notifications about the calendar sharing change. The default is True.

  • calendar_id (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:

Updated access control rule.

delete_acl_rule(acl_rule, calendar_id=None)

Deletes access control rule.

Parameters:

  • acl_rule (AccessControlRule | str) – Access control rule’s ID or AccessControlRule object with set acl_id.

  • calendar_id (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.

get_free_busy(resource_ids=None, *, time_min=None, time_max=None, timezone='Etc/UTC', group_expansion_max=None, calendar_expansion_max=None, ignore_errors=False)

Returns free/busy information for a set of calendars and/or groups.

Parameters:

  • resource_ids (str | List[str]) – Identifier or list of identifiers of calendar(s) and/or group(s). Default is default_calendar specified in GoogleCalendar.

  • time_min (date | datetime | BeautifulDate) – The start of the interval for the query.

  • time_max (date | datetime | BeautifulDate) – The end of the interval for the query.

  • 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.

  • group_expansion_max (int) – Maximal number of calendar identifiers to be provided for a single group. An error is returned for a group with more members than this value. Maximum value is 100.

  • calendar_expansion_max (int) – Maximal number of calendars for which FreeBusy information is to be provided. Maximum value is 50.

  • ignore_errors (bool) – Whether errors related to calendars and/or groups should be ignored. If False FreeBusyQueryError is raised in case of query related errors. If True, related errors are stored in the resulting FreeBusy object. Default is False. Note, request related errors (e.x. authentication error) will not be ignored regardless of the ignore_errors value.

Returns:

FreeBusy object.

Return type:

FreeBusy

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'