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

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:

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:

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:

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.

google : Synchronization with Google¶

Plugin settings¶

Model mixins¶

Choices and choicelists¶

Database objects¶

Interaction with other plugins¶

Synchronization¶

`google` : Synchronization with Google¶

Plugin settings ¶

Model mixins ¶

Choices and choicelists ¶

Database objects ¶

Interaction with other plugins ¶

Synchronization ¶