Fix googlecalendar's misleading first run semantics (#689)

* ...

* docs

* ...

* pep8.... everytime

* i broke docs

* derp

docs/conf.py

@@ -44,6 +44,7 @@ MOCK_MODULES = [
     "httplib2",
     "oauth2client",
     "apiclient",
+    "googleapiclient",
     "googleapiclient.errors",
     "vlc",
     "dateutil.tz",

i3pystatus/calendar/google.py

@@ -2,15 +2,18 @@ import datetime
 from datetime import timezone
 
 import httplib2
-import oauth2client
+from oauth2client import file as file_, client, tools
 import pytz
-from apiclient import discovery
+from googleapiclient import discovery
 from dateutil import parser
 from googleapiclient.errors import HttpError
 from i3pystatus.calendar import CalendarBackend, CalendarEvent, formatter
 from i3pystatus.core.util import user_open, require, internet
 
 
+SCOPES = 'https://www.googleapis.com/auth/calendar.readonly'
+
+
 class GoogleCalendarEvent(CalendarEvent):
     def __init__(self, google_event):
         self.id = google_event['id']
@@ -47,7 +50,14 @@ class Google(CalendarBackend):
     Calendar backend for interacting with Google Calendar.
 
     Requires the Google Calendar API package - https://developers.google.com/google-apps/calendar/quickstart/python.
-    Additionally requires the `colour`, `httplib2`, `oauth2client`, `pytz`, `apiclient` and `dateutil` modules.
+    Additionally requires the `colour`, `httplib2`, `oauth2client`, `pytz`, `google-api-python-client` and `dateutil` modules.
+
+    The first time this module is ran, you will need to specify the location of `credentials.json` (as credentials_json)
+    acquired from: https://developers.google.com/google-apps/calendar/quickstart/python
+    this will open a browser window for auth, and save a token to `credential_path`. you will need to reload i3poystatus
+    afterwards
+
+    If you already have a token `credentials_json` is not required (though highly recomended incase your token gets broken)
 
     .. rubric:: Available formatters
 
@@ -57,12 +67,14 @@ class Google(CalendarBackend):
     """
 
     settings = (
-        ('credential_path', 'Path to credentials'),
+        ('credential_path', 'Path to save credentials to (auto generated the first time this module is ran)'),
+        ('credentials_json', 'path to credentials.json (generated by google)'),
         ('days', 'Only show events between now and this many days in the future'),
     )
 
     required = ('credential_path',)
 
+    credentials_json = None
     days = 7
 
     def init(self):
@@ -80,7 +92,14 @@ class Google(CalendarBackend):
 
     def connect_service(self):
         self.logger.debug("Connecting Service..")
-        self.credentials = oauth2client.file.Storage(self.credential_path).get()
+        store = file_.Storage(self.credential_path)
+        self.credentials = store.get()
+
+        # if the module is being ran for the first time, open up the browser to authenticate
+        if not self.credentials or self.credentials.invalid:
+            flow = client.flow_from_clientsecrets(self.credentials_json, SCOPES)
+            self.credentials = tools.run_flow(flow, store)
+
         self.service = discovery.build('calendar', 'v3', http=self.credentials.authorize(httplib2.Http()))
 
     def refresh_events(self):