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.

synchronize_with_google(self, user: Optional[User]) bool

Decides whether the entry is synchronizable with Google.

Parameters:

user (Optional[User]) -- The user who's Google account lino is synchronizing with.

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:
Returns:

A tuple of the saved calendar entry and the default room.

Return type:

tuple[Calendar, Room]

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.

Parameters:

user -- An instance of User

Returns:

Generator[Event, None, None]

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 related Room and Guest 's.

Parameters:
Returns:

Saved calendar event entry.

Return type:

Event.

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 a GuestState.

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 an EntryState or google.guest_state_translation when the input parameter is an instance of a GuestState. 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

sync_token

Token given by Google to sync later Event entries on the subscribed calendar.

Type:

str

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 or Event 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 an Event 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.