From 31de9176317217aa88be7bc596e2aadc7593c262 Mon Sep 17 00:00:00 2001 From: Fabio Manganiello Date: Thu, 18 Jan 2024 23:46:30 +0100 Subject: [PATCH] [Google] Updated documentation of Google plugins. Expanded explanation of the desktop vs. headless authentication process and where the credential files are supposed to be copied if the user opts for a non-automatic authentication flow. --- platypush/plugins/google/__init__.py | 33 ++++++++++--- platypush/plugins/google/calendar/__init__.py | 33 ++++++++++--- platypush/plugins/google/drive/__init__.py | 33 ++++++++++--- platypush/plugins/google/fit/__init__.py | 47 ++++++++++++++----- platypush/plugins/google/mail/__init__.py | 33 ++++++++++--- 5 files changed, 142 insertions(+), 37 deletions(-) diff --git a/platypush/plugins/google/__init__.py b/platypush/plugins/google/__init__.py index 0500a03f2..95a6569af 100644 --- a/platypush/plugins/google/__init__.py +++ b/platypush/plugins/google/__init__.py @@ -29,15 +29,36 @@ class GooglePlugin(Plugin): 5 Select "Desktop app", enter whichever name you like, and click "Create". 6. Click on the "Download JSON" icon next to your newly created client ID. + Save the JSON file under + ``/credentials/google/client_secret.json``. - 7. Generate a credentials file for the required scope: + 7.1. If you're running the service on a desktop environment, then you + can just start the application. A browser window will open and + you'll be asked to authorize the application - you may be prompted + with a warning because you are running a personal and potentially + unverified application. After authorizing the application, the + process will save the credentials under + ``/credentials/google/.json`` and proceed + with the plugin initialization. - .. code-block:: bash + 7.2. If you're running the service on a headless environment, or you + prefer to manually generate the credentials file before copying to + another machine, you can run the following command: - mkdir -p /credentials/google - python -m platypush.plugins.google.credentials \ - 'calendar.readonly' \ - /credentials/google/client_secret.json + .. code-block:: bash + + mkdir -p /credentials/google + python -m platypush.plugins.google.credentials \ + 'calendar.readonly,gmail.modify' \ + [--noauth_local_webserver] \ + /credentials/google/client_secret.json + + When launched with ``--noauth_local_webserver``, the script will + start a local webserver and print a URL that should be opened in + your browser. After authorizing the application, you may be + prompted with a code that you should copy and paste back to the + script. Otherwise, if you're running the script on a desktop, a + browser window will be opened automatically. """ diff --git a/platypush/plugins/google/calendar/__init__.py b/platypush/plugins/google/calendar/__init__.py index 665a5196c..64d57df93 100644 --- a/platypush/plugins/google/calendar/__init__.py +++ b/platypush/plugins/google/calendar/__init__.py @@ -28,15 +28,36 @@ class GoogleCalendarPlugin(GooglePlugin, CalendarInterface): 5 Select "Desktop app", enter whichever name you like, and click "Create". 6. Click on the "Download JSON" icon next to your newly created client ID. + Save the JSON file under + ``/credentials/google/client_secret.json``. - 7. Generate a credentials file for the required scope: + 7.1. If you're running the service on a desktop environment, then you + can just start the application. A browser window will open and + you'll be asked to authorize the application - you may be prompted + with a warning because you are running a personal and potentially + unverified application. After authorizing the application, the + process will save the credentials under + ``/credentials/google/.json`` and proceed + with the plugin initialization. - .. code-block:: bash + 7.2. If you're running the service on a headless environment, or you + prefer to manually generate the credentials file before copying to + another machine, you can run the following command: - mkdir -p /credentials/google - python -m platypush.plugins.google.credentials \ - 'calendar.readonly' \ - /credentials/google/client_secret.json + .. code-block:: bash + + mkdir -p /credentials/google + python -m platypush.plugins.google.credentials \ + 'calendar.readonly' \ + [--noauth_local_webserver] \ + /credentials/google/client_secret.json + + When launched with ``--noauth_local_webserver``, the script will + start a local webserver and print a URL that should be opened in + your browser. After authorizing the application, you may be + prompted with a code that you should copy and paste back to the + script. Otherwise, if you're running the script on a desktop, a + browser window will be opened automatically. """ diff --git a/platypush/plugins/google/drive/__init__.py b/platypush/plugins/google/drive/__init__.py index 7e61de8df..d5ea5f96a 100644 --- a/platypush/plugins/google/drive/__init__.py +++ b/platypush/plugins/google/drive/__init__.py @@ -28,15 +28,36 @@ class GoogleDrivePlugin(GooglePlugin): 5 Select "Desktop app", enter whichever name you like, and click "Create". 6. Click on the "Download JSON" icon next to your newly created client ID. + Save the JSON file under + ``/credentials/google/client_secret.json``. - 7. Generate a credentials file for the required scope: + 7.1. If you're running the service on a desktop environment, then you + can just start the application. A browser window will open and + you'll be asked to authorize the application - you may be prompted + with a warning because you are running a personal and potentially + unverified application. After authorizing the application, the + process will save the credentials under + ``/credentials/google/.json`` and proceed + with the plugin initialization. - .. code-block:: bash + 7.2. If you're running the service on a headless environment, or you + prefer to manually generate the credentials file before copying to + another machine, you can run the following command: - mkdir -p /credentials/google - python -m platypush.plugins.google.credentials \ - 'drive,drive.appfolder,drive.photos.readonly' \ - /credentials/google/client_secret.json + .. code-block:: bash + + mkdir -p /credentials/google + python -m platypush.plugins.google.credentials \ + 'drive,drive.appfolder,drive.photos.readonly' \ + [--noauth_local_webserver] \ + /credentials/google/client_secret.json + + When launched with ``--noauth_local_webserver``, the script will + start a local webserver and print a URL that should be opened in + your browser. After authorizing the application, you may be + prompted with a code that you should copy and paste back to the + script. Otherwise, if you're running the script on a desktop, a + browser window will be opened automatically. """ diff --git a/platypush/plugins/google/fit/__init__.py b/platypush/plugins/google/fit/__init__.py index 17dbc1a07..f8a36fc6c 100644 --- a/platypush/plugins/google/fit/__init__.py +++ b/platypush/plugins/google/fit/__init__.py @@ -25,22 +25,43 @@ class GoogleFitPlugin(GooglePlugin): 5 Select "Desktop app", enter whichever name you like, and click "Create". 6. Click on the "Download JSON" icon next to your newly created client ID. + Save the JSON file under + ``/credentials/google/client_secret.json``. - 7. Generate a credentials file for the required scope: + 7.1. If you're running the service on a desktop environment, then you + can just start the application. A browser window will open and + you'll be asked to authorize the application - you may be prompted + with a warning because you are running a personal and potentially + unverified application. After authorizing the application, the + process will save the credentials under + ``/credentials/google/.json`` and proceed + with the plugin initialization. - .. code-block:: bash + 7.2. If you're running the service on a headless environment, or you + prefer to manually generate the credentials file before copying to + another machine, you can run the following command: - $ mkdir -p /credentials/google - $ roles=" - fitness.activity.read, - fitness.body.read, - fitness.body_temperature.read, - fitness.heart_rate.read, - fitness.sleep.read, - fitness.location.read - " - $ python -m platypush.plugins.google.credentials "$roles" \ - /credentials/google/client_secret.json + .. code-block:: bash + + $ mkdir -p /credentials/google + $ roles=" + fitness.activity.read, + fitness.body.read, + fitness.body_temperature.read, + fitness.heart_rate.read, + fitness.sleep.read, + fitness.location.read + " + $ python -m platypush.plugins.google.credentials "$roles" \ + [--noauth_local_webserver] \ + /credentials/google/client_secret.json + + When launched with ``--noauth_local_webserver``, the script will + start a local webserver and print a URL that should be opened in + your browser. After authorizing the application, you may be + prompted with a code that you should copy and paste back to the + script. Otherwise, if you're running the script on a desktop, a + browser window will be opened automatically. """ diff --git a/platypush/plugins/google/mail/__init__.py b/platypush/plugins/google/mail/__init__.py index c8e1355b8..ab1749563 100644 --- a/platypush/plugins/google/mail/__init__.py +++ b/platypush/plugins/google/mail/__init__.py @@ -37,15 +37,36 @@ class GoogleMailPlugin(GooglePlugin): 5 Select "Desktop app", enter whichever name you like, and click "Create". 6. Click on the "Download JSON" icon next to your newly created client ID. + Save the JSON file under + ``/credentials/google/client_secret.json``. - 7. Generate a credentials file for the required scope: + 7.1. If you're running the service on a desktop environment, then you + can just start the application. A browser window will open and + you'll be asked to authorize the application - you may be prompted + with a warning because you are running a personal and potentially + unverified application. After authorizing the application, the + process will save the credentials under + ``/credentials/google/.json`` and proceed + with the plugin initialization. - .. code-block:: bash + 7.2. If you're running the service on a headless environment, or you + prefer to manually generate the credentials file before copying to + another machine, you can run the following command: - mkdir -p /credentials/google - python -m platypush.plugins.google.credentials \ - 'gmail.modify' \ - /credentials/google/client_secret.json + .. code-block:: bash + + mkdir -p /credentials/google + python -m platypush.plugins.google.credentials \ + 'gmail.modify' \ + [--noauth_local_webserver] \ + /credentials/google/client_secret.json + + When launched with ``--noauth_local_webserver``, the script will + start a local webserver and print a URL that should be opened in + your browser. After authorizing the application, you may be + prompted with a code that you should copy and paste back to the + script. Otherwise, if you're running the script on a desktop, a + browser window will be opened automatically. """