Google Calendar Simple API

To create recurring events in gcsa, use the gcsa.recurrence.Recurrence module. The module provides methods that return strings in RRULE format. These strings can be passed to the recurrence parameter of an Event object as either a single string or a list of strings.

There are 8 primary methods for defining recurrence rules:

• rule: Defines the recurrence rule.
• exclude_rule: Defines excluded dates/datetimes.
• dates: Includes specific dates or a list of dates.
• exclude_dates: Excludes specific dates or a list of dates.
• times: Includes specific datetimes or a list of datetimes.
• exclude_times: Excludes specific datetimes or a list of datetimes.
• periods: Includes specific periods or a list of periods.
• exclude_periods: Excludes specific periods or a list of periods.

Note: All exclude_{method} counterparts follow the same format and parameters as their base {method} versions.

from gcsa.event import Event
from gcsa.recurrence import Recurrence, DAILY

# Single rule
Event('Breakfast',
      (1/Jan/2020)[9:00],
      (1/Jan/2020)[10:00],
      recurrence=Recurrence.rule(freq=DAILY))

# Multiple rules (including exclusions)
Event('Breakfast',
      (1/Jan/2019)[9:00],
      (1/Jan/2020)[9:00],
      recurrence=[
         Recurrence.rule(freq=DAILY),
         Recurrence.exclude_rule(by_week_day=[SU, SA])
      ])

To automate adding events to your Google Calendar, use the GoogleCalendar class to manage the connection and the Event class to define individual calendar entries. You can iterate through a range of dates (using libraries like beautiful_date) and call gc.add_event(e) for each event you wish to create.

This example demonstrates how to schedule a series of daily push-up goals starting from the next Monday.

from gcsa.google_calendar import GoogleCalendar
from gcsa.event import Event
from beautiful_date import D, drange, days, MO

gc = GoogleCalendar()

PUSH_UPS_COUNT = [
    5, 5, 0, 5, 10, 0, 10,
    0, 12, 12, 0, 15, 15, 0,
    20, 24, 0, 25, 30, 0, 32,
    35, 35, 0, 38, 40, 0, 42,
    45, 50
]

# starting next Monday (of course)
# +1 days for the case that today is Monday
start = D.today()[9:00] + 1 * days + MO
end = start + len(PUSH_UPS_COUNT) * days

for day, push_ups in zip(drange(start, end), PUSH_UPS_COUNT):
    e = Event(
        f'{push_ups} Push-Ups' if push_ups else 'Rest',
        start=day,
        minutes_before_popup_reminder=5
    )
    gc.add_event(e)

Manage how calendars appear in a user's personal list using CalendarListEntry objects.

Get the user's calendar list

Retrieve the collection of calendars in the user's list. You can filter by access role and visibility:

from gcsa.calendar import AccessRoles

for calendar in gc.get_calendar_list(min_access_role=AccessRoles.READER, show_deleted=True, show_hidden=True):
    print(calendar)

Get a calendar list entry

Retrieve the entry for the default calendar or a specific ID:

# Default
entry = gc.get_calendar_list_entry()

# By ID
entry = gc.get_calendar_list_entry('calendar_id')

Add a calendar to the list

You can create a CalendarListEntry directly or convert an existing Calendar object:

from gcsa.calendar import CalendarListEntry

# Direct creation
entry = CalendarListEntry(calendar_id='calendar_id', summary_override='Holidays in Czechia')
gc.add_calendar_list_entry(entry)

# From a Calendar object
from gcsa.calendar import Calendar
calendar = Calendar(calendar_id='calendar_id', summary='Original Summary')
entry = calendar.to_calendar_list_entry(summary_override='Holidays in Czechia')
gc.add_calendar_list_entry(entry)

Update and Delete list entries

# Update
entry.summary_override = 'New Summary'
gc.update_calendar_list_entry(entry)

# Delete (supports Calendar, CalendarListEntry, or ID)
gc.delete_calendar_list_entry(calendar)
gc.delete_calendar_list_entry(entry)
gc.delete_calendar_list_entry('<calendar_id>')

from gcsa.google_calendar import GoogleCalendar
from gcsa.calendar import CalendarListEntry, AccessRoles

gc = GoogleCalendar()

# Get list
for entry in gc.get_calendar_list(min_access_role=AccessRoles.READER):
    print(entry)

# Add entry
entry = CalendarListEntry(calendar_id='id', summary_override='New Name')
gc.add_calendar_list_entry(entry)

# Update entry
entry.summary_override = 'Updated Name'
gc.update_calendar_list_entry(entry)

# Delete entry
gc.delete_calendar_list_entry('id')

When creating a new Event, you can specify attendees using the attendees parameter. You can pass a single Attendee object, a single email string, or a list containing both Attendee objects and email strings. If you pass a string, the library will automatically create an Attendee instance for you.

To configure an Attendee object manually, use the Attendee class which supports display_name and additional_guests.

from gcsa.attendee import Attendee
from gcsa.event import Event

# Option 1: Using an Attendee object
attendee = Attendee(
    'attendee@gmail.com',
    display_name='Friend',
    additional_guests=3
)

event = Event('Meeting',
              start=(17/Jul/2020)[12:00],
              attendees=attendee)

# Option 2: Using a simple email string
event = Event('Meeting',
              start=(17/Jul/2020)[12:00],
              attendees='attendee@gmail.com')

# Option 3: Using a list of mixed types
event = Event('Meeting',
              start=(17/Jul/2020)[12:00],
              attendees=[
                  'attendee@gmail.com',
                  Attendee('attendee2@gmail.com', display_name='Friend')
              ])