google
: Synchronization with Google¶
This page gives developer information about the lino_xl.lib.google
plugin,
which adds google calendar and contacts synchronization functionality to your
Lino application. See also google : Synchronization with Google.
This is a tested document. The following instructions are used for initialization:
>>> from lino import startup
>>> startup('lino_book.projects.noi1e.settings.demo')
>>> from lino.api.doctest import *
Plugin settings¶
This plugin adds the following settings, which a site maintainer can
configure in the settings.py
.
- google.client_secret_file¶
JSON formatted GoogleAPI client secret.
- Type:
Path
Obtainable for google. See: this thread.
- google.scopes¶
The access list to google API.
- Type:
list
>>> pprint(dd.plugins.google.scopes) ['https://www.googleapis.com/auth/userinfo.profile', 'https://www.googleapis.com/auth/userinfo.email', 'https://www.googleapis.com/auth/contacts', 'https://www.googleapis.com/auth/user.addresses.read', 'https://www.googleapis.com/auth/user.birthday.read', 'https://www.googleapis.com/auth/user.gender.read', 'https://www.googleapis.com/auth/user.phonenumbers.read', 'https://www.googleapis.com/auth/calendar', 'https://www.googleapis.com/auth/calendar.events']
- google.entry_state_translation¶
Translate
EntryState
into google status.- Type:
tuple[tuple[str, tuple[str, ...]]]
- Value:
(('confirmed', ('confirmed', )), ('tentative', ('tentative', )), ('cancelled', ('cancelled', )))
The first value of the inner tuples is the corresponding Google event status for the EntryState names in the second value (which is also a tuple).
- google.guest_state_translation¶
Translate between possible values in Google and Lino guest state choices.
- Type:
tuple[tuple[str, tuple[str, ...]]
- Value:
(('needsAction', ('needsAction', )), ('declined', ('decliend', )), ('tentative', ('tentative', )), ('accepted', ('accepted', )))
Add more items on the second item of the inner toples so that they translate to the first item on the inner tuple.
Model mixins¶
- class lino_xl.lib.google.GoogleSynchronized¶
Google's related database models inherits from this mixin.
- google_id¶
Used in making reference to the object stored in Google's database.
- class lino_xl.lib.google.GoogleCalendarSynchronized¶
A subclass of
GoogleSynchronized
.- modified¶
Keeps the timestamp of the last modification of the
Calendar
as an entry.- Type:
datetime.datetime
Helps in synchronization with Google.
- insert_or_update_into_google(self, crs, user) None ¶
Insert or updates the calendar entry with google.
- Parameters:
crs -- Google calendar API resource. Can be obtained by calling Resource.calendars()
user -- An instance of
User
- classmethod get_outward_insert_update_queryset(cls, user)¶
This method returns a queryset of
Calendar
that are not stored in Google or should be updated.- Parameters:
user -- An instance of
User
- Returns:
django.db.models.query.QuerySet
- classmethod delete_google_calendar(cls, cal: dict) None ¶
This method deletes a
Calendar
at sync time when the calendar is deleted from the Google calendar.- Parameters:
cal (dict) -- Dictionary of attributes of the deleted calendar.
Also deletes the
DeletedEntry
record from the database to keep it clean.
- classmethod sync_deleted_records(cls) None ¶
Deletes calendars by looking at
DeletedEntry
from Google calendar.
- classmethod insert_or_update_google_calendar(cls, cal: dict, user=None)¶
Inserts or updates a calendar entry and the default
Room
.- Parameters:
cls -- A subclass of
GoogleCalendarSynchronized
.cal (dict) -- A dictionary of calendar attibutes.
user (
User
) -- A lino user.
- Returns:
A tuple of the saved calendar entry and the default room.
- Return type:
- class lino_xl.lib.google.GoogleCalendarEventSynchronized¶
A subclass of
GoogleSynchronized
.- classmethod delete_google_event(cls, cal: dict) None ¶
This method deletes a
Event
at sync time when the event is deleted from the Google calendar.- Parameters:
event (dict) -- Dictionary of attributes of the deleted event.
Also deletes the
DeletedEntry
record from the database to keep it clean.
- classmethod sync_deleted_records(cls) None ¶
Deletes events by looking at
DeletedEntry
from Google calendar.
- classmethod get_outward_insert_update_queryset(cls, user)¶
This method yields
Event
(s) which are not stored in Google or should be updated.
- insert_or_update_into_google(self, ers, user) None ¶
Insert or updates the events into Google.
- Parameters:
ers -- Google calendar API resource. Can be obtained by calling Resource.events()
user -- An instance of
User
- classmethod insert_or_update_google_event(cls, event: dict, room, user)¶
Inserts or updates a calendar
Event
and relatedRoom
andGuest
's.- Parameters:
cls -- A subclass of
GoogleCalendarEventSynchronized
.event (dict) -- A dictionary of an
Event
attibutes.room (
Room
.) -- The room this event belongs to.user (
User
) -- A lino user.
- Returns:
Saved calendar event entry.
- Return type:
Choices and choicelists¶
Defines ChoiceList(s) and some utility functions.
- lino_xl.lib.google.google_status(state: Union[EntryState, GuestState]) Optional[str] ¶
- Parameters:
state -- Takes either a
EntryState
or aGuestState
.- Returns:
An str as status acceptable by Google.
Internally it works by looking at state_translation either
google.entry_state_translation
when the input parameter is an instance of anEntryState
orgoogle.guest_state_translation
when the input parameter is an instance of aGuestState
. It returns None if a value is not found for a corresponding state.>>> google.google_status(cal.EntryStates.tentative) 'tentative'
- class lino_xl.lib.google.AccessRoles¶
Keeps the choices for the type of access to a Google calendar.
Used for checking whether a user can insert into a Google calendar. The available values are freeBusyReader (read public info only), reader, writer and owner.
>>> rt.show(google.AccessRoles) ======= ================ ================== value name text ------- ---------------- ------------------ p freeBusyReader Free busy reader r reader Reader w writer Writer o owner Owner ======= ================ ==================
Database objects¶
- class lino_xl.lib.google.CalendarSubscription¶
A subclass of
BaseSubscription
.- modified¶
Keeps the last modification timestamp.
Used to make a reference to un-synced objects.
- primary¶
A boolean field which indicated whether calendar referenced in this subscription is the primary calendar for the user in Google.
- access_role¶
User's access role on the subscribed calendar.
See:
AccessRoles
- page_token¶
Whether the
sync_token
is a nextSyncToken or a nextPageToken.- Type:
bool
- Value:
False
- class lino_xl.lib.google.DeletedEntry¶
Keeps a record of the natively deleted
Calendar
orEvent
for deleting from Google when the next sync is run.- calendar¶
A boolean field which says whether the deleted item is a Calendar if not it is an Event.
- Type:
bool
- Value:
False
- event_id¶
Takes the value of the
Event.google_id
when the deleted record is anEvent
otherwise an empty string.- Type:
str
- calendar_id¶
Takes the value of the
Calendar.google_id
- Type:
str
If the deleted record is an Event it takes the google_id from the Calendar in which the deleted Event belongs to.
Interaction with other plugins¶
This plugin injects a field
calendar_sync_token
into the
lino.modlib.users.User
model:
- class lino.modlib.users.User
- calendar_sync_token¶
The next sync token for the user's calendar synchronization.
This is obtained from the finish of an ongoing synchronization, done by the
sync_google_calendar()
function.- Type:
Optional[str]
Synchronization¶
Calendar synchronization in Lino with Google works in both ways. Lino application can fetch calendar entries from Google as well as it can insert and update calendar entries in Google.
- lino_xl.lib.google.get_resource(user, people: bool = False) googleapiclient.discovery.Resource ¶
Builds and returns a Google API resource for calendar and contacts.
- Parameters:
user -- An instance of
User
.people (bool) -- Whether to build a people api instead of calendar api.
- Returns:
Google API resource.
- Return type:
googleapiclient.discovery.Resource
- lino_xl.lib.google.sync_google_calendar(user) None ¶
Does calendar synchronization with Google.
Utilizes the methods in Model mixins and the Database objects in doing the synchronization.
- Parameters:
user (
User
) -- Lino user.