Calendar

Calendar

Calendar(auth: GoogleAuth, calendar_id: str = 'primary')

High-level Calendar client.

Example

auth = GoogleAuth() auth.authenticate()

cal = Calendar(auth)

Get upcoming events

for event in cal.get_upcoming(days=7): print(f"{event.start}: {event.summary}")

Create event

cal.create_event( summary="Meeting", start=datetime(2026, 1, 30, 10, 0), end=datetime(2026, 1, 30, 11, 0), )

Initialize Calendar client.

Parameters:

Name	Type	Description	Default
auth	GoogleAuth	GoogleAuth instance with valid credentials	required
calendar_id	str	Default calendar ID ("primary" for main calendar)	'primary'

service property

service: Any

Lazy-load Calendar API service.

iter_events

iter_events(time_min: datetime | None = None, time_max: datetime | None = None, calendar_id: str | None = None, max_results: int | None = 250, single_events: bool = True, order_by: str = 'startTime') -> Iterator[Event]

Lazily yield events in a time range, following result pages.

Parameters:

Name	Type	Description	Default
time_min	datetime | None	Start of range (default: now). Naive datetimes are UTC.	None
time_max	datetime | None	End of range	None
calendar_id	str | None	Calendar ID (default: primary)	None
max_results	int | None	Maximum events to yield (None = all)	250
single_events	bool	Expand recurring events	True
order_by	str	Sort order (startTime or updated)	'startTime'

get_events

get_events(time_min: datetime | None = None, time_max: datetime | None = None, calendar_id: str | None = None, max_results: int | None = 250, single_events: bool = True, order_by: str = 'startTime') -> list[Event]

Get events in a time range.

Parameters:

Name	Type	Description	Default
time_min	datetime | None	Start of range (default: now). Naive datetimes are UTC.	None
time_max	datetime | None	End of range	None
calendar_id	str | None	Calendar ID (default: primary)	None
max_results	int | None	Maximum events to return (None = all)	250
single_events	bool	Expand recurring events	True
order_by	str	Sort order (startTime or updated)	'startTime'

Returns:

Type	Description
list[Event]	List of Event objects

get_upcoming

get_upcoming(days: int = 7, calendar_id: str | None = None, max_results: int = 100) -> list[Event]

Get upcoming events.

Parameters:

Name	Type	Description	Default
days	int	Number of days ahead (default: 7)	7
calendar_id	str | None	Calendar ID	None
max_results	int	Maximum events	100

Returns:

Type	Description
list[Event]	List of upcoming events

get_today

get_today(calendar_id: str | None = None) -> list[Event]

Get today's events, where "today" is in GSUITE_DEFAULT_TIMEZONE.

get_event

get_event(event_id: str, calendar_id: str | None = None) -> Event | None

Get a specific event by ID.

get_calendars

get_calendars() -> list[CalendarEntity]

Get all accessible calendars.

create_event

create_event(summary: str, start: datetime | date, end: datetime | date | None = None, description: str | None = None, location: str | None = None, attendees: list[str] | None = None, calendar_id: str | None = None, all_day: bool = False, recurrence: list[str] | None = None, meet: bool = False, send_updates: SendUpdates = 'none') -> Event

Create a new event.

Parameters:

Name	Type	Description	Default
summary	str	Event title	required
start	datetime | date	Start time (datetime) or date (for all-day)	required
end	datetime | date | None	End time (default: start + 1 hour)	None
description	str | None	Event description	None
location	str | None	Event location	None
attendees	list[str] | None	List of attendee emails	None
calendar_id	str | None	Calendar to create in	None
all_day	bool	Create as all-day event	False
recurrence	list[str] | None	RRULE lines, e.g. ["RRULE:FREQ=WEEKLY;BYDAY=MO,WE"]	None
meet	bool	Attach a new Google Meet link (see Event.meet_link)	False
send_updates	SendUpdates	Email attendees: "all", "externalOnly" or "none"	'none'

Returns:

Type	Description
Event	Created Event

quick_add

quick_add(text: str, calendar_id: str | None = None, send_updates: SendUpdates = 'none') -> Event

Create an event from natural language: "Lunch with Ana tomorrow at 1pm".

update_event

update_event(event_id: str, summary: str | None = None, start: datetime | date | None = None, end: datetime | date | None = None, description: str | None = None, location: str | None = None, attendees: list[str] | None = None, all_day: bool = False, calendar_id: str | None = None, send_updates: SendUpdates = 'none') -> Event

Change an event. Only the arguments you pass are updated.

Moving an event: pass start (and end, or it becomes 1 hour long). attendees replaces the whole list.

Returns:

Type	Description
Event	The updated Event

get_instances

get_instances(event_id: str, time_min: datetime | None = None, time_max: datetime | None = None, max_results: int | None = 250, calendar_id: str | None = None) -> list[Event]

Occurrences of a recurring event (optionally within a time range).

get_free_busy

get_free_busy(time_min: datetime, time_max: datetime, calendars: list[str] | None = None) -> dict[str, list[dict[str, datetime | None]]]

Busy intervals per calendar.

Parameters:

Name	Type	Description	Default
calendars	list[str] | None	Calendar IDs or emails ("me" = your primary calendar). Default: this client's calendar.	None

Returns:

Type	Description
dict[str, list[dict[str, datetime | None]]]	{calendar: [{"start": datetime, "end": datetime}, ...]}. A calendar
dict[str, list[dict[str, datetime | None]]]	you can't see comes back with no busy times and a logged warning.

delete_event

delete_event(event_id: str, calendar_id: str | None = None, send_updates: SendUpdates = 'none') -> bool

Delete an event.

Parameters:

Name	Type	Description	Default
send_updates	SendUpdates	Email attendees about the cancellation: "all", "externalOnly" or "none"	'none'

Returns:

Type	Description
bool	True if deleted, False if it didn't exist. Other failures (auth,
bool	rate limit, ...) raise instead of looking like "not found".

Event dataclass

Event(id: str, summary: str, description: str | None = None, location: str | None = None, start: datetime | None = None, end: datetime | None = None, all_day: bool = False, recurring: bool = False, recurrence: list[str] | None = None, attendees: list[Attendee] = list(), organizer: str | None = None, calendar_id: str = 'primary', html_link: str | None = None, status: str = 'confirmed', meet_link: str | None = None, timezone: str | None = None, created: datetime | None = None, updated: datetime | None = None, creator: str | None = None, recurring_event_id: str | None = None)

Calendar event.

Represents a single calendar event with all its metadata.

duration_minutes property

duration_minutes: int | None

Get event duration in minutes.

is_all_day property

is_all_day: bool

Check if this is an all-day event.

is_recurring property

is_recurring: bool

Check if this is a recurring event.

CalendarEntity dataclass

CalendarEntity(id: str, summary: str, description: str | None = None, time_zone: str | None = None, primary: bool = False, access_role: str = 'reader', background_color: str | None = None, foreground_color: str | None = None)

A calendar.

Represents a single calendar (primary or shared).

is_primary property

is_primary: bool

Check if this is the user's primary calendar.

is_writable property

is_writable: bool

Check if user can write to this calendar.