An asyncio python library for the Google Calendar API. This library provides a simplified Google Calendar API that is lighter weight and more streamlined compared to using aiogoogle, and increased reliability by supporting efficient sync and reading from local storage. See the API Documentation.
The focus of this API is on making it simple to access the most relevant parts of Google Calendar, for doing useful things. It may not support everything in the API however it should be easy to extend to do more as needed.
Quickstart
In order to use the library, you'll need to do some work yourself to get authentication credentials. This depends a lot on the context (e.g. redirecting to use OAuth via web) but should be easy to incorporate using Google's python authentication libraries. See Google's Authentication and authorization overview for details.
You will implement gcal_sync.AbstractAuth to provide an access token. Your implementation
will handle any necessary refreshes. You can invoke the service with your auth implementation
to access the API.
from gcal_sync.auth import AbstractAuth
class MyAuthImpl(gcal_sync.AbstractAuth):
def __init__(self, websession: aiohttp.ClientSession) -> None:
"""Initialize MyAuthimpl."""
super().__init__(websession)
async def async_get_access_token(self) -> str:
"""Return a valid access token."""
return ...
service = GoogleCalendarService(MyAuthImpl(...))
calendar = await service.async_get_calendar("primary")
See gcal_sync.api.GoogleCalendarService for more details on API calls and see the
overall documentation
Fetching Events
Events can be fetched using the gcal_sync.api.ListEventsRequest which can filter
events based on time or search criteria. The GoogleCalendarService supports paging
through events using an aync generator like in this example below:
from gcal_sync.api import ListEventsRequest
request = ListEventsRequest(
calendar_id=calendar.id,
search="Holiday",
)
result = await service.async_list_events(request)
async for result_page in result:
for event in result_page.items:
print(event.summary)
Using the async generator avoids the need to manually handle paging and page tokens, but that is also available if needed. Recurring events are expanded on the server by default, so you don't have to worry about handling them yourself.
Synchronization
If you require a high read rate to the events, then it may be more efficient to first sync down the calendar then query local events. Any recurring events are expanded at query time by the local library by interpreting the recurrence rules on the synced event.
from gcal_sync.sync import CalendarListSyncManager
sync = CalendarEventSyncManager(service)
# Run when you want to sync down the latest set of events
await sync.run()
# Iterate over events in the local store
timeline = await sync.store_service.async_get_timeline()
for event in timeline:
print(event.summary)
See gcal_sync.sync for more details.
Development Environment
$ python3 -m venv venv
$ source venv/bin/activate
$ pip3 install -r requirements_dev.txt
# Run tests
$ py.test
# Run tests with code coverage
$ py.test --cov-report=term-missing --cov=gcal_sync
1 maintainer
Metadata
1 maintainer
Release files for gcal-sync 9.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| gcal_sync-9.1.1.tar.gz | 44.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| gcal_sync-9.1.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 74.4 kB
Release files / gcal_sync-9.1.1.tar.gz
| Download URL | gcal_sync-9.1.1.tar.gz |
|---|---|
| Size | 44.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8e0ac9edbf56d6e2060a0f8a83e97d6837b33545b955418bab412f5e6f638f06
|
|
BLAKE2b-256 checksum How to use checksums |
835c4665b62551021eaa169741fe9ffdd75d2fe3b6afc549a379b10161594824
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency logRelease files / gcal_sync-9.1.1-py3-none-any.whl
| Download URL | gcal_sync-9.1.1-py3-none-any.whl |
|---|---|
| Size | 30.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b61b45ce9632af79115344c3977a8de3c099a55212832b9b958da2f20358c25d
|
|
BLAKE2b-256 checksum How to use checksums |
b108a6eaba6ce799a7361449f3aa03873da94b6351fb4cc0e87a4aff050b74ee
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency log
