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

Project links

Data verified by PyPI on Jul 19, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for allen.porter from gravatar.com allen.porter

Credits

Author: Allen Porter

GitHub Statistics

Data verified by PyPI on Jul 19, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.13

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gcal_sync-9.1.0.tar.gz (44.1 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

gcal_sync-9.1.0-py3-none-any.whl (30.0 kB view details)

Uploaded Python 3

File details

Details for the file gcal_sync-9.1.0.tar.gz.

File metadata

  • Download URL: gcal_sync-9.1.0.tar.gz
  • Upload date:
  • Size: 44.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for gcal_sync-9.1.0.tar.gz
Algorithm Hash digest
SHA256 4869a06f0d98900ed21b6a71137c02b61a1173eb534290d3eea23588d606cc5b
MD5 3032d117d352cc88bddb041c531bc16a
BLAKE2b-256 b027acbeefc801800c5ff4d257cb42e25bd3d49fdc093d2271db1b23450fdd58

See more details on using hashes here.

Provenance

The following attestation bundles were made for gcal_sync-9.1.0.tar.gz:

Publisher: publish.yaml on allenporter/gcal_sync

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gcal_sync-9.1.0-py3-none-any.whl.

File metadata

  • Download URL: gcal_sync-9.1.0-py3-none-any.whl
  • Upload date:
  • Size: 30.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for gcal_sync-9.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 abe31a0eccfa2b9aded91061726951d7388b1112b38f48e023ccf2741e5940f4
MD5 7ff2df6f18d4f9ad54b59ed8a8ca69db
BLAKE2b-256 18e96899c7a12c6442e1881ad0f732ebda51b8eea59c3974fb72dfedf2fae4cd

See more details on using hashes here.

Provenance

The following attestation bundles were made for gcal_sync-9.1.0-py3-none-any.whl:

Publisher: publish.yaml on allenporter/gcal_sync

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

9.1.0 This release

2 files

9.0.0

2 files

8.0.0

2 files

7.2.0

2 files

7.1.0

2 files

7.0.1

2 files

7.0.0

2 files

6.2.0

2 files

6.1.6

2 files

6.1.5

2 files

6.1.4

2 files

6.1.3

2 files

6.1.2

2 files

6.1.1

2 files

6.1.0

2 files

6.0.4

2 files

6.0.3

2 files

6.0.2

2 files

6.0.1

2 files

6.0.0

2 files

5.0.0

2 files

4.2.1

2 files

4.2.0

2 files

4.1.4

2 files

4.1.3

2 files

4.1.2

2 files

4.1.1

2 files

4.1.0

2 files

4.0.4

2 files

4.0.3

2 files

4.0.2

2 files

4.0.1

2 files

4.0.0

2 files

3.0.0

2 files

2.2.4

2 files

2.2.3

2 files

2.2.2

2 files

2.2.0

2 files

2.1.0

2 files

2.0.0

2 files

1.1.0

2 files

1.0.0

2 files

0.11.0

2 files

0.10.0

2 files

0.9.1

2 files

0.9.0

2 files

0.8.1

2 files

0.8.0

2 files

0.7.1

2 files

0.7.0

2 files

0.6.3

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.0

2 files

0.4.1

2 files

0.4.0

2 files

0.3.1

2 files

0.3.0

2 files

0.2.2

2 files

0.2.1

2 files

0.2.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page