An asyncio python library for the [Google Calendar API](https://developers.google.com/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](https://allenporter.github.io/gcal_sync/).
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](https://developers.google.com/workspace/guides/auth-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.
```python
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](https://allenporter.github.io/gcal_sync/)
# 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:
```python
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.
```python
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
```bash
$ 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
```
Raw data
{
"_id": null,
"home_page": "https://github.com/allenporter/gcal_sync",
"name": "gcal-sync",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Allen Porter",
"author_email": "allen.porter@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/fc/b7/c7c4d9a4b3e87e9a8a9479684e32b39c032ad1c0f2d40ed2d5ed64c52f1f/gcal_sync-6.2.0.tar.gz",
"platform": null,
"description": "An asyncio python library for the [Google Calendar API](https://developers.google.com/calendar/api). This library provides a simplified\nGoogle Calendar API that is lighter weight and more streamlined compared to using\naiogoogle, and increased reliability by supporting efficient sync and reading\nfrom local storage. See the [API Documentation](https://allenporter.github.io/gcal_sync/).\n\nThe focus of this API is on making it simple to access the most relevant parts of Google\nCalendar, for doing useful things. It may not support everything in the API however it\nshould be easy to extend to do more as needed.\n\n# Quickstart\n\nIn order to use the library, you'll need to do some work yourself to get authentication\ncredentials. This depends a lot on the context (e.g. redirecting to use OAuth via web)\nbut should be easy to incorporate using Google's python authentication libraries. See\nGoogle's [Authentication and authorization overview](https://developers.google.com/workspace/guides/auth-overview) for details.\n\nYou will implement `gcal_sync.AbstractAuth` to provide an access token. Your implementation\nwill handle any necessary refreshes. You can invoke the service with your auth implementation\nto access the API.\n\n```python\nfrom gcal_sync.auth import AbstractAuth\n\n\nclass MyAuthImpl(gcal_sync.AbstractAuth):\n\n def __init__(self, websession: aiohttp.ClientSession) -> None:\n \"\"\"Initialize MyAuthimpl.\"\"\"\n super().__init__(websession)\n\n async def async_get_access_token(self) -> str:\n \"\"\"Return a valid access token.\"\"\"\n return ...\n\n\nservice = GoogleCalendarService(MyAuthImpl(...))\ncalendar = await service.async_get_calendar(\"primary\")\n```\n\nSee `gcal_sync.api.GoogleCalendarService` for more details on API calls and see the\noverall [documentation](https://allenporter.github.io/gcal_sync/)\n\n# Fetching Events\n\nEvents can be fetched using the `gcal_sync.api.ListEventsRequest` which can filter\nevents based on time or search criteria. The `GoogleCalendarService` supports paging\nthrough events using an aync generator like in this example below:\n\n```python\nfrom gcal_sync.api import ListEventsRequest\n\nrequest = ListEventsRequest(\n calendar_id=calendar.id,\n search=\"Holiday\",\n)\nresult = await service.async_list_events(request)\nasync for result_page in result:\n for event in result_page.items:\n print(event.summary)\n```\n\nUsing the async generator avoids the need to manually handle paging and page tokens,\nbut that is also available if needed. Recurring events are expanded on the server by\ndefault, so you don't have to worry about handling them yourself.\n\n# Synchronization\n\nIf you require a high read rate to the events, then it may be more efficient to\nfirst sync down the calendar then query local events. Any recurring events are\nexpanded at query time by the local library by interpreting the recurrence rules\non the synced event.\n\n```python\nfrom gcal_sync.sync import CalendarListSyncManager\n\nsync = CalendarEventSyncManager(service)\n# Run when you want to sync down the latest set of events\nawait sync.run()\n\n# Iterate over events in the local store\ntimeline = await sync.store_service.async_get_timeline()\nfor event in timeline:\n print(event.summary)\n```\n\nSee `gcal_sync.sync` for more details.\n\n# Development Environment\n\n```bash\n$ python3 -m venv venv\n$ source venv/bin/activate\n$ pip3 install -r requirements_dev.txt\n\n# Run tests\n$ py.test\n\n# Run tests with code coverage\n$ py.test --cov-report=term-missing --cov=gcal_sync\n```\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A python library for syncing Google Calendar to local storage",
"version": "6.2.0",
"project_urls": {
"Homepage": "https://github.com/allenporter/gcal_sync"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3619c5d1b79e0888fb33cd7e95de986ce6e001ac42287a0f840bb4e1e091ea5b",
"md5": "77261e4a32c2fb1f54fbe3c3d3837977",
"sha256": "b3feb4c2eec5472f8321908377e8d3c482fd0411c650b094c2c1aa5fc177db75"
},
"downloads": -1,
"filename": "gcal_sync-6.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "77261e4a32c2fb1f54fbe3c3d3837977",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 28332,
"upload_time": "2024-10-22T03:20:00",
"upload_time_iso_8601": "2024-10-22T03:20:00.549388Z",
"url": "https://files.pythonhosted.org/packages/36/19/c5d1b79e0888fb33cd7e95de986ce6e001ac42287a0f840bb4e1e091ea5b/gcal_sync-6.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fcb7c7c4d9a4b3e87e9a8a9479684e32b39c032ad1c0f2d40ed2d5ed64c52f1f",
"md5": "978de4dfee48e02b72c6034c3f91537f",
"sha256": "33ab2d39127ebcb4ac1c3672b5c4bd2fd6d3eb0560ac0f4b4a71bfa9a920d34c"
},
"downloads": -1,
"filename": "gcal_sync-6.2.0.tar.gz",
"has_sig": false,
"md5_digest": "978de4dfee48e02b72c6034c3f91537f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 40869,
"upload_time": "2024-10-22T03:20:01",
"upload_time_iso_8601": "2024-10-22T03:20:01.636191Z",
"url": "https://files.pythonhosted.org/packages/fc/b7/c7c4d9a4b3e87e9a8a9479684e32b39c032ad1c0f2d40ed2d5ed64c52f1f/gcal_sync-6.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-22 03:20:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "allenporter",
"github_project": "gcal_sync",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "gcal-sync"
}
JSON
